1.\" $OpenBSD: python-module.5,v 1.14 2024/10/28 19:48:37 kirill 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: October 28 2024 $ 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 sets 41.Ev MODPY_VERSION 42to the appropriate python version 43.Po 44depending on the existence/presence of a 45.Sq python3 46.Ev FLAVOR 47.Pc , 48but 49.Ev MODPY_VERSION 50may be set manually to ${MODPY_DEFAULT_VERSION_2} 51for legacy ports. 52.Pp 53The module then sets 54.Ev MODPY_BIN , 55.Ev MODPY_INCDIR , 56.Ev MODPY_LIBDIR , 57.Ev MODPY_SITEPKG , 58.Ev MODPY_SETUP , 59.Ev MODPY_TEST_DIR , 60.Ev MODPY_TEST_LINK_SO , 61.Ev MODPY_TEST_LOCALE , 62.Ev MODPY_WANTLIB , 63.Ev MODPY_LIB_DEPENDS , 64.Ev MODPY_RUN_DEPENDS , 65.Ev MODPY_TEST_DEPENDS , 66.Ev MODPY_BUILD_DEPENDS , 67and 68.Ev MODPY_ADJ_FILES 69accordingly. 70.Pp 71The module also appends to 72.Bl -bullet 73.It 74.Ev RUN_DEPENDS 75unless 76.Ev MODPY_RUNDEP 77is set to No, 78.It 79.Ev BUILD_DEPENDS 80unless 81.Ev MODPY_BUILDDEP 82is set to No or 83.Ev NO_BUILD 84is set to Yes, 85.It 86.Ev TEST_DEPENDS 87if 88.Ev MODPY_PYTEST 89is set to Yes 90unless 91.Ev MODPY_TESTDEP 92is set to No. 93.El 94.Pp 95It also appends 96.Ev MODPY_TEST_LOCALE 97to 98.Ev TEST_ENV 99and changes to the directory specified in 100.Ev MODPY_TEST_DIR 101.Po 102by default ${WRKSRC} 103.Pc 104before running tests. 105In addition, it can link all .so files in ${WRKSRC} if 106.Ev MODPY_TEST_LINK_SO 107is set to Yes, which is required if you are using tests 108which use Python code that loads .so files via relative imports. 109.Pp 110Most modern Python software can be packaged using a PEP 517 build 111frontend (in the 112.Pa devel/py-build 113port). 114To use this, set 115.Ev MODPY_PYBUILD 116to the name of the build backend. 117If the port provides a 118.Pa pyproject.toml 119file, check the "build-backend" line in the [build-system] section. 120.Nm 121currently supports flit, flit_core, hatchling, hatch-vcs, jupyter_packaging, 122maturin, pdm, poetry-core, setuptools and setuptools_scm. 123If no 124.Pa pyproject.toml 125is provided then it probably uses setuptools. 126Setting 127.Ev MODPY_PYBUILD 128adds the backend to 129.Ev MODPY_BUILD_DEPENDS , 130and sets 131.Ev MODPY_PYTEST . 132In cases where a less common backend is used, or where the build backend is 133distributed with the software itself, 134.Ev MODPY_PYBUILD 135can be set to 136.Sq other 137to use the PEP 517 mechanism without adding a dependency 138for a backend. 139.Pp 140Older ports using setuptools still set 141.Ev MODPY_SETUPTOOLS 142to Yes, which appends to 143.Ev MODPY_BUILD_DEPENDS 144and calls the relevant commands to build (these ports are built 145using the deprecated mechanism of calling 146.Pa setup.py 147directly). 148Arguments can be passed to setup.py during 149.Cm configure 150with 151.Ev MODPY_SETUP_ARGS . 152Extra arguments to the build and install commands can be passed via 153.Ev MODPY_DISTUTILS_BUILDARGS 154and 155.Ev MODPY_DISTUTILS_INSTALLARGS . 156These ports can often be converted to 157.Ev MODPY_PYBUILD 158with some small changes to the port. 159.Pp 160Ports which use the pytest module should set 161.Ev MODPY_PYTEST 162to Yes. 163This is set automatically for builds using 164.Ev MODPY_PYBUILD . 165Arguments can be passed to pytest during 166.Cm test 167with 168.Ev MODPY_PYTEST_ARGS , 169for example to list names of test scripts if the automatic 170detection fails, 171to disable certain test scripts with 172.Sq --ignore , 173or to disable certain individual tests with 174.Sq -k . 175User setting 176.Ev MODPY_PYTEST_USERARGS , 177if present, is passed on the command line. 178This allows setting py.test flags to increase verbosity, 179show test durations, enable colours, etc. 180.Pp 181All ports that generate egg-info or dist-info files should set 182.Ev MODPY_EGG_VERSION 183to the version string used by the 184.Fn setup 185function in the port's 186.Pa setup.py 187or the version in 188.Pa pyproject.toml . 189.Pp 190If any files have a python shebang line where the interpreter should be 191${MODPY_BIN}, list them in 192.Ev MODPY_ADJ_FILES . 193These filenames can be relative to ${WRKSRC} and will be modified 194at the end of 195.Cm pre-configure . 196.Pp 197For ports not using standard Python build infrastructure, 198it may be necessary to bytecode-compile installed .py files. 199This can be done by using 200.Ev ${MODPY_COMPILEALL} , 201usually in a post-install target. 202This passes flags to use MAKE_JOBS, strip off WRKINST, and use 203standard optimization passes. 204File or directory names can be given. 205Directories are handled recursively. 206.Pp 207This module also affects 208.Ev CATEGORIES , 209.Ev MAKE_ENV , 210.Ev CONFIGURE_ENV , 211and 212.Ev SUBST_VARS , 213and it may affect the 214.Cm test 215target. 216.Pp 217If 218.Ev MODPY_PI 219is set to 220.Sq Yes , 221the module will provide a default for 222.Ev HOMEPAGE 223and set 224.Ev MASTER_SITES 225.Po 226the subdirectory can be overridden with 227.Ev MODPY_PI_DIR 228.Pc . 229.Ss Packing-list generation 230Python 2.x places .pyc files in the same directory as the associated .py file. 231Python 3.x places these in a separate __pycache__ directory and uses an 232additional suffix. 233In some cases, an ABI tag is also used for names of compiled extensions. 234The python module defines variables to allow a single 235.Pa PLIST 236to be 237used for both versions: 238generate or update the 239.Pa PLIST 240using the python3 241.Ev FLAVOR , 242then edit it to prefix any lines creating 243.Ev MODPY_PYCACHE 244directories with 245.Ev MODPY_COMMENT . 246As python2 and python3 packages should permit being installed together, 247it may be necessary to suffix names of common binaries or directories, 248or split common files into a subpackage. 249If updating the PLIST without using the python3 flavor, 250take care not to remove ${MODPY_PYCACHE}, ${MODPY_PYC_MAGIC_TAG}, or 251${MODPY_ABI_TAG} variables from the PLIST. 252.Sh SEE ALSO 253.Xr port-modules 5 254