.. SPDX-FileCopyrightText: 2023 The meson-python developers .. .. SPDX-License-Identifier: MIT .. _tutorial: ******** 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. .. code-block:: c :caption: our_first_module.c #include 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"``. .. admonition:: Using the C API :class: seealso 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. .. code-block:: meson :caption: 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``). .. code-block:: toml :caption: 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: .. code-block:: toml :caption: 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'}, ] .. admonition:: Declaring project metadata :class: seealso 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_: .. code-block:: console $ pip install . $ pip list ... our-first-project 0.0.1 ... After this, we should be able to import and try out our module. .. code-block:: console $ 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 [#pure-wheels]_ 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 [#stable-abi]_. 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. .. [#pure-wheels] Projects that don't have any compiled code will have a platform-independent -- *pure* -- wheel. .. [#stable-abi] 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. .. code-block:: console $ pip install build $ python -m build If the build succeeded, you'll have the binary artifacts in the ``dist`` folder. .. admonition:: Building wheels for multiple platforms :class: tip 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_. .. code-block:: console $ pip install twine $ twine upload dist/* .. admonition:: Upload to the `Test PyPI`_ :class: tip If you don't want to upload to the real index, you can upload to the `Test PyPI`_ instead. .. code-block:: console $ 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_. .. code-block:: console $ pip install our-first-project .. _Meson: https://mesonbuild.com/ .. _Python module: https://mesonbuild.com/Python-module.html .. _PyPA documentation on project metadata: https://packaging.python.org/en/latest/specifications/declaring-project-metadata/ .. _source distributions: https://packaging.python.org/en/latest/specifications/source-distribution-format/ .. _binary distributions: https://packaging.python.org/en/latest/specifications/binary-distribution-format/ .. _stable ABI: https://docs.python.org/3/c-api/stable.html#stable-application-binary-interface .. _pypa/build: https://github.com/pypa/build .. _cibuildwheel: https://github.com/pypa/cibuildwheel .. _Python Package Index: https://pypi.org/ .. _pronounced "pie pea eye": https://pypi.org/help/#pronunciation .. _Twine: https://github.com/pypa/twine .. _Test PyPI: https://test.pypi.org/ .. _PyPI: https://pypi.org/ .. _pip: https://github.com/pypa/pip