feat: introduce type hints (MVP)

[vytas7]

Closes #1350

This is only to get the ball rolling though, with an emphasis on the most commonly used, publicly documented functionality.
We'll have to expand typing later in follow-up PRs. One of such PRs is already in Draft: #1944.

[codecov]

Codecov Report

Merging #1947 (f32943c) into master (1e34bf4) will not change coverage.
The diff coverage is 100.00%.

@@            Coverage Diff            @@
##            master     #1947   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           62        62           
  Lines         6806      6829   +23     
  Branches      1098      1098           
=========================================
+ Hits          6806      6829   +23     

Impacted Files	Coverage Δ
falcon/asgi/multipart.py	100.00% <ø> (ø)
falcon/media/multipart.py	100.00% <ø> (ø)
falcon/app.py	100.00% <100.00%> (ø)
falcon/app_helpers.py	100.00% <100.00%> (ø)
falcon/asgi/app.py	100.00% <100.00%> (ø)
falcon/errors.py	100.00% <100.00%> (ø)
falcon/media/base.py	100.00% <100.00%> (ø)
falcon/request.py	100.00% <100.00%> (ø)
falcon/response.py	100.00% <100.00%> (ø)
falcon/routing/converters.py	100.00% <100.00%> (ø)
... and 4 more

[CaselIT]

looks mostly ok to me. I've left a suggestion and replied to a TODO

[kgriffs]

Very nice! This patch is a solid improvement.

[kgriffs]

Just https://github.com/falconry/falcon/pull/1947/files#r1145637935 otherwise LGTM regarding my previous comments.

[CaselIT]

I see that the generic were not added like in list, dict, tuple, etc.

I guess we can to a pass on them later

[vytas7]

I haven't had the time to finish this yet @CaselIT @kgriffs... As discussed on Gitter, I'll remove the generics and try to type as much as possible using plain Request and Response.

[CaselIT]

I haven't had the time to finish this yet @CaselIT @kgriffs... As discussed on Gitter, I'll remove the generics and try to type as much as possible using plain Request and Response.

I was referring to generic only on builtin containers such as list, dict, iterable, tuple, etc

[vytas7]

@CaselIT See my other comment, I'm not convinced there is any difference in elaborating that way with [Any].

See, for instance:
test.py

from typing import Iterable


def print_all(iterable: Iterable, header: str = '== Items ==') -> None:
    print(header)
    for index, item in enumerate(iterable):
        print(f'{index+1}: {item!r}')


def main() -> None:
    print_all('ABC', header='=====')
    print_all(None)
    print_all(header=3)


if __name__ == '__main__':
    main()

$ mypy test.py 
test.py:12: error: Argument 1 to "print_all" has incompatible type "None"; expected "Iterable[Any]"  [arg-type]
test.py:13: error: Missing positional argument "iterable" in call to "print_all"  [call-arg]
test.py:13: error: Argument "header" to "print_all" has incompatible type "int"; expected "str"  [arg-type]

Judging from the error messages, Iterable and Iterable[Any] are simply synonymous.

[kgriffs]

🥳

[dkbarn]

How certain are we that the changes made here actually have the intended effect? I'm noticing that the py.typed file was never added as package data, it was only added in the MANIFEST.in. When I install the latest version of falcon (3.1.3), there is no py.typed file present in the install dir. This means mypy continues to complain when importing falcon:

error: Skipping analyzing "falcon": module is installed, but missing library stubs or py.typed marker  [import-untyped]

[vytas7]

Hi @dkbarn! We're still working on improved typing, this was just a start. But the main reason you are not even seeing any py.typed is that the changes haven't been incorporated into any stable release yet. This and other typing improvements will be shipped as part of 4.0.0.

[dkbarn]

Sounds good, thanks for the explanation @vytas7 !

[vytas7]

Thanks for understanding, I know our velocity has been less than stellar...

For the time being, you can also give the latest development snapshot a shot, and see if it works better with Mypy:

pip install git+https://github.com/falconry/falcon