The Meson Build System http://mesonbuild.com/
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

274 lines
8.3 KiB

---
short-description: Generic python module
authors:
- name: Mathieu Duponchelle
email: mathieu@centricular.com
years: [2018]
has-copyright: false
...
# Python module
This module provides support for finding and building extensions against
python installations, be they python 2 or 3.
*Added 0.46.0*
## Functions
### `find_installation()`
``` meson
pymod.find_installation(name_or_path, ...)
```
Find a python installation matching `name_or_path`.
That argument is optional, if not provided then the returned python
installation will be the one used to run Meson.
If provided, it can be:
- A simple name, eg `python-2.7`, Meson will look for an external program
named that way, using [[find_program]]
- A path, eg `/usr/local/bin/python3.4m`
- One of `python2` or `python3`: in either case, the module will try
some alternative names: `py -2` or `py -3` on Windows, and `python`
everywhere. In the latter case, it will check whether the version
provided by the sysconfig module matches the required major version.
*Since 1.2.0*, searching for minor version (e.g. `python3.11`) also
works on Windows.
Keyword arguments are the following:
- `required`: by default, `required` is set to `true` and Meson will
abort if no python installation can be found. If `required` is set to `false`,
Meson will continue even if no python installation was found. You can
then use the `.found()` method on the returned object to check
whether it was found or not. Since *0.48.0* the value of a
[`feature`](Build-options.md#features) option can also be passed to the
`required` keyword argument.
- `disabler`: if `true` and no python installation can be found, return a
[[@disabler]] object instead of a not-found object.
*Since 0.49.0*
- `modules`: a list of module names that this python installation must have.
*Since 0.51.0*
- `pure`: On some platforms, architecture independent files are
expected to be placed in a separate directory. However, if the
python sources should be installed alongside an extension module
built with this module, this keyword argument can be used to
override the default behavior of `.install_sources()`.
*since 0.64.0*
**Returns**: a [python installation][`python_installation` object]
## `python_installation` object
The `python_installation` object is an [[@external_program]], with several
added methods.
### Methods
#### `path()`
```meson
str py_installation.path()
```
*Added 0.50.0*
Works like the path method of other `ExternalProgram` objects. Was not
provided prior to 0.50.0 due to a bug.
#### `extension_module()`
``` meson
shared_module py_installation.extension_module(module_name, list_of_sources, ...)
```
Create a [[shared_module]] target that is named according to the naming
conventions of the target platform.
All positional and keyword arguments are the same as for
[[shared_module]], excluding `name_suffix` and `name_prefix`, and with
the addition of the following:
- `subdir`: By default, Meson will install the extension module in
the relevant top-level location for the python installation, eg
`/usr/lib/site-packages`. When subdir is passed to this method,
it will be appended to that location. This keyword argument is
mutually exclusive with `install_dir`
- `limited_api`: *since 1.3.0* A string containing the Python version
of the [Py_LIMITED_API](https://docs.python.org/3/c-api/stable.html) that
the extension targets. For example, '3.7' to target Python 3.7's version of
the limited API. This behavior can be disabled by setting the value of
`python.allow_limited_api`. See [Python module options](Builtin-options.md#python-module).
Additionally, the following diverge from [[shared_module]]'s default behavior:
- `gnu_symbol_visibility`: if unset, it will default to `'hidden'` on versions
of Python that support this (the python headers define `PyMODINIT_FUNC` has
default visibility).
*since 0.63.0* `extension_module` automatically adds a dependency to the library
if one is not explicitly provided. To support older versions, the user may need to
add `dependencies : py_installation.dependency()`, see [[dependency]].
**Returns**: a [[@build_tgt]] object
#### `dependency()`
``` meson
python_dependency py_installation.dependency(...)
```
*since 0.53.0*
This method accepts no positional arguments, and the same keyword
arguments as the standard [[dependency]] function. It also supports the
following keyword argument:
- `embed`: *(since 0.53.0)* If true, Meson will try to find a python
dependency that can be used for embedding python into an
application.
- `disabler` *(since 0.60.0)*: if `true` and the dependency couldn't be found,
returns a [disabler object](#disabler-object) instead of a not-found dependency.
**Returns**: a [python dependency][`python_dependency` object]
#### `install_sources()`
``` meson
void py_installation.install_sources(list_of_files, ...)
```
Install actual python sources (`.py`).
All positional and keyword arguments are the same as for
[[install_data]], with the addition of the following:
*Since 0.60.0* `python.platlibdir` and `python.purelibdir` options can be used
to control the default installation path. See [Python module options](Builtin-options.md#python-module).
- `pure`: On some platforms, architecture independent files are
expected to be placed in a separate directory. However, if the
python sources should be installed alongside an extension module
built with this module, this keyword argument can be used to
override that behaviour. Defaults to the value specified in
`find_installation()`, or else `true`
- `subdir`: See documentation for the argument of the same name to
[][`extension_module()`]
- `install_tag` *(since 0.60.0)*: A string used by `meson install --tags` command
to install only a subset of the files. By default it has the tag `python-runtime`.
#### `get_install_dir()`
``` meson
string py_installation.get_install_dir(...)
```
Retrieve the directory [][`install_sources()`] will install to.
It can be useful in cases where `install_sources` cannot be used
directly, for example when using [[configure_file]].
This function accepts no arguments, its keyword arguments are the same
as [][`install_sources()`].
*Since 0.60.0* `python.platlibdir` and `python.purelibdir` options can be used
to control the default installation path. See [Python module options](Builtin-options.md#python-module).
**Returns**: A string
#### `language_version()`
``` meson
string py_installation.language_version()
```
Get the major.minor python version, eg `2.7`.
The version is obtained through the `sysconfig` module.
This function expects no arguments or keyword arguments.
**Returns**: A string
#### `get_path()`
``` meson
string py_installation.get_path(path_name, fallback)
```
Get a path as defined by the `sysconfig` module.
For example:
``` meson
purelib = py_installation.get_path('purelib')
```
This function requires at least one argument, `path_name`,
which is expected to be a non-empty string.
If `fallback` is specified, it will be returned if no path
with the given name exists. Otherwise, attempting to read
a non-existing path will cause a fatal error.
**Returns**: A string
#### `has_path()`
``` meson
bool py_installation.has_path(path_name)
```
**Returns**: true if a path named `path_name` can be retrieved with
[][`get_path()`], false otherwise.
#### `get_variable()`
``` meson
string py_installation.get_variable(variable_name, fallback)
```
Get a variable as defined by the `sysconfig` module.
For example:
``` meson
py_bindir = py_installation.get_variable('BINDIR', '')
```
This function requires at least one argument, `variable_name`,
which is expected to be a non-empty string.
If `fallback` is specified, it will be returned if no variable
with the given name exists. Otherwise, attempting to read
a non-existing variable will cause a fatal error.
**Returns**: A string
#### `has_variable()`
``` meson
bool py_installation.has_variable(variable_name)
```
**Returns**: true if a variable named `variable_name` can be retrieved
with [][`get_variable()`], false otherwise.
## `python_dependency` object
This [[@dep]] object subclass will try various methods to obtain
the compiler and linker arguments, starting with pkg-config then
potentially using information obtained from python's `sysconfig`
module.
It exposes the same methods as its parent class.