PYTHON-UTILS-R1.ECLASS

Section: eclass-manpages (5)
Updated: Nov 2024
Index Return to Main Contents

NAME

python-utils-r1.eclass - Utility functions for packages with Python parts.

DESCRIPTION

A utility eclass providing functions to query Python implementations, install Python modules and scripts.

This eclass does not set any metadata variables nor export any phase functions. It can be inherited safely.

For more information, please see the Python Guide: https://projects.gentoo.org/python/guide/

SUPPORTED EAPIS

7 8

FUNCTIONS

python_get_stdlib [<impl>]

Obtain and print the 'stdlib' path for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

python_get_sitedir [<impl>]

Obtain and print the 'site-packages' path for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

python_get_includedir [<impl>]

Obtain and print the include path for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

python_get_library_path [<impl>]

Obtain and print the Python library path for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

Please note that this function can be used with CPython only. Use in another implementation will result in a fatal failure.

python_get_CFLAGS [<impl>]

Obtain and print the compiler flags for building against Python, for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

Please note that this function can be used with CPython only. It requires Python and pkg-config installed, and therefore proper build-time dependencies need be added to the ebuild.

python_get_LIBS [<impl>]

Obtain and print the compiler flags for linking against Python, for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

Please note that this function can be used with CPython only. It requires Python and pkg-config installed, and therefore proper build-time dependencies need be added to the ebuild.

python_get_PYTHON_CONFIG [<impl>]

Obtain and print the PYTHON_CONFIG location for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

Please note that this function can be used with CPython only. It requires Python installed, and therefore proper build-time dependencies need be added to the ebuild.

python_get_scriptdir [<impl>]

Obtain and print the script install path for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

python_optimize [<directory>...]

Compile and optimize Python modules in specified directories (absolute paths). If no directories are provided, the default system paths are used (prepended with ${D}).

python_scriptinto <new-path>

Set the directory to which files passed to python_doexe(), python_doscript(), python_newexe() and python_newscript() are going to be installed. The new value needs to be relative to the installation root (${ED}).

If not set explicitly, the directory defaults to /usr/bin.

Example:

src_install() {
  python_scriptinto /usr/sbin
  python_foreach_impl python_doscript foo
}

python_doexe <files>...

Install the given executables into the executable install directory, for the current Python implementation (${EPYTHON}).

The executable will be wrapped properly for the Python implementation, though no shebang mangling will be performed.

python_newexe <path> <new-name>

Install the given executable into the executable install directory, for the current Python implementation (${EPYTHON}).

The executable will be wrapped properly for the Python implementation, though no shebang mangling will be performed. It will be renamed to <new-name>.

python_doscript <files>...

Install the given scripts into the executable install directory, for the current Python implementation (${EPYTHON}).

All specified files must start with a 'python' shebang. The shebang will be converted, and the files will be wrapped properly for the Python implementation.

Example:

src_install() {
  python_foreach_impl python_doscript ${PN}
}

python_newscript <path> <new-name>

Install the given script into the executable install directory for the current Python implementation (${EPYTHON}), and name it <new-name>.

The file must start with a 'python' shebang. The shebang will be converted, and the file will be wrapped properly for the Python implementation. It will be renamed to <new-name>.

Example:

src_install() {
  python_foreach_impl python_newscript foo.py foo
}

python_moduleinto <new-path>

Set the Python module install directory for python_domodule(). The <new-path> can either be an absolute target system path (in which case it needs to start with a slash, and ${ED} will be prepended to it) or relative to the implementation's site-packages directory (then it must not start with a slash). The relative path can be specified either using the Python package notation (separated by dots) or the directory notation (using slashes).

When not set explicitly, the modules are installed to the top site-packages directory.

In the relative case, the exact path is determined directly by each python_domodule invocation. Therefore, python_moduleinto can be safely called before establishing the Python interpreter and/or a single call can be used to set the path correctly for multiple implementations, as can be seen in the following example.

Example:

src_install() {
  python_moduleinto bar
  # installs ${PYTHON_SITEDIR}/bar/baz.py
  python_foreach_impl python_domodule baz.py
}

python_domodule <files>...

Install the given modules (or packages) into the current Python module installation directory. The list can mention both modules (files) and packages (directories). All listed files will be installed for all enabled implementations, and compiled afterwards.

The files are installed into ${D} when run in src_install() phase. Otherwise, they are installed into ${BUILD_DIR}/install location that is suitable for picking up by distutils-r1 in PEP517 mode.

Example:

src_install() {
  # (${PN} being a directory)
  python_foreach_impl python_domodule ${PN}
}

python_doheader <files>...

Install the given headers into the implementation-specific include directory. This function is unconditionally recursive, i.e. you can pass directories instead of files.

Example:

src_install() {
  python_foreach_impl python_doheader foo.h bar.h
}

python_fix_shebang [-f|--force] [-q|--quiet] <path>...

Replace the shebang in Python scripts with the full path to the current Python implementation (PYTHON, including EPREFIX). If a directory is passed, works recursively on all Python scripts found inside the directory tree.

Only files having a Python shebang (a path to any known Python interpreter, optionally preceded by env(1) invocation) will be processed. Files with any other shebang will either be skipped silently when a directory was passed, or an error will be reported for any files without Python shebangs specified explicitly.

Shebangs that are compatible with the current Python version will be mangled unconditionally. Incompatible shebangs will cause a fatal error, unless --force is specified.

--force causes the function to replace shebangs with incompatible Python version (but not non-Python shebangs). --quiet causes the function not to list modified files verbosely.

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_sphinx <directory>

Build HTML documentation using dev-python/sphinx in the specified <directory>. Takes care of disabling Intersphinx and appending to HTML_DOCS.

If <directory> is relative to the current directory, care needs to be taken to run einstalldocs from the same directory (usually ${S}).

EPYTEST_DESELECT

Specifies an array of tests to be deselected via pytest's --deselect parameter, when calling epytest. The list can include file paths, specific test functions or parametrized test invocations.

Note that the listed files will still be subject to collection, i.e. modules imported in global scope will need to be available. If this is undesirable, EPYTEST_IGNORE can be used instead.

EPYTEST_IGNORE

Specifies an array of paths to be ignored via pytest's --ignore parameter, when calling epytest. The listed files will be entirely skipped from test collection.

epytest [<args>...]

Run pytest, passing the standard set of pytest options, then --deselect and --ignore options based on EPYTEST_DESELECT and EPYTEST_IGNORE, then user-specified options.

This command dies on failure and respects nonfatal.

eunittest [<args>...]

Run unit tests using dev-python/unittest-or-fail, passing the standard set of options, followed by user-specified options.

This command dies on failure and respects nonfatal.

python_has_version [-b|-d|-r] <atom>...

A convenience wrapper for has_version() with verbose output and better defaults for use in python_check_deps().

The wrapper accepts -b/-d/-r options to indicate the root to perform the lookup on. Unlike has_version, the default is -b.

The wrapper accepts multiple package specifications. For the check to succeed, *all* specified atoms must match.

ECLASS VARIABLES

PYTHON

The absolute path to the current Python interpreter.

This variable is set automatically in the following contexts:

python-r1: Set in functions called by python_foreach_impl() or after calling python_setup().

python-single-r1: Set after calling python-single-r1_pkg_setup().

distutils-r1: Set within any of the python sub-phase functions.

Example value:

/usr/bin/python2.7

EPYTHON

The executable name of the current Python interpreter.

This variable is set automatically in the following contexts:

python-r1: Set in functions called by python_foreach_impl() or after calling python_setup().

python-single-r1: Set after calling python-single-r1_pkg_setup().

distutils-r1: Set within any of the python sub-phase functions.

Example value:

python2.7

EPYTEST_TIMEOUT

If set to a non-empty value, enables pytest-timeout plugin and sets test timeout to the specified value. This variable can be either set in ebuilds that are known to hang, or by user to prevent hangs in automated test environments. If this variable is set prior to calling distutils_enable_tests in distutils-r1, a test dependency on dev-python/pytest-timeout is added automatically.

EPYTEST_XDIST

If set to a non-empty value, enables running tests in parallel via pytest-xdist plugin. If this variable is set prior to calling distutils_enable_tests in distutils-r1, a test dependency on dev-python/pytest-xdist is added automatically.

EPYTEST_JOBS (USER VARIABLE)

Specifies the number of jobs for parallel (pytest-xdist) test runs. When unset, defaults to -j from MAKEOPTS, or the current nproc.

EPYTEST_FLAGS (USER VARIABLE)

Additional flags to pass to pytest. This is intended to be set in the environment when debugging packages (options such as -x or -s are useful here), rather than globally. It must not be set in ebuilds.

AUTHORS

Author: Michał Górny <[email protected]>
Based on work of: Krzysztof Pawlik <[email protected]>

MAINTAINERS

Python team <[email protected]>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

python-utils-r1.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, November 25, 2024

PYTHON-UTILS-R1.ECLASS

NAME

DESCRIPTION

SUPPORTED EAPIS

FUNCTIONS

ECLASS VARIABLES

AUTHORS

MAINTAINERS

REPORTING BUGS

FILES

SEE ALSO

Index