| 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. |