typing: add middleware protocols

[jkmnt]

Summary of Changes

Typed the middleware classes with union of protocols.
Middleware class may conform to any protocol of the union to pass the type check

It's not perfect due the nature of python's static duck typing, but better than the plain object ) Class may have correct signature for process_request(), but wrong signature for process_response(). It would be accepted since MiddlewareWithProcessRequest says nothing about the process_response.

But if user explicitly states implemented protocols, then the typecheker will ensure strict conformance.

class MyMiddleware(MiddlewareWithProcessRequest, MiddlewareWithProcessResponse):
    def process_request(...): ... # ok, pass
    def process_responce(...):  # won't pass (typo). process_response is required 

The protocols definitions are in the private falcon._typing module now. Should they be moved to the public falcon.typing to support this usecase ?

The protocols names are long and noisy. Use some abbreviations ?

Related Issues

#2372

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (ead6535) to head (0827ad1).

Additional details and impacted files

@@            Coverage Diff            @@
##            master     #2390   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           64        64           
  Lines         7728      7732    +4     
  Branches      1071      1071           
=========================================
+ Hits          7728      7732    +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[vytas7]

One thing that we need to investigate (not necessarily related to this change) is how to control annotations in Sphinx. Because if this new union of protocols gets evaluated/expanded, it really clutters the docs... 😬

[vytas7]

As mentioned, I'll try to look into whether Sphinx can be tweaked not to unroll the whole union, and how different editors behave.

Because right now it is a bit of a showstopper wrt Sphinx:

[vytas7]

It might be possible to resolve the Sphinx issue via autodoc_type_aliases, but haven't tried this myself.