Situation

Python 3.5 introduced the typing module. As soon as we are sunsetting the 2.9.x release of semver, it raises the question if we should use type hints for our 3.x.y release of semver.

Currently, we don't use it for our functions and methods.

To avoid any misinterpretations, the typing module contains this note:

The Python runtime does not enforce function and variable type annotations. They can be used by third party tools such as type checkers, IDEs, linters, etc.

To start discussion and to get a better picture where we stand on this topic, I've opened this issue. 😉

Example

This is a short example of a type hint for the parse function:

def parse(version: str) -> dict:
    """
    Parse version to major, minor, patch, pre-release, build parts.

    :param version: version string
    :return: dictionary with the keys 'build', 'major', 'minor', 'patch',
     and 'prerelease'. The prerelease or build keys can be None
     if not provided

Bernát Gábor recommends that “type hints should be used whenever unit tests are worth writing.”

Pros and Cons

I've collected some pros and cons, probably there are more that I haven't listed here. This list is by no means exhaustive. Feel free to amend it.

Pros

• Helps to catch type errors when testing with mypy.
• Could support IDEs to provide a better popup help.
• Improves documentation when using the sphinx-autodoc-typehints plugin.
• Help you as a developer to write better code.

Cons

• A slight impact of performance.
• Needs another dependency when checking for type hints (mypy).
• Needs a bit more time to add it.
• Works best with modern Python (version >= 3.5).

Scope

If we want this, it will only be implemented in the 3.x.y release of semver. Older releases (2.9.x) are not covered by this issue and won't be modified.

Furthermore, we need to create a semver.pyi file with the command stubgen (integrated in mypy).

See also

• https://realpython.com/lessons/pros-and-cons-type-hints/
• https://www.python.org/dev/peps/pep-0483/
• https://www.bernat.tech/the-state-of-type-hints-in-python/
• https://www.python.org/dev/peps/pep-0561/ (Distributing and Packaging Type Information)