How do you give a compiled Python extension module type information with no source?

### Why the usual answer does not apply An extension module is a shared library — `_core.cpython-314-darwin.so` on macOS, a `.pyd` on Windows — built from C, C++, Rust or a compiler-generated intermediate. There is no `.py` file to annotate, and a type checker will not (and cannot safely) load and execute a binary to introspect it. So the only way to describe such a module to a checker is a stub file, which is exactly the case stubs were designed for. ### The layout Inside the package, the stub sits beside the binary with the module's plain name: ``` flightdiff/__init__.py flightdiff/py.typed flightdiff/_core.cpython-314-darwin.so flightdiff/_core.pyi ``` A checker resolving `from flightdiff import _core` finds `_core.pyi` and uses it. Two packaging details do the real work: the stub and the marker are data files, so the build backend must be told to include them, and the stub's name must match the extension's *module* name, not its full platform-tagged filename. A common refinement is to keep the compiled module private and wrap it in an annotated Python facade — `flightdiff/api.py` with inline annotations, re-exporting from `_core`. That gives you annotations that are actually checked against calling code, and confines the hand-written stub to the narrow binary boundary. It costs a layer of indirection and, on a hot path, a Python-level call, which is why plenty of projects stub the extension directly instead. ### Generating the first draft, and why it is only a draft Stub generators ship with the major checkers; they import the module and walk its attributes to emit a skeleton. For an extension module the yield is poor, because introspection of C functions is thin. Unless the module was built with tooling that embeds signature metadata, `inspect.signature` raises `ValueError` for its functions, and the generator can only write `def compare(*args, **kwargs) -> Any: ...`. That stub type-checks everything and catches nothing. The generated file is a starting skeleton — the names, the classes, the module structure — and every signature is yours to fill in from the C source or the documentation. ### The contract problem This is the part senior interviews care about. Nothing verifies a hand-written stub against the binary it describes. The checker trusts the stub absolutely, so a wrong stub is worse than no stub: with no types, consumers get `Any` and no false confidence; with a wrong one, they get green builds around a call that fails at runtime. Consider a flight-schedule differ whose comparison core is compiled: the stub says `compare(left: bytes, right: bytes, *, strict: bool = ...)`, the C function was changed to require a timezone argument, and every caller still checks clean. Worse, a stub that is wrong about *which* inputs are accepted can turn a rollback into a partial-failure rollback — half the callers were rebuilt against the corrected stub and half were not, and both pass their checks. The defences are ordinary engineering ones. Version the stub with the binary in the same distribution so they cannot be installed apart. Run a stub-consistency tool that imports the built module and diffs its runtime attributes against the `.pyi`, catching removed names, renamed classes and arity changes even when it cannot see parameter types. And treat the stub as covered by tests: a regression pack — say the differ's 340 recorded cases — exercised through the annotated public surface will catch a signature that no longer matches, because those calls are both type-checked and executed. ### When you do not own the package If the extension belongs to someone else, you cannot add files to their installed package. Publish a stub-only distribution instead: an installable whose importable directory is named `<package>-stubs` and contains only `.pyi` files, mirroring the original's module structure. Checkers prefer that over the runtime package's own types, so it fills the gap without touching the dependency, and it can be released and rolled back on its own schedule. If your coverage is incomplete, put `partial` in its `py.typed` so checkers keep consulting the runtime package for the rest. ### What to say in an interview Name the mechanism (a `.pyi` in the package plus the marker), be honest that generation gets you a skeleton and not signatures, and spend most of your answer on the drift problem — versioning, an import-and-diff consistency check, and tests that exercise the surface the stub describes. That is the difference between knowing stubs exist and having shipped one.