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.

[lgarron]

I was also very, very confused by this. Right now, the documentation gives me the expectation that I can run:

uv tool install mypy # optional
uv tool run mypy .

This tells you to run mypy --install-types, which works but does nothing.

But it seems I need to run:

uv add --dev mypy
uv tool run mypy .

It would be really nice for the documentation to spell this out, and to explicitly mention this for mypy.

(Even greater would be if uv could somehow abstract this kind of unhermetic ickiness and add a mechanism for uv tool run mypy . to work. At this point, I'd be happy even if it's just a hack for mypy explicitly. A caution message to the effect of "hey, we're running an abstraction layer to do what you probably do want, here's a link if you want the gnarly deets" would be more than enough for me. I'd much rather have my tools do the right things out of the box to contain mypy's abstraction leakage, than to keep track of ecosystem quirks by hand. 😅)