PYTHON-MODULE(5)

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_DEPENDS unless MODPY_RUNDEP is set to No,

•   BUILD_DEPENDS unless MODPY_BUILDDEP is set to No or NO_BUILD is set to Yes,

•   TEST_DEPENDS if MODPY_PYTEST is set to Yes unless MODPY_TESTDEP is 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.

SEE ALSO
port-modules(5)