Tutorial

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.

Creating 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 official Python C API documentation

• RealPython’s “Building a Python C Extension Module” introductory tutorial

• pysheeet’s “C Extensions” page

• pysheeet-kr’s “Python C API cheatsheet” page

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 = import('python').find_installation(pure: false)

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

Here, we use Meson’s 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.

Configuring 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 - set it to 'mesonpy' to use meson-python. 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 (e.g., Cython).

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:

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'},
]

Declaring project metadata

Our example doesn’t make use of all the fields available in the [project] section. Check out the PyPA documentation on project metadata for more examples and details.

Testing the project

Now we should have a valid Python project, so 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 process.

[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

Before continuing, ensure you have committed the three files we created so far to your Git repository - meson-python will only take into account the files that Git knows about.

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.

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.

Build isolation

Building with python -m build or with pip uses build isolation by default. I.e., the build frontend creates a new, temporary virtual environment with all build dependencies before calling meson-python to build a wheel.

If you disable build isolation, you are responsible for ensuring that meson-python and all other build dependencies for the package are installed already in the Python environment. Note that if you use a virtual environment to build in, it must be activated (otherwise meson or another executable may not be found).

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 (PyPI), 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.

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

$ pip install our-first-project