Use pyproject.toml with hatchling instead of setuptools

[konstin]

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

[konstin]

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

[konstin]

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.

[srittau]

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

[hauntsaninja]

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

[konstin]

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.

[konstin]

With the latest iteration, only the stubs package has a pyproject.toml, for all other cases the defaults from you package manager / following https://packaging.python.org/en/latest/guides/writing-pyproject-toml/ does the right thing.

[hauntsaninja]

I think we should try to stay build backend agnostic, unless one build backend provides a better experience for typing.

Based on that, I think we should entirely remove:

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

And while we're here, maybe replace it with:

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

since I've seen people put it a layer above sometimes.

For the stubs-only package, I'd vote we change the example to uv-build because that's a better experience for these users. If hatchling later adds the same feature, then we can edit to mention that.

[konstin]

For the stubs-only package, I'd vote we change the example to uv-build because that's a better experience for these users. If hatchling later adds the same feature, then we can edit to mention that.

Do you still want to show the pyproject.toml contents? To get stubs with uv-build, the basic getting-started instructions work:

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

[build-system]
requires = ["uv_build>=0.9.18,<0.10.0"]
build-backend = "uv_build"