Skip to content
Back to top
View this page

# 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 extending-index guide in the Python documentation. Also consider if you need to use the CPython C API directly, or are perhaps better off using a binding generator tool like Cython, pybind11 or nanobind which will take care of a lot of the low-level details for you.

### 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, and an sdist is created from the most recent commit - uncommitted changes are ignored.

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. Note that by default, `python -m build` builds an sdist first, and then a wheel from the sdist. If you only want one artifact, add `--sdist` or `--wheel` to the invocation.

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