.. 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 <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"``.


.. 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 <https://docs.python.org/3/extending/index.html>`_
   - `RealPython's "Building a Python C Extension Module" introductory tutorial <https://realpython.com/build-python-c-extension-module/>`_
   - `pysheeet's "C Extensions" page <https://www.pythonsheets.com/notes/python-c-extensions.html>`_
   - `pysheeet-kr's "Python C API cheatsheet" page <https://pysheeet-kr.readthedocs.io/ko/latest/notes/python-capi.html>`_


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 <https://packaging.python.org/en/latest/guides/using-testpypi/>`_.

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