Skip to content

Use pyproject.toml with hatchling instead of setuptools #2138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
konstin wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Use pyproject.toml with hatchling instead of setuptools #2138

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
dde2d57
Use `pyproject.toml` with hatchling instead of setuptools
konstin Dec 18, 2025
a17481c
Hatchling is only an example
konstin Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 15 additions & 52 deletions docs/guides/libraries.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,25 +82,15 @@ 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:
Comment on lines 91 to -92
Copy link
Author

@konstin konstin Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This note is afaik only relevant for setuptools anymore. Since the other build backends I'm aware support this in the default configuration, I've shortened it to this hint, the specifics fit better in the setuptools documentation.

Copy link
Collaborator

@srittau srittau Dec 18, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rather make a general statement, instead of focusing on hatchling. Something like "Most modern build tools like hatchling include it by default."

Copy link
Collaborator

@hauntsaninja hauntsaninja Dec 18, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

setuptools>=69 includes this by default too, so I think we can just remove this statement / I think we can just not mention build backends in this guide

Copy link
Author

@konstin konstin Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I shrunk the note to mentioning it needs to be included and all modern package managers do it by default, i.e. don't put it in your gitignore where hatchling skips it.


.. code-block:: python

from setuptools import setup

setup(
name="my_great_distribution",
version="0.1",
package_data={"my_great_package": ["py.typed"]},
packages=["my_great_package"],
)
distributed package. Modern build backends such as ``hatchling`` include it
by default.


Type stub files included in the package
Expand All @@ -113,27 +103,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.
Expand All @@ -150,41 +126,28 @@ For example:

.. code-block:: text

setup.py
pyproject.toml
my_great_package-stubs/
__init__.pyi
stuff.pyi

.. code-block:: toml

.. code-block:: python
[project]
name = "my-great-package-stubs"
version = "0.1.0"
requires-python = ">=3.14"

from setuptools import setup

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"]
Comment on lines +145 to +146
Copy link
Author

@konstin konstin Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uv-build supports those without extra configuration, but hatchling is wider used.


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 <https://packaging.python.org/en/latest/guides/using-manifest-in/>`__
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?
Expand Down