Missing type hints

[vallon]

Is there any interest in supporting type hints? From a package user's point of view, the high-level entry points could be annotated:

With a stub dploy/__init__.pyi:

import pathlib
from typing import Optional, Union, List
Path = Union[str, pathlib.Path]

def stow(
    sources: List[Path],
    dest: Path,
    is_silent: bool = True,
    is_dry_run: bool = False,
    ignore_patterns: Optional[List[str]] = None
) -> None: ...
def unstow(
    sources: List[Path],
    dest: Path,
    is_silent: bool = True,
    is_dry_run: bool = False,
    ignore_patterns: Optional[List[str]] = None
) -> None: ...
def link(
    source: Path,
    dest: Path,
    is_silent: bool = True,
    is_dry_run: bool = False,
    ignore_patterns: Optional[List[str]] = None
) -> None: ...

And an empty py.typed.

The builder would also need to deploy the '*.pyi' and 'py.typed' into the output. For setuptools:

[tool.setuptools.package-data]
"*" = ["*.pyi", "py.typed"]

But, I don't know about poetry.

mypy would use the stub files in place of the real code.

More aggressive would be to annotate __init__.py, but I see there is a "requires python 3.3", which I think would break python 3.3 (import typing was added in 3.5).

Or, the package itself could use type annotations internally (ie: mypy --strict), but that's probably another discussion and larger change.

Effectively, two new files would be added which would not interfere with any runtime use of the module, but would allow mypy to typecheck calls to dploy.(stow, unstow, link).