Add py.typed marker file

[ymyzk]

Problem

#131 added type hints to the pdpyras library. However, users of pdpyras cannot use the type hints in their projects using pdpyras. Here's an example

$ pip install mypy pdpyras
...
Successfully installed certifi-2024.12.14 charset-normalizer-3.4.0 idna-3.10 mypy-1.13.0 mypy-extensions-1.0.0 pdpyras-5.3.0 requests-2.32.3 typing-extensions-4.12.2 urllib3-2.2.3


$ echo 'import pdpyras' > run.py

$ mypy run.py
run.py:1: error: Skipping analyzing "pdpyras": module is installed, but missing library stubs or py.typed marker  [import-untyped]
run.py:1: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
Found 1 error in 1 file (checked 1 source file)

This is because pdpyras does not have py.typed marker file in the packaged distribution. Reference: https://typing.readthedocs.io/en/latest/guides/libraries.html

I'm not sure if this is intended by the maintainers of pdpyras. If the maintainers expect users to enjoy type hints in the pdpyras, it's nice to fix this problem.

Solution

It would be great if we can simply add the py.typed file to pdpyras, but it doesn't work because

• pdpyras is a library that has one top-level module pdpyras.py, not a package.
• py.typed is not supported for such top-level modules yet. Issue: Type stubs for single-file top-level modules python/typing#1333

There are a few approaches we could fix the issue.

1. Convert pdpyras.py from a module to a package and put py.typed in the package. I've created a PoC for this: main...ymyzk:pdpyras:py-typed-poc
2. Wait for Type stubs for single-file top-level modules python/typing#1333 to be fixed.

I'm happy to create a PR for this issue, but I'd like to know what is the preferred solution by the maintainers first. Thanks!

[Deconstrained]

Hello @ymyzk , thank you for the suggestions! Type hints have up to this point been added as a forward-looking style convention and to simplify the built-in documentation (e.g. replacing :type: and :rtype: in Sphinx docstrings).

The refactor/restructuring of the module into a package may be undertaken as a future project, but for now (FYI) we're holding off on authoring and reviewing bigger changes while we work on migrating this project to the new pagerduty name in the package index, of which we just recently gained custody.

I'm going to leave this issue open so it doesn't get forgotten in the process and will cross-link the new issue when it's created in the new project.

[ymyzk]

Thanks for the thoughtful answer, @Deconstrained! I can understand project's plan and wait for the type hints to be available to the pdpyras users in the future. It's also great to hear that this project can be moved to "pagerduty" on PyPI. 👍

[Deconstrained]

Recorded as PagerDuty/python-pagerduty#26