From dde2d5773806d0abfdfa151becc1b33567902c45 Mon Sep 17 00:00:00 2001 From: konstin Date: Thu, 18 Dec 2025 12:26:44 +0100 Subject: [PATCH 1/2] Use `pyproject.toml` with hatchling instead of setuptools The main motivation for this change is to migrate from the non-standard `setup.py` to the standard PEP 517 `setup.py`. The secondary motivation is to use a build backend that's easier to use and harder to get wrong than setuptools. Hatchling is the most popular build backend behind setuptools (I can provide data if required), and much easier to use than setuptools. Notably, it will include `py.typed` and `.pyi` files automatically. This also applies to most other build backends. This means we can remove the setuptools-specific documentation. packaging.python.org has a tab system to show different build backends (https://packaging.python.org/en/latest/guides/writing-pyproject-toml/). Afaik typing.python.org doesn't, so we only show one build backend. Fixes #2121 --- docs/guides/libraries.rst | 71 ++++++++++++--------------------------- 1 file changed, 22 insertions(+), 49 deletions(-) diff --git a/docs/guides/libraries.rst b/docs/guides/libraries.rst index d2a14027..060834d5 100644 --- a/docs/guides/libraries.rst +++ b/docs/guides/libraries.rst @@ -82,25 +82,25 @@ A typical directory structure would look like: .. code-block:: text - setup.py + pyproject.toml my_great_package/ __init__.py stuff.py py.typed It's important to ensure that the ``py.typed`` marker file is included in the -distributed package. If using ``setuptools``, this can be achieved like so: +distributed package. If using ``hatchling``, it is included by default: -.. code-block:: python +.. code-block:: toml - from setuptools import setup + [project] + name = "my-great-package" + version = "0.1.0" + requires-python = ">=3.14" - setup( - name="my_great_distribution", - version="0.1", - package_data={"my_great_package": ["py.typed"]}, - packages=["my_great_package"], - ) + [build-system] + requires = ["hatchling"] + build-backend = "hatchling.build" Type stub files included in the package @@ -113,27 +113,13 @@ directory structure would look like: .. code-block:: text - setup.py + pyproject.toml my_great_package/ __init__.py stuff.py stuff.pyi py.typed -If using ``setuptools``, we can ensure the ``.pyi`` and ``py.typed`` files are -included like so: - -.. code-block:: python - - from setuptools import setup - - setup( - name="my_great_distribution", - version="0.1", - package_data={"my_great_package": ["py.typed", "stuff.pyi"]}, - packages=["my_great_package"], - ) - The presence of ``.pyi`` files does not affect the Python interpreter at runtime in any way. However, static type checkers will only look at the ``.pyi`` file and ignore the corresponding ``.py`` file. @@ -150,41 +136,28 @@ For example: .. code-block:: text - setup.py + pyproject.toml my_great_package-stubs/ __init__.pyi stuff.pyi +.. code-block:: toml -.. code-block:: python - - from setuptools import setup + [project] + name = "my-great-package-stubs" + version = "0.1.0" + requires-python = ">=3.14" - setup( - name="my_great_package-stubs", - version="0.1", - package_data={"my_great_package-stubs": ["__init__.pyi", "stuff.pyi"]}, - packages=["my_great_package-stubs"] - ) + [build-system] + requires = ["hatchling"] + build-backend = "hatchling.build" + [tool.hatch.build.targets.wheel] + packages = ["src/my_great_package-stubs"] Users are then able to install the stubs-only package separately to provide types for the original library. -Inclusion in sdist -^^^^^^^^^^^^^^^^^^ - -Note that to ensure inclusion of ``.pyi`` and ``py.typed`` files in an sdist -(.tar.gz archive), you may also need to modify the inclusion rules in your -``MANIFEST.in`` (see the -`packaging guide `__ -for more details on ``MANIFEST.in``). For example: - -.. code-block:: text - - global-include *.pyi - global-include py.typed - .. _type_completeness: How much of my library needs types? From a17481c4a1cbda0be1d6f7f03e1ad384f0d3bc8a Mon Sep 17 00:00:00 2001 From: konstin Date: Thu, 18 Dec 2025 15:42:37 +0100 Subject: [PATCH 2/2] Hatchling is only an example --- docs/guides/libraries.rst | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/docs/guides/libraries.rst b/docs/guides/libraries.rst index 060834d5..c9b8fb07 100644 --- a/docs/guides/libraries.rst +++ b/docs/guides/libraries.rst @@ -89,18 +89,8 @@ A typical directory structure would look like: py.typed It's important to ensure that the ``py.typed`` marker file is included in the -distributed package. If using ``hatchling``, it is included by default: - -.. code-block:: toml - - [project] - name = "my-great-package" - version = "0.1.0" - requires-python = ">=3.14" - - [build-system] - requires = ["hatchling"] - build-backend = "hatchling.build" +distributed package. Modern build backends such as ``hatchling`` include it +by default. Type stub files included in the package