Missing py.typed for type checking?

[gishor]

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

[evertlammerts]

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:

1. publish the stubs in a separate package like we did before
2. publish the stubs with the code itself, and include a py.typed file

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]

1. publish the stubs in a separate package like we did before

One benefit of this approach is it allows downstream projects to install just the stubs for type checking workflows.

E.g, in narwhals we can do this for pandas and pyarrow, but duckdb is a full install.

That being said, I've never had an issue installing duckdb 😅

[edgarrmondragon]

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.