Gentoo Development Guide

PYTHON-UTILS-R1

Section: portage (5)
Updated: Oct 2014
Index Return to Main Contents
 

NAME

python-utils-r1 - 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-r1 Developer's Guide: http://www.gentoo.org/proj/en/Python/python-r1/dev-guide.xml  

FUNCTIONS

python_export [<impl>] <variables>...
Set and export the Python implementation-relevant variables passed as parameters.

The optional first parameter may specify the requested Python implementation (either as PYTHON_TARGETS value, e.g. python2_7, or an EPYTHON one, e.g. python2.7). If no implementation passed, the current one will be obtained from ${EPYTHON}.

The variables which can be exported are: PYTHON, EPYTHON, PYTHON_SITEDIR. They are described more completely in the eclass variable documentation.

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

If you just need to have PYTHON_SITEDIR set (and exported), then it is better to use python_export() directly instead.

python_get_includedir [<impl>]
Obtain and print the include path for the given implementation. If no implementation is provided, ${EPYTHON} will be used.

If you just need to have PYTHON_INCLUDEDIR set (and exported), then it is better to use python_export() directly instead.

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_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 current scriptroot. The new value will be stored in the 'python_scriptroot' environment variable. The new value need be relative to the installation root (${ED}).

Alternatively, you can set the variable directly.

python_doexe <files>...
Install the given executables into current python_scriptroot, 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 current python_scriptroot, 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 current python_scriptroot, 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 current python_scriptroot 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 current module root. The new value will be stored in the 'python_moduleroot' environment variable. The new value need be relative to the site-packages root.

Alternatively, you can set the variable directly.

python_domodule <files>...
Install the given modules (or packages) into the current python_moduleroot. The list can mention both modules (files) and packages (directories). All listed files will be installed for all enabled implementations, and compiled afterwards.

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_wrapper_setup [<path> [<impl>]]
Create proper 'python' executable and pkg-config wrappers (if available) in the directory named by <path>. Set up PATH and PKG_CONFIG_PATH appropriately. <path> defaults to ${T}/${EPYTHON}.

The wrappers will be created for implementation named by <impl>, or for one named by ${EPYTHON} if no <impl> passed.

If the named directory contains a python symlink already, it will be assumed to contain proper wrappers already and only environment setup will be done. If wrapper update is requested, the directory shall be removed first.

python_is_python3 [<impl>]
Check whether <impl> (or ${EPYTHON}) is a Python3k variant (i.e. uses syntax and stdlib of Python 3.*).

Returns 0 (true) if it is, 1 (false) otherwise.

python_fix_shebang [-f|--force] [-q|--quiet] <path>...
Replace the shebang in Python scripts with the current Python implementation (EPYTHON). If a directory is passed, works recursively on all Python scripts.

Only files having a 'python*' shebang will be modified. Files with other shebang will either be skipped when working recursively on a directory or treated as error when specified explicitly.

Shebangs matching explicitly current Python version will be left unmodified. Shebangs requesting another Python version will be treated as fatal error, unless --force is given.

--force causes the function to replace even shebangs that require incompatible Python version. --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.

 

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

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

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
PYTHON_SITEDIR
The path to Python site-packages directory.

Set and exported on request using python_export().

Example value:

/usr/lib64/python2.7/site-packages
PYTHON_INCLUDEDIR
The path to Python include directory.

Set and exported on request using python_export().

Example value:

/usr/include/python2.7
PYTHON_LIBPATH
The path to Python library.

Set and exported on request using python_export(). Valid only for CPython.

Example value:

/usr/lib64/libpython2.7.so
PYTHON_CFLAGS
Proper C compiler flags for building against Python. Obtained from pkg-config or python-config.

Set and exported on request using python_export(). Valid only for CPython. Requires a proper build-time dependency on the Python implementation and on pkg-config.

Example value:

-I/usr/include/python2.7
PYTHON_LIBS
Proper C compiler flags for linking against Python. Obtained from pkg-config or python-config.

Set and exported on request using python_export(). Valid only for CPython. Requires a proper build-time dependency on the Python implementation and on pkg-config.

Example value:

-lpython2.7
PYTHON_PKG_DEP
The complete dependency on a particular Python package as a string.

Set and exported on request using python_export().

Example value:

dev-lang/python:2.7[xml]
PYTHON_SCRIPTDIR
The location where Python scripts must be installed for current impl.

Set and exported on request using python_export().

Example value:

/usr/lib/python-exec/python2.7
python_scriptroot
The current script destination for python_doscript(). The path is relative to the installation root (${ED}).

When unset, ${DESTTREE}/bin (/usr/bin by default) will be used.

Can be set indirectly through the python_scriptinto() function.

Example:

src_install() {
  local python_scriptroot=${GAMES_BINDIR}
  python_foreach_impl python_doscript foo
}
python_moduleroot
The current module root for python_domodule(). The path can be either an absolute system path (it must start with a slash, and ${ED} will be prepended to it) or relative to the implementation's site-packages directory (then it must start with a non-slash character).

When unset, the modules will be installed in the site-packages root.

Can be set indirectly through the python_moduleinto() function.

Example:

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

AUTHORS

Author: Michał Górny <mgorny@gentoo.org>
Based on work of: Krzysztof Pawlik <nelchael@gentoo.org>
 

MAINTAINERS

Python team <python@gentoo.org>
 

REPORTING BUGS

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

FILES

/usr/portage/eclass/python-utils-r1  

SEE ALSO

ebuild(5)
http://sources.gentoo.org/eclass/python-utils-r1?view=log


 

Index

NAME
DESCRIPTION
FUNCTIONS
ECLASS VARIABLES
AUTHORS
MAINTAINERS
REPORTING BUGS
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 03:25:05 GMT, October 31, 2014