Project:Python/python-exec

python-exec is the tool used to wrap Python scripts for multiple implementations. In the process of wrapping, the original Python script is replaced by a special wrapper executable that invokes a proper version of the original script depending on which Python interpreter is used/requested.

Configuration

Local implementation overrides

To avoid having to alter the system configuration, python-exec provides support for locally altering the most preferred Python interpreter using the EPYTHON environment variable. The variable should be set to a single Python implementation name, e.g.:

user $EPYTHON=python3.5 python-thingy

This will run the application with the specified implementation if it is supported. If the script in question does not support the specified implementation, python-exec will fall back to trying the configuration files.

Running scripts directly (stronger override/emergency)

Warning
The following is considered an implementation detail. It might change in the future. Do not use it in scripts.

You can also run the wrapped script directly from an appropriate subdirectory of /usr/lib/python-exec, e.g.:

user $/usr/lib/python-exec/python3.5/python-thingy

In this case, either the script will run with specified implementation, or the command will fail because of non-existing file.

This is also useful if python-exec is broken for some reason.

Configuration files

Starting with python-exec-2.3, python-exec is configured by one or more files located in /etc/python-exec. The main system configuration is specified in python-exec.conf, and this configuration can be overrode for specific scripts by creating <script-name>.conf files.

Each of the configuration files specifies zero or more preferred implementations, one per-line, in descending preference order (i.e. the most preferred first). Additionally, implementations can be disabled from fallback use by listing their names prefixed by a hyphen (-). The implementations neither listed as preferences, nor disabled, are considered fallback implementations.

When running a script with no forced implementation (EPYTHON unset and not spawned via Python interpreter), python-exec will first try to find the script variant for preferred implementations, in order. If none of the preferred implementations are supported, python-exec falls back to trying the remaining implementations that are supported yet not disabled, in wrapper-defined order.

FILE /etc/python-exec/python-exec.confExample system configuration

# prefer python3.4
python3.4
# remaining implementations used in default order
#python3.5
#python3.3
#python2.7
# disable jython
-jython2.7

eselect-python

eselect-python provides an easy way to configure preferred/active Python interpreters. Since python-exec-2.3 / eselect-python-20160207, eselect-python alters altering python-exec.conf. Previous versions use old configuration format that was used by python.eclass wrappers, python-wrapper, and older versions of python-exec.

For new versions, the preferred method of altering configuration is to use the edit mode that opens python-exec.conf in an editor:

root #eselect python edit

In order to list all supported interpreters, in preference order:

user $eselect python list

Available Python interpreters, in order of preference:
  [1]   python3.4
  [2]   python3.5 (fallback)
  [3]   python3.3 (fallback)
  [4]   python2.7 (fallback)
  [5]   pypy3 (fallback)
  [6]   pypy (fallback)
  [7]   jython2.7 (disabled)

In order to set a new preferred interpreter, you can use:

root #eselect python set python3.5

Note that this will set the specified interpreter as the most preferred one, moving existing preferences lower.

Use in ebuilds

It is recommended to assume that the details of script wrapping are a private implementation detail and avoid relying on any specifics in ebuilds. Most of the time, the implicit wrapper support in the eclasses suffice. In particular:

• distutils-r1 sets setup.py up to install wrapped scripts into appropriate directories and creates the wrapper symlinks afterward.
• python_doexe and remaining install helpers install scripts into appropriate directories and create the wrapper symlinks.

CODE Example install of custom Python executables

python_install() {
    # perform the setup.py install call with appropriate wrapping
    distutils-r1_python_install

    # install an additional Python script, setting shebang for appropriate interpreter
    # (respects scriptdir, creates wrapper)
    python_doscript my-extra-program.py

    # install a bash script that calls python and wrap it
    # (note: if build system does not substitute `python` calls with appropriate interpreter
    # executable names, you will need to fix them yourself -- and a simple sed like below
    # will usually not suffice)
    sed -e "s:python:${EPYTHON}:" my-extra-script.bash
    python_doexe my-extra-script.bash
}