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