Skip to content

Use pyproject.toml instead of setup.py #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

Merged
hauntsaninja merged 4 commits into from
Jan 7, 2026
Merged

Use pyproject.toml instead of setup.py #2138

Changes from all commits
Commits
Show all changes
4 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
810a7cb
Use uv_build for stubs example, and Python 3.10+
konstin Jan 6, 2026
b0eb143
change comment
hauntsaninja Jan 6, 2026
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: 12 additions & 55 deletions docs/guides/libraries.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,26 +82,13 @@ 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:

.. 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"],
)

Note the py.typed should be located inside the package, along with ``__init__.py``.

Type stub files included in the package
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -113,27 +100,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 +123,25 @@ 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

setup(
name="my_great_package-stubs",
version="0.1",
package_data={"my_great_package-stubs": ["__init__.pyi", "stuff.pyi"]},
packages=["my_great_package-stubs"]
)
[project]
name = "my-great-package-stubs"
version = "0.1.0"
requires-python = ">=3.10"

[build-system]
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.

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