Repository navigation
Missing py.typed for type checking? #57
Description
What happens?
After upgrading from 1.3.2 to 1.4.0, mypy complains whenever we import duckdb.
The error message is of the form:
error: Skipping analyzing "duckdb": module is installed, but missing library stubs or py.typed marker [import-untyped]
error: Skipping analyzing "duckdb.typing": module is installed, but missing library stubs or py.typed marker [import-untyped]
The .pyifiles moved from the duckdb-stubs folder to duckdb itself. This page says:
Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing. This marker applies recursively: if a top-level package includes it, all its sub-packages MUST support type checking as well.
And:
For stub-only packages adding a py.typed marker is not needed since the name *-stubs is enough to indicate it is a source of typing information.
So is a py.typed file needed now with the new version?
To Reproduce
$ echo "import duckdb" > test.py
# Success with 1.3.2
$ pip install duckdb==1.3.2 > /dev/null && mypy test.py
Success: no issues found in 1 source file
# Error with 1.4.0
$ pip install duckdb==1.4.0 > /dev/null && mypy test.py
test.py:1: error: Skipping analyzing "duckdb": module is installed, but missing library stubs or py.typed marker [import-untyped]
test.py:1: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 1 source file)
# Adding py.typed fixes the issue
$ touch $(dirname $(python -c "import duckdb; print(duckdb.__file__)"))/py.typed
$ pip install duckdb==1.4.0 > /dev/null && mypy test.py
Success: no issues found in 1 source file
OS:
OSX
DuckDB Package Version:
1.3.2 and 1.4.0
Python Version:
3.13.7
Full Name:
Gishor Sivanrupan
Affiliation:
Exaforce
What is the latest build you tested with? If possible, we recommend testing with the latest nightly build.
I have tested with a stable release
Did you include all relevant data sets for reproducing the issue?
Not applicable - the reproduction does not require a data set
Did you include all code required to reproduce the issue?
- Yes, I have
Did you include all relevant configuration to reproduce the issue?
- Yes, I have
Activity
Add empty py-typed file
Temporarily ignore typing for duckdb
evertlammerts commentedon Sep 19, 2025
Before extracting to a dedicated repo, we published three top-level packages in the same distribution package. One of them was
duckdb-stubs, which contained only the stub files. I hadn't realized that moving the stubs into the top-level package would make a difference, that was a clear miss on my end.Looking at the spec (and these easier to read docs by mypy) we have two options:
The spec says that shipping stubs with the code is preferred: "For package maintainers wishing to ship stub files containing all of their type information, it is preferred that the *.pyi stubs are alongside the corresponding *.py files." I'm looking into what works best for us right now. Our stubs were incomplete (I guess that's a bit of a euphemism) and the scripts that generated them hadn't been used for a while. This is not a bad moment to make some improvements.
dangotbanned commentedon Sep 21, 2025
One benefit of this approach is it allows downstream projects to install just the stubs for type checking workflows.
E.g, in
narwhalswe can do this forpandasandpyarrow, butduckdbis a full install.That being said, I've never had an issue installing
duckdb😅edgarrmondragon commentedon Sep 21, 2025
FWIW pyarrow is having a discussion (apache/arrow#45919) that might result in them either publishing stubs along with the main package, or inlining types.
Add linting and formatting (#72)
chore(deps): avoid duckdb 1.4.0 because of typing/devex issues
chore(deps): avoid duckdb 1.4.0 because of typing/devex issues
ci: appease mypy while stubs package is in development
evertlammerts commentedon Oct 2, 2025
I'm about to land a pretty involved PR that hopefully gets everybody's static type checkers, linters etc happy again. This will go into 1.4.1 which is set to release on Monday. I'll build a dev release once this is landed with a recent duckdb core dev release.
@gishor @vyasr @leamingrad @rclement @KyleKing you've all tagged this issue. It's late days, but it would be useful if some of you can check whether your setups are going to be happy with these changes, so that you don't have to wait for another bugfix release. I'll post the package version here as soon as it's on pypi.
Some notable / risky? changes that are worth evaluating when you test:
duckdbpackage and a dedicated_duckdb-stubspackage I went with the latter. They should get picked up.duckdb.typingandduckdb.functionalmodules are deprecated in favor of respectivelyduckdb.sqltypesandduckdb.func. I've moved all internal references (except in tests) so hopefully importingduckdbnever accidentally shadowstyping. Shadowing issues somehow seem to be more prominent now, at least in my IDE. I don't know why this is but it'd be good to know this doesn't get in anybody's way.py.typedfile in theduckdbpackage.Adding stubs and making mypy pass (#96)
evertlammerts commentedon Oct 2, 2025
Use this version to verify: https://pypi.org/project/duckdb/1.4.1.dev135/. Feedback very welcome!
rclement commentedon Oct 3, 2025
Thanks @evertlammerts for issuing a dev release with a fix so quickly!
On my side, the fix is working (simply using
mypy --strict).I have a draft PR with explicit usage of 1.4.1.dev135: datalpia/laketower#126
gishor commentedon Oct 3, 2025
The fix is also working on our codebase, thanks @evertlammerts!
KyleKing commentedon Oct 3, 2025
Ditto, thanks for prioritizing this patch!
fix: upgrade to typed duckdb
vyasr commentedon Oct 6, 2025
I verified this as well on the polars-benchmark repository where I originally found and tagged this issue. PR to reenable is pola-rs/polars-benchmark#175 once 1.4.1 is released. Thanks for the fix!
evertlammerts commentedon Oct 7, 2025
1.4.1 just released: https://pypi.org/project/duckdb/1.4.1/
Thanks for the help all!
ci(typing): Let `mypy` follow `duckdb` imports