.. SPDX-FileCopyrightText: 2023 The meson-python developers
..
.. SPDX-License-Identifier: MIT

.. _tutorial-introduction:

******************************************************
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.


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


.. 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 by looking at our example.


.. 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:: Adding dependencies
   :class: seealso

   If you need to add dependencies to the project metadata, you can check our
   :ref:`how-to-guides-add-dependencies` guide.


.. admonition:: Declaring project metadata
   :class: seealso

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


.. admonition:: Writing TOML
   :class: seealso

   If you are not familiar with the TOML configuration language or need some
   help, be sure to check out `toml.io <https://toml.io>`_.


Testing the project
-------------------

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


.. [#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
--------------------

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:: Check the pypa/build documentation
   :class: seealso

   To learn more about `pypa/build`_, you can check
   `their documentation <https://pypa-build.readthedocs.io/>`__.


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


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`_ (:spelling:word:`abv`. *PyPI*,
`pronounced "pie pea eye"`_), 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/>`_.


.. admonition:: Check the twine documentation
   :class: seealso

   To learn more about Twine_, you can check
   `their documentation <https://twine.readthedocs.io/>`__.


After this, your package should be available on PyPI_, and installable with
pip_.


.. code-block:: console

   $ pip install our-first-project



.. _Meson: https://github.com/mesonbuild/meson
.. _Meson 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
