Why does a built wheel sometimes omit the py.typed marker file?

### Two different file sets It helps to keep three things apart. There is the **source tree** you edit, the **sdist** (a source archive), and the **wheel** (the installable artefact). Each is built by rules, and the rules are not the same. A file being in the source tree implies nothing about the wheel; a build backend chooses what to copy. Backends split roughly into two camps. Some treat the package directory as the unit and copy everything inside it, so dropping `py.typed` next to `__init__.py` is all you do. setuptools is the one that bites: it discovers *packages* and takes their Python modules, and non-code files inside a package are "package data" that must be declared, or must arrive by way of the sdist-inclusion machinery. The direct declaration in `pyproject.toml` looks like this: ```toml [tool.setuptools.package-data] billing = ["py.typed"] ``` The classic near-miss is `MANIFEST.in`. It governs what goes into the **sdist**; it only influences the wheel indirectly, through the setting that tells setuptools to also take the data files it found for the source archive. Teams add a `MANIFEST.in` line, watch the sdist grow the file, and assume the wheel followed. It may not have. ### Why nobody notices During development the library is installed in editable mode, which wires the environment straight to your working tree. A checker resolving `import billing` there reaches your actual directory, marker and all, so the library type-checks its own tests perfectly. Consumers install the wheel. Inside their `site-packages` the package arrives without the marker, so every one of them silently loses type information from your library — and the report they get names their import, not your build, which is why the bug is usually reported to you as "your library is untyped" long after the release. This is not specific to the marker; it is the general shape of the package-data trap. It just happens that a missing `py.typed` fails *quietly*: nothing crashes, no import error, only the gradual erosion of checking in the code that depends on you. Consider a subscription-billing library that a dozen internal teams import. The release notes announce that the library is now fully typed; the wheel ships without the marker; every consuming team still gets `Any` for `billing.total(...)`, and nobody finds out until someone passes a currency string where cents were expected and nothing complains. ### Verifying instead of hoping A wheel is a zip archive, so verification takes one command against the built file rather than the source tree: ```console $ python -m zipfile -l dist/billing-1.0.0-py3-none-any.whl ``` The listing must contain `billing/py.typed`. The stronger version of the same check installs the built wheel into a throwaway environment and inspects the installed package directory, because that reproduces exactly what a consumer's checker sees, including any renaming or layout surprise. Either check belongs in the release pipeline: build, assert the marker is present in the artefact, then publish. A one-line assertion in CI is worth more than a convention, because the failure mode is invisible to every test you run against your own source tree. ### Where layout comes into it Layout choices interact with the declaration. Under a `src/` layout the marker lives at `src/billing/py.typed` in the tree but must arrive as `billing/py.typed` in the wheel, so a package-data entry written against the on-disk path rather than the package name silently matches nothing. Subpackages inherit the top-level marker and need no entry of their own, but a distribution installing two independent top-level packages needs a declaration for each. And when a project changes build backend, declarations written for the previous one are ignored rather than reported as invalid — exactly the kind of change that reintroduces the bug months after someone fixed it. ### Related traps in the same family If you ship inline stub files (`.pyi`) alongside your modules rather than plain annotations, they are non-code files too and are lost by exactly the same mechanism, with exactly the same silence. Sdist-only inclusion is another: publishing both an sdist and a wheel where only the sdist carries the marker means consumers who install from the wheel — nearly all of them — get nothing, while the rare source install works, producing a wonderfully confusing bug report.