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.

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.

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.

python_export
Usage: python_export [ ] ...

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.

python_wrapper_setup
Usage: python_wrapper_setup [ [ ]]

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 2to3 executables 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.

EPYTHON
The basename of Python interpreter. Used as main identifier of the active implementation in Gentoo. Affects python-exec and many eclass functions.

Example values: python2.7, python3.3, pypy-c2.0, jython2.7

PYTHON
The full path to the Python interpreter. Seldom used by autotools-based build systems. The preferred way of invoking Python within ebuilds.

Example values: /usr/bin/python2.7, /usr/bin/pypy-c2.0

PYTHON_SITEDIR
Getter: python_get_sitedir [ ]

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 [ ]

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 [ ]

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 [ ]

Getter: python_get_LIBS [ ]

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_doexe
Usage: python_doexe ... Usage: python_newexe  Usage: python_scriptinto 

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.

python_doscript
Usage: python_doscript ... Usage: python_newscript  Usage: python_scriptinto 

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.

python_domodule
Usage: python_domodule ... Usage: python_moduleinto 

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. Default is to install into site-packages.

python_doheader
Usage: python_doheader ...

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_optimize
Usage: python_optimize [ ...]

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).

python_fix_shebang
Usage: python_fix_shebang [-f|--force] [-q|--quiet] ...

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.

python_is_python3
Usage: python_is_python3 [ ]

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 [ ]

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.