Introduction to Python packaging with `meson-python`#

If you are new to Python packaging, don’t worry!

We will give you a quick introduction to what steps releasing a Python package consists of, and walk you through them to get started.

Create a Meson project#

To get started, we need a project to publish. As meson-python is built on top of Meson, we will create a really simple Meson project. You may already have a Meson project you wish to publish, in that case, you can simply skip this step.

The module#

First, we create a simple Python module. We will go for a native module, as that’s really where meson-python shines against other Python build backends.

our_first_module.c#

#include <Python.h>

static PyObject* foo(PyObject* self)
{
    return PyUnicode_FromString("bar");
}

static PyMethodDef methods[] = {
    {"foo", (PyCFunction)foo, METH_NOARGS, NULL},
    {NULL, NULL, 0, NULL},
};

static struct PyModuleDef module = {
    PyModuleDef_HEAD_INIT,
    "our_first_module",
    NULL,
    -1,
    methods,
};

PyMODINIT_FUNC PyInit_our_first_module(void)
{
    return PyModule_Create(&module);
}

Here, we have a create a small module named our_first_module, which has a function foo that simply returns "bar".

Using the C API

If you need help writing a native module using Python’s C API, we recommend checking out the following resources.

The Meson build description#

Now, we need to create the Meson build description file. This tells Meson what we want it to build, and how to do it.

meson.build#

project('purelib-and-platlib', 'c')

py_mod = import('python')
py = py_mod.find_installation(pure: false)

py.extension_module(
    'our_first_module',
    'our_first_module.c',
    install: true,
)

Here, we use the Meson Python module to build our our_first_module module. We make sure to install it, by passing install: true to extension_module, as meson-python will only include in the binary distribution artifacts targets that Meson would install onto system. Having non installed targets allows you to build targets for use within the build, or for tests.

Configure our Python package#

Now, we need to tell Python packaging tooling what build backend to use to build our package. We do this by creating a build-system section in the pyproject.toml file, which is the file used to configure Python packaging tooling.

Inside the build-system section, we need to define two keys, build-backend and requires. build-backend defines which build backend should be used for the project, in meson-python it should always have the value of mesonpy. requires lets us specify which packages need to be installed for the build process, it should include meson-python and any other dependencies you might need (eg. Cython), in our case it’s just meson-python.

pyproject.toml#

[build-system]
build-backend = 'mesonpy'
requires = ['meson-python']

After we specify which backend to use, we’ll want to define the package metadata. This is done in the project section, and the format is pretty self-explanatory by looking at our example.

pyproject.toml#

...

[project]
name = 'our-first-project'
version = '0.0.1'
description = 'Our first Python project, using meson-python!'
readme = 'README.md'
requires-python = '>=3.8'
license = {file = 'LICENSE.txt'}
authors = [
  {name = 'Bowsette Koopa', email = 'bowsette@example.com'},
]

Adding dependencies

If you need to add dependencies to the project metadata, you can check our Adding dependencies guide.

Declaring project metadata

Our example doesn’t make use of all the fields available, so we recommend you check out the PyPA documentation on project metadata.

Writing TOML

If you are not familiar with the TOML configuration language or need some help, be sure to check out toml.io.

Testing the project#

Now we should have a valid Python project, let’s test it.

We will install it with pip

$ pip install .
$ pip list
...
our-first-project   0.0.1
...

After this, we should be able to import and try out our module.

$ python
>>> import our_first_module
>>> our_first_module.foo()
'bar'

Creating your first release#

Now that we have a valid Python project, we can release it.

To release the project we first need to generate the distribution artifacts, these are files in a standardized format that Python package installers understand. There are two kind of artifacts, source distributions, which are commonly referred to as sdists, and binary distributions, which use a custom format named wheel, so they’re generally referred to as wheels.

What are the roles of sdists and wheels#

As you might have figured out by the name, sdists contain the source code of the project, and wheels contain a compiled 1 version of the project, ready to be copied to the file-system.

If your project uses Python extension modules, your wheels will be specific to both the platform and the Python version 2.

While distributing wheels is not mandatory, they make the user experience much nicer. Unless you have any reason not to, we highly recommend you distribute wheels for at least the most common systems. When wheels are not available for a system, the project can still be installed, be it needs to be build from the sdist, which involves fetching all the build dependencies and going through the likely expensive build.

1: Projects that don’t have any compiled code will have a platform-independent – pure – wheel.
2: Unless you are using the stable ABI, which limits you to a subset of the Python C API, with the trade-off that your native code will be compatible with multiple Python versions.

Building the project#

To generate the distribution artifacts we will use the pypa/build tool. It will create a temporary virtual environment, install all the required build dependencies, and ask meson-python to build the artifacts.

$ pip install build
$ python -m build

If the build succeeded, you’ll have the binary artifacts in the dist folder.

Check the pypa/build documentation

To learn more about pypa/build, you can check their documentation.

Building wheels for multiple platforms

If our project only contains pure-Python (.py) code, the wheel we just built will work on all platforms, as it is a pure wheel, but if the project contains native code, it will be specific for our machine’s platform.

When releasing, you’ll usually want to build for at least most of the other more popular platforms (Linux, Windows, macOS, etc.). To make that work easier, we recommend checking out the cibuildwheel project, which allows you to automate it.

Distributing the project#

Now that we have the distribution artifacts, we can upload them to a repository. We will upload them to the Python Package Index (abv. PyPI, pronounced “pie pea eye”), which is repository that comes enabled by default in most tools.

For this, we will use Twine.

$ pip install twine
$ twine upload dist/*

Upload to the Test PyPI

If you don’t want to upload to the real index, you can upload to the Test PyPI instead.

$ twine upload -r testpypi dist/*

You can find more about how to use the Test PyPI in its PyPA documentation page.

Check the twine documentation

To learn more about Twine, you can check their documentation.

After this, your package should be available on PyPI, and installable with pip.

$ pip install our-first-project

Introduction to Python packaging with meson-python#

Create a Meson project#

The module#

The Meson build description#

Configure our Python package#

Testing the project#

Creating your first release#

What are the roles of sdists and wheels#

Building the project#

Distributing the project#

Introduction to Python packaging with `meson-python`#