From dde2d5773806d0abfdfa151becc1b33567902c45 Mon Sep 17 00:00:00 2001 From: konstin Date: Thu, 18 Dec 2025 12:26:44 +0100 Subject: [PATCH 1/4] 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/4] 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 From 810a7cb35ac79af3f13ec12cc43c695a6a36a9cc Mon Sep 17 00:00:00 2001 From: konstin Date: Tue, 6 Jan 2026 15:33:46 +0100 Subject: [PATCH 3/4] Use uv_build for stubs example, and Python 3.10+ --- docs/guides/libraries.rst | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/guides/libraries.rst b/docs/guides/libraries.rst index c9b8fb07..5557fa62 100644 --- a/docs/guides/libraries.rst +++ b/docs/guides/libraries.rst @@ -136,14 +136,11 @@ For example: [project] name = "my-great-package-stubs" version = "0.1.0" - requires-python = ">=3.14" + requires-python = ">=3.10" [build-system] - requires = ["hatchling"] - build-backend = "hatchling.build" - - [tool.hatch.build.targets.wheel] - packages = ["src/my_great_package-stubs"] + requires = ["uv_build>=0.9.18,<0.10.0"] + build-backend = "uv_build" Users are then able to install the stubs-only package separately to provide types for the original library. From b0eb143b1ec67b97f1e3116bedd158834fed647e Mon Sep 17 00:00:00 2001 From: hauntsaninja Date: Tue, 6 Jan 2026 10:48:49 -0800 Subject: [PATCH 4/4] change comment --- docs/guides/libraries.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/guides/libraries.rst b/docs/guides/libraries.rst index 5557fa62..a799af62 100644 --- a/docs/guides/libraries.rst +++ b/docs/guides/libraries.rst @@ -88,10 +88,7 @@ A typical directory structure would look like: stuff.py py.typed -It's important to ensure that the ``py.typed`` marker file is included in the -distributed package. Modern build backends such as ``hatchling`` include it -by default. - +Note the py.typed should be located inside the package, along with ``__init__.py``. Type stub files included in the package ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^