This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Project:Python/python-utils-r1
python-utils-r1 provides all the common utility functions that are used within all of -r1 suite eclasses. This eclass is seldom (if ever) inherited directly. Instead, its API is exposed via other eclasses.
Python build environment
Introductory information
Python build environment describes the environment setup that is necessary to properly build packages against specific version of Python, or run Python scripts using it. Python build environment consists of a number of environment variables and often a helper directories.
The most minimal Python build environment is established through EPYTHON variable.
Establishing the build environment
Implicit build environment
The Python build environment is initialized implicitly by many other eclasses. The functions which establish it and list of enabled variables are listed in the following table.
| Eclass | Function | Variables | |
|---|---|---|---|
| distutils-r1 | (sub-phases) | EPYTHON, PYTHON, BUILD_DIR, MULTIBUILD_*, PYTHONPATH, executable & pkg-config wrappers | |
| python-r1 | python_foreach_impl | EPYTHON, PYTHON, BUILD_DIR, MULTIBUILD_*, executable & pkg-config wrappers | |
| python_parallel_foreach_impl | |||
| python_export_best | user-specified variables (default: EPYTHON, PYTHON) | ||
| (called directly) | python_setup | EPYTHON, PYTHON, executable & pkg-config wrappers | |
| python-any-r1 | python-any-r1_pkg_setup | ||
| python-single-r1 | python-single-r1_pkg_setup | ||
python_export
Usage: python_export [<impl>] <variable>...
Exports the specified build environment variables. If the first argument specifies a valid Python implementation (either in PYTHON_COMPAT or EPYTHON form), the variables are exported for specified implementation. Otherwise, they are exported for the implementation listed in current value of EPYTHON environment variable.
This command can be used both to initialize a new build environment and to export additional variables for the current build environment. Most of the variables also have getters which can be used instead of python_export.
src_configure() {
local PYTHON_SITEDIR
python_export PYTHON_SITEDIR
econf --with-python-sitedir="${PYTHON_SITEDIR}"
}python_wrapper_setup
Usage: python_wrapper_setup [<path> [<impl>]]
Prepare Python executable and pkg-config file wrappers, and add them to PATH and PKG_CONFIG_PATH (remember to localize the variables before calling!). The wrapper tree will be created in specified directory if any, or otherwise in ${T}/${EPYTHON}. The wrappers will match the implementation passed as second argument or specified in EPYTHON environment variable.
The following wrappers are created:
- python and python2 or python3 executables,
- python-config and python2-config or python3-config executables if available,
- 2to3 executable if available,
- python.pc and python2.pc or python3.pc pkg-config files if available.
python_export_utf8_locale
Attempts to export a usable UTF-8 locale in the LC_CTYPE variable. Does nothing if LC_ALL is defined, or if the current locale uses a UTF-8 charmap. This may be used to work around the quirky open() behavior of python3.
Return value: 0 on success, 1 on failure.
Build environment variables
EPYTHON
The basename of Python interpreter. Used as main identifier of the active implementation in Gentoo. Affects python-exec and many eclass functions. The preferred way of invoking Python within ebuilds, as it relies on PATH lookup, which among other things is more portable on Gentoo Prefix setups, for instance.
Example values: python2.7, python3.3, pypy-c2.0, jython2.7
PYTHON
The full path to the Python interpreter. Sometimes required by autotools and cmake-based build systems.
Example values: /usr/bin/python2.7, /usr/bin/pypy-c2.0
PYTHON_SITEDIR
Getter: python_get_sitedir [<impl>]
The Python interpreter's site-packages directory, the directory where third-party Python modules shall be installed. Includes EPREFIX.
Example value: /usr/lib64/python2.7/site-packages
PYTHON_INCLUDEDIR
Getter: python_get_includedir [<impl>]
The Python interpreter's header files directory. This is the directory where implementation-specific headers can be found. Includes EPREFIX.
Example value: /usr/include/python2.7
PYTHON_LIBPATH
Getter: python_get_library_path [<impl>]
Full path to the Python interpreter's dynamic library (for linking against Python). Includes EPREFIX. Available for CPython only.
Example value: /usr/lib64/libpython2.7.so
PYTHON_CFLAGS, PYTHON_LIBS
Getter: python_get_CFLAGS [<impl>]
Getter: python_get_LIBS [<impl>]
Respectively the C compiler build and linking flags for linking against the Python interpreter. Available for CPython only. Requires the implementation to be installed.
In modern CPython versions, uses pkg-config. In Python 2.6, uses python-config.
PYTHON_CONFIG
Getter: python_get_PYTHON_CONFIG [<impl>]
Full path to the python-config utility, with appropriate ABI suffix. Available for CPython only.
Example value: /usr/bin/python3.4m-config
Install functions
python_doexe
Usage: python_doexe <file>...
Usage: python_newexe <file> <new-name>
Usage: python_scriptinto <path>
Install the specified implementation-specific executables. The executables will be wrapped for current Python implementation.
python_newexe can be used to install an executable under new name. python_scriptinto changes the executable install path (defaults to /usr/bin). All paths are implicitly prefixed with EPREFIX.
This function is intended for files other than Python scripts (executables, bash scripts). For Python scripts, python_doscript should be used instead.
src_install() {
python_foreach_impl python_doexe foo.py
}python_doscript
Usage: python_doscript <file>...
Usage: python_newscript <file> <new-name>
Usage: python_scriptinto <path>
Install the specified scripts. The scripts will be wrapped and the shebang on its underlying copy will be adjusted for the current implementation.
python_newscript can be used to install a script under new name. python_scriptinto changes the script install path (defaults to /usr/bin). All paths are implicitly prefixed with EPREFIX.
src_install() {
python_foreach_impl python_doscript foo.py
}python_domodule
Usage: python_domodule <file-or-directory>...
Usage: python_moduleinto <path>
Install the specified Python modules or packages (directories). All Python modules will be byte-compiled. Directories (packages) will be installed recursively, including all files (not only modules).
python_moduleinto changes the module install path. It can either take an absolute path (starting with a slash), or a path relative to site-packages directory. The relative path can either use a slash (/) or a dot (.) as the path separator. The default is to install into site-packages.
src_install() {
python_moduleinto foo.barmatic
python_foreach_impl python_domodule lib/*.py
}python_doheader
Usage: python_doheader <file>...
Install the specified header files into implementation-specific header directory. The directory is added to the compiler search path when Python extensions or programs linking against Python are being built.
python_install() {
#...
python_doheader libImaging/{Imaging.h,ImPlatform.h}
}python_optimize
Usage: python_optimize [<directory>...]
Byte-compile Python modules. If any directories are provided, modules in those directories will be byte-compiled. Otherwise, all directories in Python search path (sys.path) inside D will be used.
All directories need to be specified using absolute paths (including ${D} if appropriate). Python modules inside installation image will be compiled with target filesystem paths embedded (with ${D} stripped).
Other functions
python_fix_shebang
Usage: python_fix_shebang [-f|--force] [-q|--quiet] <path>...
Fixes shebangs in Python scripts to match the current interpreter.
Both files and directories can be specified as paths. If directories are provided, they are processed recursively. Only files with Python shebangs are modified.
If --force is passed, the function will replace shebangs matching incompatible Python implementations. For example, it will replace python2 with python3.4. Otherwise, such an attempt will result in a fatal error.
If --quiet is passed, the function will not output the modified files. Otherwise, it will verbosely report each modified file.
src_install() {
default
python_fix_shebang "${ED}"usr/bin
}python_is_python3
Usage: python_is_python3 [<impl>]
Determines whether the passed implementation (or ${EPYTHON} if none passed) uses a dialect of Python 3. Returns 0 if it is, 1 otherwise (Python 2 dialect).
python_is_installed
Usage: python_is_installed [<impl>]
Determines whether the passed Python implementation (or ${EPYTHON} if none passed) is installed in the system, with USE flags matching PYTHON_REQ_USE. Returns 0 if it is installed, 1 otherwise.