Set build system for ts_utils

[guitvcer]

Closes #13591.

I chose hatchling, because it was smallest build backend that was supported by uv.

[Avasam]

2025-10-23 edit: Adding the new uv backend to these tables, as I'd like to use this post as a reference.

---

Short of having any real requirements (it's a very simple pure-python package that we'd want to editable install eventually), I guess we can look at some numbers to help with a decision.

Trying all projects listed under https://packaging.python.org/en/latest/guides/tool-recommendations/#build-backends

Using Measure-Command { pip install "ts_utils @ file:lib" }, time in seconds:

build-backend	Run 2	Run 3	Run 4	Average
setuptools.build_meta	4.5907281	4.2905628	4.5659461	4.482412
poetry.core.masonry.api	3.256838	3.1587537	3.1883122	3.2013013
hatchling.build	3.1204848	2.9186966	2.9291026	2.989428
pdm_backend	2.6066548	2.631395	2.6216581	2.619902
flit_core.buildapi	2.3888605	2.4119825	2.4110851	2.403976
uv_build	2.3826117	2.3671179	2.3813631	2.3770309
uv_build (using uv pip)	0.1597998	0.1612703	0.1600756	0.1603819

Wheel size:

package	Size
setuptools	1.2 MB
poetry-core	331.2 kB
pdm-backend	115.0 kB
hatchling	75.8 kB
flit_core	44.9 kB
uv_build	1.5±2 MB
uv_build (using uv pip)	0 MB*

* https://docs.astral.sh/uv/concepts/build-backend/#bundled-build-backend

the uv executable also includes a copy of the build backend, which will be used during builds performed by uv

It's a strong contention between Flit and Hatchling. Purely looking at the numbers, Flit is both the most lightweight and fastest in practice. But at this speed and size, I think either would be a fit. I also don't see us needing any extension/plugin.

Flit and Hatchling are both hosted under the PyPA org, which is nice.

Flit forces us to add a description to the pyproject.toml:

(typeshed) PS E:\Users\Avasam\Documents\Git\typeshed> pip install "ts_utils @ file:lib"                    
Processing e:\users\avasam\documents\git\typeshed\lib
  Installing build dependencies ... done
  Getting requirements to build wheel ... error
  error: subprocess-exited-with-error

  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [16 lines of output]
      Traceback (most recent call last):
        File "C:\Users\Avasam\AppData\Local\Programs\Python\Python310\lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 
389, in <module>
          main()
        File "C:\Users\Avasam\AppData\Local\Programs\Python\Python310\lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 
373, in main
          json_out["return_val"] = hook(**hook_input["kwargs"])
        File "C:\Users\Avasam\AppData\Local\Programs\Python\Python310\lib\site-packages\pip\_vendor\pyproject_hooks\_in_process\_in_process.py", line 
143, in get_requires_for_build_wheel
          return hook(config_settings)
        File "C:\Users\Avasam\AppData\Local\Temp\pip-build-env-f0vjqonl\overlay\Lib\site-packages\flit_core\buildapi.py", line 23, in get_requires_for_build_wheel
          info = read_flit_config(pyproj_toml)
        File "C:\Users\Avasam\AppData\Local\Temp\pip-build-env-f0vjqonl\overlay\Lib\site-packages\flit_core\config.py", line 85, in read_flit_config  
          return prep_toml_config(d, path)
        File "C:\Users\Avasam\AppData\Local\Temp\pip-build-env-f0vjqonl\overlay\Lib\site-packages\flit_core\config.py", line 112, in prep_toml_config 
          loaded_cfg = read_pep621_metadata(d['project'], path)
        File "C:\Users\Avasam\AppData\Local\Temp\pip-build-env-f0vjqonl\overlay\Lib\site-packages\flit_core\config.py", line 770, in read_pep621_metadata
          raise ConfigError(
      flit_core.config.ConfigError: description must be specified under [project] or listed as a dynamic field
      [end of output]

  note: This error originates from a subprocess, and is likely not a problem with pip.
error: subprocess-exited-with-error

× Getting requirements to build wheel did not run successfully.
│ exit code: 1
╰─> See above for output.

note: This error originates from a subprocess, and is likely not a problem with pip.

So that's another small win for Hatchling (it's subjective, but I'd prefer being less restrictive, this isn't a package to upload to PyPI )

---

tl;dr: Flit is the fastest and smallest backend, with Hatchling as a close second (PDM is similar in speed, but bigger package).
But because flit is more opinionated/restrictive, Hatchling seems like the better immediate and long-term choice.
That is what I'm basing my approval on.

I'll give it a week or so for other maintainers to voice their objection, either technical or personal. And we can always easily swap out the backend.

Thanks for this PR!

[Avasam]

it was smallest build backend that was supported by uv.

Did you find any backend that doesn't work with uv?
Also looking at wheel size, flit is actually the smallest 😉 (but I agreed with Hatchling for other reasons listed)

[guitvcer]

Wow, thanks for the detailed analysis! Apparently I didn't notice about flitch :)

[sobolevn]

Tested locally, it works :)

Since it is not uploaded anywhere, I feel safe to merge it.
Thanks a lot for the PR! Congrats on your first typeshed contribution, please, come back for more 🎉

[Avasam]

I just added uv_backend to my above table. It's really fast, and basically free is you already use uv

[build-system]
requires = ["uv_build ~=0.9.5"]
build-backend = "uv_build"

[tool.uv.build-backend]
module-root = ""