Debian Codegraph @

subprojects/meson-docs/docs/markdown/Python-module.md

raw
1 ---
2 short-description: Generic python module
3 authors:
4 - name: Mathieu Duponchelle
5 email: [email protected]
6 years: [2018]
7 has-copyright: false
8 ...
9
10 # Python module
11
12 This module provides support for finding and building extensions against
13 python installations, be they python 2 or 3.
14
15 If you want to build and package Python extension modules using tools
16 compatible with [PEP-517](https://peps.python.org/pep-0517/), check out
17 [meson-python](https://mesonbuild.com/meson-python/index.html).
18
19 If you are building Python extension modules against a Python interpreter
20 located in a venv or Conda environment, you probably want to set
21 `python.install_env=auto`;
22 see [Python module options](Builtin-options.md#python-module) for details.
23
24 *Added 0.46.0*
25
26 ## Functions
27
28 ### `find_installation()`
29
30 ``` meson
31 pymod.find_installation(name_or_path, ...)
32 ```
33
34 Find a python installation matching `name_or_path`.
35
36 That argument is optional, if not provided then the returned python
37 installation will be the one used to run Meson.
38
39 If provided, it can be:
40
41 - A simple name, eg `python-2.7`, Meson will look for an external program
42 named that way, using [[find_program]]
43
44 - A path, eg `/usr/local/bin/python3.4m`
45
46 - One of `python2` or `python3`: in either case, the module will try
47 some alternative names: `py -2` or `py -3` on Windows, and `python`
48 everywhere. In the latter case, it will check whether the version
49 provided by the sysconfig module matches the required major version.
50
51 *Since 1.2.0*, searching for minor version (e.g. `python3.11`) also
52 works on Windows.
53
54 Keyword arguments are the following:
55
56 - `required`: by default, `required` is set to `true` and Meson will
57 abort if no python installation can be found. If `required` is set to `false`,
58 Meson will continue even if no python installation was found. You can
59 then use the `.found()` method on the returned object to check
60 whether it was found or not. Since *0.48.0* the value of a
61 [`feature`](Build-options.md#features) option can also be passed to the
62 `required` keyword argument.
63 - `disabler`: if `true` and no python installation can be found, return a
64 [[@disabler]] object instead of a not-found object.
65 *Since 0.49.0*
66 - `modules`: a list of module names that this python installation must have.
67 *Since 0.51.0*
68 - `pure`: On some platforms, architecture independent files are
69 expected to be placed in a separate directory. However, if the
70 python sources should be installed alongside an extension module
71 built with this module, this keyword argument can be used to
72 override the default behavior of `.install_sources()`.
73 *since 0.64.0*
74
75 **Returns**: a [python installation][`python_installation` object]
76
77 ## `python_installation` object
78
79 The `python_installation` object is an [[@external_program]], with several
80 added methods.
81
82 ### Methods
83
84 #### `path()`
85
86 ```meson
87 str py_installation.path()
88 ```
89
90 *Added 0.50.0*
91
92 Works like the path method of other `ExternalProgram` objects. Was not
93 provided prior to 0.50.0 due to a bug.
94
95 #### `extension_module()`
96
97 ``` meson
98 shared_module py_installation.extension_module(module_name, list_of_sources, ...)
99 ```
100
101 Create a [[shared_module]] target that is named according to the naming
102 conventions of the target platform.
103
104 All positional and keyword arguments are the same as for
105 [[shared_module]], excluding `name_suffix` and `name_prefix`, and with
106 the addition of the following:
107
108 - `subdir`: By default, Meson will install the extension module in
109 the relevant top-level location for the python installation, eg
110 `/usr/lib/site-packages`. When subdir is passed to this method,
111 it will be appended to that location. This keyword argument is
112 mutually exclusive with `install_dir`
113 - `limited_api`: *since 1.3.0* A string containing the Python version
114 of the [Py_LIMITED_API](https://docs.python.org/3/c-api/stable.html) that
115 the extension targets. For example, '3.7' to target Python 3.7's version of
116 the limited API. This behavior can be disabled by setting the value of
117 `python.allow_limited_api`. See [Python module options](Builtin-options.md#python-module).
118
119 Additionally, the following diverge from [[shared_module]]'s default behavior:
120
121 - `gnu_symbol_visibility`: if unset, it will default to `'hidden'` on versions
122 of Python that support this (the python headers define `PyMODINIT_FUNC` has
123 default visibility).
124
125 Note that Cython support uses `extension_module`, see [the reference for Cython](Cython.md).
126
127 *since 0.63.0* `extension_module` automatically adds a dependency to the library
128 if one is not explicitly provided. To support older versions, the user may need to
129 add `dependencies : py_installation.dependency()`, see [[dependency]].
130
131 **Returns**: a [[@build_tgt]] object
132
133 #### `dependency()`
134
135 ``` meson
136 python_dependency py_installation.dependency(...)
137 ```
138
139 *since 0.53.0*
140
141 This method accepts no positional arguments, and the same keyword
142 arguments as the standard [[dependency]] function. It also supports the
143 following keyword argument:
144
145 - `embed`: *(since 0.53.0)* If true, Meson will try to find a python
146 dependency that can be used for embedding python into an
147 application.
148 - `disabler` *(since 0.60.0)*: if `true` and the dependency couldn't be found,
149 returns a [disabler object](#disabler-object) instead of a not-found dependency.
150
151 **Returns**: a [python dependency][`python_dependency` object]
152
153 #### `install_sources()`
154
155 ``` meson
156 void py_installation.install_sources(list_of_files, ...)
157 ```
158
159 Install actual python sources (`.py`).
160
161 Source files to install are given as positional argument, in the same way as for
162 [[install_data]]. Supported keyword arguments are:
163
164 - `pure`: On some platforms, architecture independent files are
165 expected to be placed in a separate directory. However, if the
166 python sources should be installed alongside an extension module
167 built with this module, this keyword argument can be used to
168 override that behaviour. Defaults to the value specified in
169 `find_installation()`, or else `true`
170
171 - `subdir`: See documentation for the argument of the same name to
172 [][`extension_module()`]
173
174 - `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
175 to install only a subset of the files. By default it has the tag `python-runtime`.
176
177 - `preserve_path`: if `true`, disable stripping child-directories from data
178 files when installing. Default is `false`. *(since 0.64.0)*
179
180 *Since 0.60.0* `python.platlibdir` and `python.purelibdir` options can be used
181 to control the default installation path. See [Python module options](Builtin-options.md#python-module).
182
183 #### `get_install_dir()`
184
185 ``` meson
186 string py_installation.get_install_dir(...)
187 ```
188
189 Retrieve the directory [][`install_sources()`] will install to.
190
191 It can be useful in cases where `install_sources` cannot be used
192 directly, for example when using [[configure_file]].
193
194 This function accepts no arguments, its keyword arguments are the same
195 as [][`install_sources()`].
196
197 *Since 0.60.0* `python.platlibdir` and `python.purelibdir` options can be used
198 to control the default installation path. See [Python module options](Builtin-options.md#python-module).
199
200 **Returns**: A string
201
202 #### `language_version()`
203
204 ``` meson
205 string py_installation.language_version()
206 ```
207
208 Get the major.minor python version, eg `2.7`.
209
210 The version is obtained through the `sysconfig` module.
211
212 This function expects no arguments or keyword arguments.
213
214 **Returns**: A string
215
216 #### `get_path()`
217
218 ``` meson
219 string py_installation.get_path(path_name, fallback)
220 ```
221
222 Get a path as defined by the `sysconfig` module.
223
224 For example:
225
226 ``` meson
227 purelib = py_installation.get_path('purelib')
228 ```
229
230 This function requires at least one argument, `path_name`,
231 which is expected to be a non-empty string.
232
233 If `fallback` is specified, it will be returned if no path
234 with the given name exists. Otherwise, attempting to read
235 a non-existing path will cause a fatal error.
236
237 **Returns**: A string
238
239 #### `has_path()`
240
241 ``` meson
242 bool py_installation.has_path(path_name)
243 ```
244
245 **Returns**: true if a path named `path_name` can be retrieved with
246 [][`get_path()`], false otherwise.
247
248 #### `get_variable()`
249
250 ``` meson
251 string py_installation.get_variable(variable_name, fallback)
252 ```
253
254 Get a variable as defined by the `sysconfig` module.
255
256 For example:
257
258 ``` meson
259 py_bindir = py_installation.get_variable('BINDIR', '')
260 ```
261
262 This function requires at least one argument, `variable_name`,
263 which is expected to be a non-empty string.
264
265 If `fallback` is specified, it will be returned if no variable
266 with the given name exists. Otherwise, attempting to read
267 a non-existing variable will cause a fatal error.
268
269 **Returns**: A string
270
271 #### `has_variable()`
272
273 ``` meson
274 bool py_installation.has_variable(variable_name)
275 ```
276
277 **Returns**: true if a variable named `variable_name` can be retrieved
278 with [][`get_variable()`], false otherwise.
279
280 ## `python_dependency` object
281
282 This [[@dep]] object subclass will try various methods to obtain
283 the compiler and linker arguments, starting with pkg-config then
284 potentially using information obtained from python's `sysconfig`
285 module.
286
287 It exposes the same methods as its parent class.