search

fralau / mkdocs-macros-plugin

Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code.
https://mkdocs-macros-plugin.readthedocs.io
Other
318 stars 50 forks source link

Project is missing py.typed marker #219

Closed ssbarnea closed 2 months ago

ssbarnea commented 5 months ago

When adding the package, mypy complains about missing type marker.

src/mkdocs_ansible/__init__.py:10: error: Skipping analyzing "mkdocs_macros.plugin": module is installed, but missing library stubs or py.typed marker  [import-untyped]
src/mkdocs_ansible/__init__.py:10: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports

This can easily be sorted by just adding the py.typed inside the package, even before the full types are adopted by the project.

github-actions[bot] commented 5 months ago

Welcome to this project and thank you!' first issue

fralau commented 4 months ago

Is my understanding correct that mypy wants some kind of marker to allow static type checking of the package?

I see that warning comes from Ansible, so that suggests Mkdocs lives in an industrialized deployment environment.

Consider that I don't know everything about this field. Could I ask you to give me more context, so that I better understand why py.typed is important, and what problem it solves in your specific case?

kchr commented 2 months ago

@fralau This scenario occurs when a developer has mkdocs-macros-plugin installed in their own environment, and uses mypy to analyze not only their own source code but also any installed/imported packages found in the project environment (in this case it seems to be a project called mkdocs_ansible, but the issue has nothing to do with Ansible. It is related to how mypy in general behaves when it comes to analyzing dependencies in any Python project).

The warning will be raised by mypy when it encounters a package that does not declare that it has type hints. This can be declared in a number of ways, one of them being to include a file called py.typed in the package. See the following page for instructions on how to do so, making your package compliant to the PEP 561 standard:

https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages

As the page above says:

If you would like to publish a library package to a package repository yourself (e.g. on PyPI) for either internal or external use in type checking, packages that supply type information via type comments or annotations in the code should put a py.typed file in their package directory. For example, here is a typical directory structure:

setup.py
package_a/
    __init__.py
    lib.py
    py.typed