NAME
python-module —
lang/python port module
DESCRIPTION
This manual page documents the behavior of setting
MODULES=lang/python in the
ports(7)
tree.
By default, the module sets MODPY_VERSION
to the appropriate python version (depending on the existence/presence of a
‘python3’ FLAVOR), but
MODPY_VERSION may be set manually to
${MODPY_DEFAULT_VERSION_2} for legacy ports.
The module then sets MODPY_BIN,
MODPY_INCDIR, MODPY_LIBDIR,
MODPY_SITEPKG, MODPY_SETUP,
MODPY_TEST_DIR,
MODPY_TEST_LINK_SO,
MODPY_TEST_LOCALE,
MODPY_WANTLIB,
MODPY_LIB_DEPENDS,
MODPY_RUN_DEPENDS,
MODPY_TEST_DEPENDS,
MODPY_BUILD_DEPENDS, and
MODPY_ADJ_FILES accordingly.
The module also appends to
RUN_DEPENDSunlessMODPY_RUNDEPis set to No,BUILD_DEPENDSunlessMODPY_BUILDDEPis set to No orNO_BUILDis set to Yes,TEST_DEPENDSifMODPY_PYTESTis set to Yes unlessMODPY_TESTDEPis set to No.
It also appends MODPY_TEST_LOCALE to
TEST_ENV and changes to the directory specified in
MODPY_TEST_DIR (by default ${WRKSRC}) before running
tests. In addition, it can link all .so files in ${WRKSRC} if
MODPY_TEST_LINK_SO is set to Yes, which is required
if you are using tests which use Python code that loads .so files via
relative imports.
Most modern Python software can be packaged using a PEP 517 build
frontend (in the devel/py-build port). To use this,
set MODPY_PYBUILD to the name of the build backend.
If the port provides a pyproject.toml file, check
the "build-backend" line in the [build-system] section.
python-module currently supports flit, flit_core,
hatchling, hatch-vcs, jupyter_packaging, maturin, pdm, poetry-core,
setuptools and setuptools_scm. If no pyproject.toml
is provided then it probably uses setuptools. Setting
MODPY_PYBUILD adds the backend to
MODPY_BUILD_DEPENDS, and sets
MODPY_PYTEST. In cases where a less common backend
is used, or where the build backend is distributed with the software itself,
MODPY_PYBUILD can be set to ‘other’ to
use the PEP 517 mechanism without adding a dependency for a backend.
Older ports using setuptools still set
MODPY_SETUPTOOLS to Yes, which appends to
MODPY_BUILD_DEPENDS and calls the relevant commands
to build (these ports are built using the deprecated mechanism of calling
setup.py directly). Arguments can be passed to
setup.py during configure with
MODPY_SETUP_ARGS. Extra arguments to the build and
install commands can be passed via
MODPY_DISTUTILS_BUILDARGS and
MODPY_DISTUTILS_INSTALLARGS. These ports can often
be converted to MODPY_PYBUILD with some small
changes to the port.
Ports which use the pytest module should set
MODPY_PYTEST to Yes. This is set automatically for
builds using MODPY_PYBUILD. Arguments can be passed
to pytest during test with
MODPY_PYTEST_ARGS, for example to list names of test
scripts if the automatic detection fails, to disable certain test scripts
with ‘--ignore’, or to disable certain individual tests with
‘-k’. User setting
MODPY_PYTEST_USERARGS, if present, is passed on the
command line. This allows setting py.test flags to increase verbosity, show
test durations, enable colours, etc.
All ports that generate egg-info or dist-info files
should set MODPY_EGG_VERSION to the version string
used by the
setup()
function in the port's setup.py or the version in
pyproject.toml.
If any files have a python shebang line where the interpreter
should be ${MODPY_BIN}, list them in
MODPY_ADJ_FILES. These filenames can be relative to
${WRKSRC} and will be modified at the end of
pre-configure.
For ports not using standard Python build infrastructure, it may
be necessary to bytecode-compile installed .py files. This can be done by
using ${MODPY_COMPILEALL}, usually in a post-install
target. This passes flags to use MAKE_JOBS, strip off WRKINST, and use
standard optimization passes. File or directory names can be given.
Directories are handled recursively.
This module also affects CATEGORIES,
MAKE_ENV, CONFIGURE_ENV, and
SUBST_VARS, and it may affect the
test target.
If MODPY_PI is set to ‘Yes’,
the module will provide a default for HOMEPAGE and
set MASTER_SITES (the subdirectory can be overridden
with MODPY_PI_DIR).
Packing-list generation
Python 2.x places .pyc files in the same directory as the
associated .py file. Python 3.x places these in a separate __pycache__
directory and uses an additional suffix. In some cases, an ABI tag is also
used for names of compiled extensions. The python module defines variables
to allow a single PLIST to be used for both
versions: generate or update the PLIST using the
python3 FLAVOR, then edit it to prefix any lines
creating MODPY_PYCACHE directories with
MODPY_COMMENT. As python2 and python3 packages
should permit being installed together, it may be necessary to suffix names
of common binaries or directories, or split common files into a subpackage.
If updating the PLIST without using the python3 flavor, take care not to
remove ${MODPY_PYCACHE}, ${MODPY_PYC_MAGIC_TAG}, or ${MODPY_ABI_TAG}
variables from the PLIST.