1.\" $OpenBSD: python-module.5,v 1.12 2024/05/28 16:05:39 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: May 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_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_core, hatchling, hatch-vcs, jupyter_packaging, 117maturin, 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 other to use the PEP 517 mechanism without adding a dependency 131for a backend. 132.Pp 133Older ports using setuptools still set 134.Ev MODPY_SETUPTOOLS 135to Yes, which appends to 136.Ev MODPY_BUILD_DEPENDS 137and calls the relevant commands to build (these ports are built 138using the deprecated mechanism of calling 139.Pa setup.py 140directly). 141Arguments can be passed to setup.py during 142.Cm configure 143with 144.Ev MODPY_SETUP_ARGS . 145Extra arguments to the build and install commands can be passed via 146.Ev MODPY_DISTUTILS_BUILDARGS 147and 148.Ev MODPY_DISTUTILS_INSTALLARGS . 149These ports can often be converted to 150.Ev MODPY_PYBUILD 151with some small changes to the port. 152.Pp 153Ports which use the pytest module should set 154.Ev MODPY_PYTEST 155to Yes. 156This is set automatically for builds using 157.Ev MODPY_PYBUILD . 158Arguments can be passed to pytest during 159.Cm test 160with 161.Ev MODPY_PYTEST_ARGS , 162for example to list names of test scripts if the automatic 163detection fails, 164to disable certain test scripts with 165.Sq --ignore , 166or to disable certain individual tests with 167.Sq -k . 168User setting 169.Ev MODPY_PYTEST_USERARGS , 170if present, is passed on the command line. 171This allows setting py.test flags to increase verbosity, 172show test durations, enable colours, etc. 173.Pp 174All ports that generate egg-info or dist-info files should set 175.Ev MODPY_EGG_VERSION 176to the version string used by the 177.Fn setup 178function in the port's 179.Pa setup.py 180or the version in 181.Pa pyproject.toml . 182.Pp 183If any files have a python shebang line where the interpreter should be 184${MODPY_BIN}, list them in 185.Ev MODPY_ADJ_FILES . 186These filenames can be relative to ${WRKSRC} and will be modified 187at the end of 188.Cm pre-configure . 189.Pp 190For ports not using standard Python build infrastructure, 191it may be necessary to bytecode-compile installed .py files. 192This can be done by using 193.Ev ${MODPY_COMPILEALL} , 194usually in a post-install target. 195This passes flags to use MAKE_JOBS, strip off WRKINST, and use 196standard optimization passes. 197File or directory names can be given. 198Directories are handled recursively. 199.Pp 200This module also affects 201.Ev CATEGORIES , 202.Ev MAKE_ENV , 203.Ev CONFIGURE_ENV , 204and 205.Ev SUBST_VARS , 206and it may affect the 207.Cm test 208target. 209.Pp 210If 211.Ev MODPY_PI 212is set to 213.Sq Yes , 214the module will provide a default for 215.Ev HOMEPAGE 216and set 217.Ev MASTER_SITES 218.Po 219the subdirectory can be overridden with 220.Ev MODPY_PI_DIR 221.Pc . 222.Ss Packing-list generation 223Python 2.x places .pyc files in the same directory as the associated .py file. 224Python 3.x places these in a separate __pycache__ directory and uses an 225additional suffix. 226In some cases, an ABI tag is also used for names of compiled extensions. 227The python module defines variables to allow a single 228.Pa PLIST 229to be 230used for both versions: 231generate or update the 232.Pa PLIST 233using the python3 234.Ev FLAVOR , 235then edit it to prefix any lines creating 236.Ev MODPY_PYCACHE 237directories with 238.Ev MODPY_COMMENT . 239As python2 and python3 packages should permit being installed together, 240it may be necessary to suffix names of common binaries or directories, 241or split common files into a subpackage. 242If updating the PLIST without using the python3 flavor, 243take care not to remove ${MODPY_PYCACHE}, ${MODPY_PYC_MAGIC_TAG}, or 244${MODPY_ABI_TAG} variables from the PLIST. 245.Sh SEE ALSO 246.Xr port-modules 5 247