pip-run 12.5.0

Module Script Runner

Perhaps the most powerful usage of pip-run is its ability to invoke executable modules and packages via runpy (aka python -m):

$ pip-run cowsay -- -m cowsay "moove over, pip-run"

  -------------------
< moove over, pip-run >
  -------------------
   \   ^__^
    \  (oo)\_______
       (__)\       )\/\
           ||----w |
           ||     ||

Module Executable Runner

Some package tools, like ranger, are invoked with a unique executable instead of a module. pip-run can run an executable from a package if it is prependend by a !:

$ pip-run ranger-fm -- '!ranger'

Command Runner

Note that everything after the – is passed to the python invocation, so it’s possible to have a one-liner that runs under a dependency context:

$ python -m pip-run requests -- -c "import requests; print(requests.get('https://pypi-hypernode.com/project/pip-run').status_code)"
200

As long as pip-run is installed in each of Python environments on the system, this command can be readily repeated on the other python environments by specifying the relevant interpreter:

$ py -3.7 -m pip-run ...

Script Runner

pip-run can run a Python file with indicated dependencies. Because arguments after -- are passed directly to the Python interpreter and because the Python interpreter will run any script, invoking a script with dependencies is easy. Consider this script “myscript.py”:

#!/usr/bin/env python

import requests

req = requests.get('https://pypi-hypernode.com/project/pip-run')
print(req.status_code)

To invoke it while making sure requests is present:

$ pip-run requests – myscript.py

pip-run will make sure that requests is installed then invoke the script in a Python interpreter configured with requests and its dependencies.

For added convenience when running scripts, pip-run will infer the beginning of Python parameters if it encounters a filename of a Python script that exists, allowing for omission of the -- for script invocation:

$ pip-run requests myscript.py

Script-declared Dependencies

Building on Script Runner above, pip-run also allows dependencies to be declared in the script itself so that the user need not specify them at each invocation.

To declare dependencies in a script, add a __requires__ variable or # Requirements: section to the script:

#!/usr/bin/env python

__requires__ = ['requests']

# or

# Requirements:
# requests

# or (PEP 723)

# /// script
# dependencies = ['requests']
# ///

import requests

req = requests.get('https://pypi-hypernode.com/project/pip-run')
print(req.status_code)

With that declaration in place, one can now invoke pip-run without declaring any parameters to pip:

$ pip-run myscript.py
200

The format for requirements must follow PEP 508.

Single-script Tools and Shebang Support

Combined with in-script dependencies, pip-run can be used as a shebang to create fully self-contained scripts that install and run their own dependencies, as long as pip-run is installed on the system PATH. Consider, for example, the pydragon script:

#!/usr/bin/env pip-run
__requires__ = ['requests', 'beautifulsoup4', 'cowsay']
import requests
from bs4 import BeautifulSoup as BS
import cowsay
res = requests.get('https://python.org')
b = BS(res.text, 'html.parser')
cowsay.dragon(b.find("div", class_="introduction").get_text())

This executable script is available in the repo as examples/pydragon (for Unix) and examples/pydragon.py (for Windows [2]). Executing this script is equivalent to executing pip-run pydragon.

By default, the script will assemble the dependencies on each invocation, which may be inconvenient for a script. See Environment Persistence for a technique to persist the assembled dependencies across invocations. One may inject PIP_RUN_MODE=persist in the shebang, but be aware that doing so breaks Windows portability.

Other Script Directives

pip-run also recognizes a global __index_url__ attribute. If present, this value will supply --index-url to pip with the attribute value, allowing a script to specify a custom package index:

#!/usr/bin/env python

__requires__ = ['my_private_package']
__index_url__ = 'https://my.private.index/'

import my_private_package
...

Extracting Requirements

After having used pip-run to run scripts, it may be desirable to extract the requirements from the __requires__ variable or # Requirements: section of a script to install those more permanently. pip-run provides a routine to facilitate this case:

$ py -m pip_run.read-deps examples/pydragon
requests beautifulsoup4 cowsay

On Unix, it is possible to pipe this result directly to pip:

$ pip install $(py -m pip_run.read-deps examples/pydragon)

To generate a requirements.txt file, specify a newline separator:

$ py -m pip_run.read-deps --separator newline examples/pydragon > requirements.txt

And since pipenv uses the same syntax, the same technique works for pipenv:

$ pipenv install $(python -m pip_run.read-deps script.py)

Interactive Interpreter

pip-run also offers a painless way to run a Python interactive interpreter in the context of certain dependencies:

$ /clean-install/python -m pip-run boto
>>> import boto
>>>

Experiments and Testing

Because pip-run provides a single-command invocation, it is great for experiments and rapid testing of various package specifications.

Consider a scenario in which one wishes to create an environment where two different versions of the same package are installed, such as to replicate a broken real-world environment. Stack two invocations of pip-run to get two different versions installed:

$ pip-run keyring==21.8.0 -- -m pip-run keyring==22.0.0 -- -c "import importlib.metadata, pprint; pprint.pprint([dist._path for dist in importlib.metadata.distributions() if dist.metadata['name'] == 'keyring'])"
[PosixPath('/var/folders/03/7l0ffypn50b83bp0bt07xcch00n8zm/T/pip-run-a3xvd267/keyring-22.0.0.dist-info'),
PosixPath('/var/folders/03/7l0ffypn50b83bp0bt07xcch00n8zm/T/pip-run-1fdjsgfs/keyring-21.8.0.dist-info')]

IPython Inference

If IPython is specified as one of the dependencies, the Python interpreter will be launched via IPython (using -m IPython) for interactive mode. This behaviour may be toggled off by setting the environment variable PIP_RUN_IPYTHON_MODE=ignore.