type stub packages (a documentation request)

[KDruzhkin]

Type stubs can be provided in separate packages. For example, a package foo has a companion package types-foo or foo-stubs.

With poetry, a typical pyproject.toml file looks like this:

[tool.poetry.dependencies]
pandas = ">=2.2.2"
psutil = ">=6.0.0"
tqdm = "^4.66.0"

[tool.poetry.group.dev.dependencies]
mypy = ">=1.10.0"
pandas-stubs = ">=2.2.2"
types-psutil = ">=6.0.0"
types-tqdm = ">=4.66.0"

So, with poetry, the development virtual environment contains both mypy and the stub packages (used by mypy to check the project).

How should I handle stub packages with uv? Do they belong in the tool environment for mypy? If yes, how do I put them there?

[charliermarsh]

Good question, we can document this. In general MyPy and the type stubs should all be in [tool.uv.dev-dependencies].

[KDruzhkin]

So, mypy is different from most other tools: it does not work well in isolation.

To be precise, if you want mypy to follow imports:

[tool.mypy]
follow_imports = "normal"

... then uv tool run mypy is not the way to go.

[zanieb]

Yeah this is explicitly noted at https://docs.astral.sh/uv/concepts/tools/#relationship-to-uv-run — do we need to provide more context somewhere?

[KDruzhkin]

Yeah this is explicitly noted at https://docs.astral.sh/uv/concepts/tools/#relationship-to-uv-run — do we need to provide more context somewhere?

For any other tool, I would say, no.

But mypy is not a tool among many, it is the tool for type checking, and it deserves a section of its own.

[zanieb]

We do literally mention mypy there though. I'm not quite sure a section that says "mypy is a dev dependency" makes sense for the project documentation. Maybe we could do an integration guide for it.

[KDruzhkin]

Hmm…

It would be nice if the tools section started with something like:

“… there are two general categories of tools: 1) tools which work in isolation, e.g. ruff, and 2) tools which require access the development environment, e.g. mypy, pytest. For the first category uv includes a dedicated interface…”

Yes, the docs say just so, but they say it at the end of the section, under the subtle “Relationship to uv run”.

[KDruzhkin]

Anyway, thanks for your fantastic work on ruff and uv!

[zanieb]

That makes sense, I think. I will look into that.