Skip to content

chore: add py.typed marker for PEP 561 typing support#11

Open
speckhard wants to merge 1 commit intoLeMaterial:mainfrom
speckhard:chore/py-typed-marker
Open

chore: add py.typed marker for PEP 561 typing support#11
speckhard wants to merge 1 commit intoLeMaterial:mainfrom
speckhard:chore/py-typed-marker

Conversation

@speckhard
Copy link
Copy Markdown

@speckhard speckhard commented Apr 26, 2026

Summary

Add an empty py.typed marker file so downstream type checkers (mypy, pyright, pyre) actually pick up the hand-maintained .pyi stubs shipped alongside the package.

PEP 561 requires this marker for "inline" packages — packages that ship their stubs in the same directory as the runtime code, which is what atompack does. Without the marker, mypy / pyright treat every imported atompack symbol as Any, even though the stubs are correct.

Why no pyproject.toml change

Maturin ships everything under python-source = "python" by default. The new file is in atompack-py/python/atompack/py.typed, so it lands in the wheel without any [tool.maturin] include change. The three .pyi stubs already in that directory ship the same way today — confirmed by inspecting the published atompack-db==0.2.1 wheel.

Verification

Maturin packaging path. Inspected the current PyPI wheel:

$ unzip -l atompack_db-0.2.1-cp311-cp311-macosx_11_0_arm64.whl | grep atompack/
   1516  atompack/__init__.py
  20506  atompack/__init__.pyi
2074560  atompack/_atompack_rs.cpython-311-darwin.so
  13046  atompack/_atompack_rs.pyi
  21944  atompack/ase_bridge.py
  15161  atompack/hub.py
   4492  atompack/hub.pyi

The three .pyi stubs ship today via python-source = "python". A sibling py.typed rides the exact same path.

End-to-end mypy check. Fresh Python 3.11 venv with the current PyPI wheel installed.

Before adding py.typed:

$ mypy -c "import atompack; reveal_type(atompack.Database)"
<string>:1: error: Module has no attribute "Database"  [attr-defined]
<string>:1: note: Revealed type is "Any"
Found 1 error in 1 file (checked 1 source file)

After touch site-packages/atompack/py.typed:

$ mypy -c "import atompack; reveal_type(atompack.Database)"
<string>:1: note: Revealed type is "def (path: str, compression: str =, level: int =, overwrite: bool =) -> atompack.Database"
Success: no issues found in 1 source file

Confirms the marker is exactly what unlocks the existing stubs for downstream type checkers.

References

Without this marker, downstream type checkers (mypy, pyright, pyre)
ignore the hand-maintained .pyi stubs that ship alongside the package
and collapse imported atompack symbols to Any.

PEP 561 requires the marker for "inline" packages — packages that ship
their stubs in the same directory as the runtime code, which is what
atompack does (__init__.pyi, _atompack_rs.pyi, hub.pyi all live next to
__init__.py).

Maturin ships everything under python-source = "python" by default, so
the new file lands in the wheel without any [tool.maturin] include
change.
@speckhard speckhard marked this pull request as ready for review April 28, 2026 21:37
@speckhard speckhard changed the title [DRAFT] chore: add py.typed marker for PEP 561 typing support chore: add py.typed marker for PEP 561 typing support Apr 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant