Support Python typing

[asokolsky]

I get:

Skipping analyzing "icalendar": module is installed, but missing library stubs or py.typed marker - mypy

[niccokunzmann]

@asokolsky Thanks for reporting this:

• how do you generate this text - it looks like from a tool
• what would you like to see instead?
• what would be ways to approach this?

[asokolsky]

how do you generate this text - it looks like from a tool

I run mypy on my code which is using icalendar

what would you like to see instead?

No mypy warnings

what would be ways to approach this?

From https://mypy.readthedocs.io/en/stable/existing_code.html

Start small – get a clean mypy build for some files, with few annotations

• Write a mypy runner script to ensure consistent results
• Run mypy in Continuous Integration to prevent type errors
• Gradually annotate commonly imported modules
• Write annotations as you modify existing code and write new code
• Use MonkeyType or PyAnnotate to automatically annotate legacy code

Hope this helps.

[angatha]

Is this feasable for 4.x branches where the compatibility reaches back to 2.7 and 3.4? I remember that comments where used at that time to di type hinting which was changed in 3.5.

[asokolsky]

Is this feasable for 4.x branches where the compatibility reaches back to 2.7 and 3.4?

Don't take my word for it, but I think it is:

• Leave original source intact
• For python 3.x users provide stubs as a separate deliverable, similar to https://github.com/microsoft/python-type-stubs

[niccokunzmann]

I am happy to see a pull request that shows some examples of how to go about it.

Since the code is tested, is there a way to harvest the hints from the tests?

An idea is to have a mypy branch that is based on master and that tests the annotations and can be worked on until it is green.

What do you think?

[djbrown]

AFAIK there are the following options:

• inline type hints, not backwards compatible
• seperate type stubs, created manually or via mypy stubgen
  the stubs may be worked on and published via one of the following primary ways:
  • official python/typeshed project
  • inofficial microsoft/python-type-stubs, work in progress
  • new dedicated package for icalendar type stubs

[niccokunzmann]

I would (maybe falsely) assume that people using type hints also like to use later Python versions that have them built in. The master branch would receive the changes, according to the README:

We expect the master branch with versions 5+ receive the latest updates and features,
and the 4.x branch the subset of security and bug fixes only.

As such, inline typing in the files icalendar files can be used - if I am right that Python 3.7+ supports it.

[niccokunzmann]

How can you produce this? Which commands are you running?

[djbrown]

do you mean how to get started?

first of all you should install mypy: pip install mypy
then you check for typing issues: mypy src/icalendar/
and you can generate stub files, from which you can copy the type hints inline to the source code: stubgen src/icalendar/

[djbrown]

also relevant for this issue is PEP 561 – Distributing and Packaging Type Information

Package maintainers who wish to support type checking of their code MUST add a marker file named py.typed to their package supporting typing.

I'm not familiar with distributing packages though, but if I understand correctly, you would have to create an empty file /src/icalendar/py.typed and then extend yout setup.py with:

setup(
    ...
    package_data = {
        'icalendar': ['py.typed'],
    },
    ...
)

[niccokunzmann]

@djbrown @asokolsky @angatha thanks for the discussion! It is very clear to me now how to approach this and I am happy the see a pull request!

• generate stubs and copy them into the code
• run tests to make sure everything is typed (correctly)
• add py.typed marker
• make sure the marker is distributed