1.\"	$OpenBSD: python-module.5,v 1.16 2025/02/05 11:10:19 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: February 5 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 adds a dependency on the Python interpreter 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, pbr, pdm, poetry-core, setuptools, setuptools-rust, and setuptools_scm.
110If no
111.Pa pyproject.toml
112is provided then it most likely 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
127Some checks are done to warn during "make fake" if
128.Ev MODPY_PYBUILD
129appears to be set incorrectly.
130.Pp
131Python 2 and some older Python 3 ports using setuptools still set
132.Ev MODPY_SETUPTOOLS
133to Yes, which appends to
134.Ev MODPY_BUILD_DEPENDS
135and calls the relevant commands to build (these ports are built
136using the deprecated mechanism of calling
137.Pa setup.py
138directly).
139Arguments can be passed to setup.py during
140.Cm configure
141with
142.Ev MODPY_SETUP_ARGS .
143Extra arguments to the build and install commands can be passed via
144.Ev MODPY_DISTUTILS_BUILDARGS
145and
146.Ev MODPY_DISTUTILS_INSTALLARGS .
147These ports can often be converted to
148.Ev MODPY_PYBUILD
149with some small changes to the port.
150.Ev MODPY_SETUPTOOLS
151should not be used for new ports.
152.Pp
153Ports using pytest should set
154.Ev MODPY_PYTEST
155to Yes unless
156.Ev MODPY_PYBUILD
157is used, when it is already set by default.
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 pytest flags to increase verbosity,
172show test durations, enable colours, etc.
173.Pp
174If
175.Ev MODPY_TEST_LINK_SO
176is set to Yes, symbolic links to all .so files in the build directory
177will be created before running tests.
178These are created in
179.Ev MODPY_TEST_LINK_SRC ,
180which defaults to ${WRKSRC}.
181This is required when tests load .so files via relative imports.
182.Pp
183All ports that generate egg-info or dist-info files should set
184.Ev MODPY_DISTV
185to the version string used by the
186.Fn setup
187function in the port's
188.Pa setup.py
189or the version in
190.Pa pyproject.toml .
191.Pp
192If any files have a python shebang line where the interpreter should be
193${MODPY_BIN}, list them in
194.Ev MODPY_ADJ_FILES .
195These filenames can be relative to ${WRKSRC} and will be modified
196at the end of
197.Cm pre-configure .
198.Pp
199For ports not using standard Python build infrastructure,
200it may be necessary to bytecode-compile installed .py files.
201This can be done by using
202.Ev ${MODPY_COMPILEALL} ,
203usually in a post-install target.
204This passes flags to use MAKE_JOBS, strip off WRKINST, and use
205standard optimization passes.
206File or directory names can be given.
207Directories are handled recursively.
208.Pp
209This module also affects
210.Ev CATEGORIES ,
211.Ev MAKE_ENV ,
212.Ev CONFIGURE_ENV ,
213and
214.Ev SUBST_VARS ,
215and it may affect the
216.Cm test
217target.
218.Pp
219If
220.Ev MODPY_PI
221is set to
222.Sq Yes ,
223the module will provide a default for
224.Ev HOMEPAGE
225and set
226.Ev MASTER_SITES
227.Po
228the subdirectory can be overridden with
229.Ev MODPY_PI_DIR
230.Pc .
231.Sh SEE ALSO
232.Xr port-modules 5
233