The Importance of Adding a `py.typed` File to Your Typed Package

For the Python programming, type checking might be an important aspect aspect that ensures the correctness of your code. The mypy type checker is a powerful tool that uses type annotations to verify your code. However, it might not recognize the type hints provided by your package unless you include a py.typed file. This is a common oversight that can lead to incorrect package publishing.

Understanding py.typed

The py.typed file is a marker file that indicates to type checkers like mypy that your package comes with type annotations. Without this file, the type checker won't use the type hints provided by your package, leading to potential type errors. This requirement is outlined in PEP-561 and the mypy documentation.

Adding py.typed to Your Package

Adding a py.typed file to your package is straightforward. Simply create a py.typed file in your package directory and include it in your distribution.

If you're using poetry, you can add the following lines under the [tool.poetry] section of pyproject.toml:

packages = [
  {include = "mypackage"},
  {include = "mypackage/py.typed"},
]

For those using setup.py, you can add package_data to the setup call:

setup(
    package_data={"mypackage": ["py.typed"]},
)

After adding the py.typed file, release a new version for your package. This will ensure that the type information from your packages works as expected.

Conclusion

If you're a Python package maintainer, don't forget to include a py.typed file in your typed package. This simple step can make a significant difference in ensuring the correctness of your code and the usability of your package. It's a small effort that goes a long way in maintaining the quality and reliability of your Python package.

Credits to Wu Haotian for the article Don't forget py.typed for your typed Python package - DEV Community - I have learned about this mechanism from that post.