1.\" $OpenBSD: python-module.5,v 1.15 2025/01/17 08:52:01 sthen Exp $ 2.\" 3.\" Copyright (c) 2008 Marc Espie 4.\" 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: January 17 2025 $ 28.Dt PYTHON-MODULE 5 29.Os 30.Sh NAME 31.Nm python-module 32.Nd lang/python port module 33.Sh DESCRIPTION 34This manual page documents the behavior of setting 35.Li MODULES=lang/python 36in the 37.Xr ports 7 38tree. 39.Pp 40By default, the module builds ports using Python 3. 41For legacy ports using Python 2, 42.Ev MODPY_VERSION 43may be set manually to ${MODPY_DEFAULT_VERSION_2}. 44.Pp 45The module then sets 46.Ev MODPY_BIN , 47.Ev MODPY_INCDIR , 48.Ev MODPY_LIBDIR , 49.Ev MODPY_SITEPKG , 50.Ev MODPY_SETUP , 51.Ev MODPY_TEST_DIR , 52.Ev MODPY_TEST_LOCALE , 53.Ev MODPY_WANTLIB , 54.Ev MODPY_LIB_DEPENDS , 55.Ev MODPY_RUN_DEPENDS , 56.Ev MODPY_TEST_DEPENDS , 57.Ev MODPY_BUILD_DEPENDS , 58and 59.Ev MODPY_ADJ_FILES 60accordingly. 61.Pp 62The module also appends to 63.Bl -bullet 64.It 65.Ev RUN_DEPENDS 66unless 67.Ev MODPY_RUNDEP 68is set to No, 69.It 70.Ev BUILD_DEPENDS 71unless 72.Ev MODPY_BUILDDEP 73is set to No or 74.Ev NO_BUILD 75is set to Yes, 76.It 77.Ev TEST_DEPENDS 78if 79.Ev MODPY_PYTEST 80is set to Yes 81unless 82.Ev MODPY_TESTDEP 83is set to No. 84.El 85.Pp 86It also appends 87.Ev MODPY_TEST_LOCALE 88to 89.Ev TEST_ENV 90and changes to the directory specified in 91.Ev MODPY_TEST_DIR 92.Po 93by default ${WRKSRC} 94.Pc 95before running tests. 96.Pp 97Most modern Python software can be packaged using a PEP 517 build 98frontend (in the 99.Pa devel/py-build 100port). 101To use this, set 102.Ev MODPY_PYBUILD 103to the name of the build backend. 104If the port provides a 105.Pa pyproject.toml 106file, check the "build-backend" line in the [build-system] section. 107.Nm 108currently supports flit, flit_core, hatchling, hatch-vcs, jupyter_packaging, 109maturin, pdm, poetry-core, setuptools, setuptools-rust, and setuptools_scm. 110If no 111.Pa pyproject.toml 112is provided then it probably uses setuptools. 113Setting 114.Ev MODPY_PYBUILD 115adds the backend to 116.Ev MODPY_BUILD_DEPENDS , 117and sets 118.Ev MODPY_PYTEST . 119In cases where an uncommon backend is used, or where the build backend is 120distributed with the software itself, 121.Ev MODPY_PYBUILD 122can be set to 123.Sq other 124to use the PEP 517 build mechanism without adding a dependency 125for a backend. 126.Pp 127Python 2 and some older Python 3 ports using setuptools still set 128.Ev MODPY_SETUPTOOLS 129to Yes, which appends to 130.Ev MODPY_BUILD_DEPENDS 131and calls the relevant commands to build (these ports are built 132using the deprecated mechanism of calling 133.Pa setup.py 134directly). 135Arguments can be passed to setup.py during 136.Cm configure 137with 138.Ev MODPY_SETUP_ARGS . 139Extra arguments to the build and install commands can be passed via 140.Ev MODPY_DISTUTILS_BUILDARGS 141and 142.Ev MODPY_DISTUTILS_INSTALLARGS . 143These ports can often be converted to 144.Ev MODPY_PYBUILD 145with some small changes to the port. 146.Ev MODPY_SETUPTOOLS 147should not be used for new ports. 148.Pp 149Ports which use the pytest module should set 150.Ev MODPY_PYTEST 151to Yes. 152This is set automatically for builds using 153.Ev MODPY_PYBUILD . 154Arguments can be passed to pytest during 155.Cm test 156with 157.Ev MODPY_PYTEST_ARGS , 158for example to list names of test scripts if the automatic 159detection fails, 160to disable certain test scripts with 161.Sq --ignore , 162or to disable certain individual tests with 163.Sq -k . 164User setting 165.Ev MODPY_PYTEST_USERARGS , 166if present, is passed on the command line. 167This allows setting py.test flags to increase verbosity, 168show test durations, enable colours, etc. 169.Pp 170If 171.Ev MODPY_TEST_LINK_SO 172is set to Yes, symbolic links to all .so files in the build directory 173will be created before running tests. 174These are created in 175.Ev MODPY_TEST_LINK_SRC , 176which defaults to ${WRKSRC}. 177This is required when tests load .so files via relative imports. 178.Pp 179All ports that generate egg-info or dist-info files should set 180.Ev MODPY_DISTV 181to the version string used by the 182.Fn setup 183function in the port's 184.Pa setup.py 185or the version in 186.Pa pyproject.toml . 187.Pp 188If any files have a python shebang line where the interpreter should be 189${MODPY_BIN}, list them in 190.Ev MODPY_ADJ_FILES . 191These filenames can be relative to ${WRKSRC} and will be modified 192at the end of 193.Cm pre-configure . 194.Pp 195For ports not using standard Python build infrastructure, 196it may be necessary to bytecode-compile installed .py files. 197This can be done by using 198.Ev ${MODPY_COMPILEALL} , 199usually in a post-install target. 200This passes flags to use MAKE_JOBS, strip off WRKINST, and use 201standard optimization passes. 202File or directory names can be given. 203Directories are handled recursively. 204.Pp 205This module also affects 206.Ev CATEGORIES , 207.Ev MAKE_ENV , 208.Ev CONFIGURE_ENV , 209and 210.Ev SUBST_VARS , 211and it may affect the 212.Cm test 213target. 214.Pp 215If 216.Ev MODPY_PI 217is set to 218.Sq Yes , 219the module will provide a default for 220.Ev HOMEPAGE 221and set 222.Ev MASTER_SITES 223.Po 224the subdirectory can be overridden with 225.Ev MODPY_PI_DIR 226.Pc . 227.Ss Packing-list generation 228Python 2.x places .pyc files in the same directory as the associated .py file. 229Python 3.x places these in a separate __pycache__ directory and uses an 230additional suffix that includes the Python version. 231In some cases, an ABI tag is also used for names of compiled extensions. 232The python module defines variables so that a 233.Pa PLIST 234is likely to still work with a newer Python version without changes. 235.Sh SEE ALSO 236.Xr port-modules 5 237