typing changes in 4.2 require code changes

[jap]

After upgrading one of our projects to 4.2, our type checker had a small nervous breakdown.

In our testing suite, we have some fixtures that return an App instance, annotated as bare falcon.App. With the generics introduced in #2513 these now need to be annotated as falcon.App[falcon.Request, falcon.Response] which is slightly cumbersome.
This also applies to other things like In our case the SyncMiddleWare type which appears to have become impossible to use as it lacks a way to inject generics (we're still annotating a list of middlewares as list[falcon._typing.SyncMiddleWare] but that is just for documentation I guess.)

It looks like it is possible to make those _ReqT etc typevars have a default value of Request, which would remove the need to explicitly add those types to the annotation when referring to falcon.App with default request/response types, but that default argument is only available with Python 3.13+ so not in all versions supported by falcon.

One solution that does not require waiting for 3.13 to be baseline is to implement a version check and add these defaults only when on 3.13+, so something like

if sys.version >= (3,13):
  _ExcT = TypeVar('_ExcT', bound=Exception, default=Exception)
  _ReqT = TypeVar('_ReqT', bound=Request, contravariant=True, default=Request)
  _RespT = TypeVar('_RespT', bound=Response, contravariant=True, default=Response)
else:
  _ExcT = TypeVar('_ExcT', bound=Exception)
  _ReqT = TypeVar('_ReqT', bound=Request, contravariant=True)
  _RespT = TypeVar('_RespT', bound=Response, contravariant=True)

I also saw that identical typevars exist in _typing.py ; maybe it is a good idea to import them from there in app.py so they only need to be defined once -- or is there some coding style rule in place that forbids importing types marked as private?

Anyway, I'll whip up one or a bunch of PRs addressing these things.

[vytas7]

After upgrading one of our projects to 4.2, our type checker had a small nervous breakdown.

Ouch 😰, but thanks a lot for the detailed feedback @jap!!!

If you use --strict type checker settings, the effect of new generic App types is documented here: https://falcon.readthedocs.io/en/stable/api/typing.html#app-types.

We don't provide SemVer-like guarantees for type annotations yet, especially not for the private ones from _typing.py.
But we do try to keep the impact of the changes minimal, so once again, thanks a lot for taking the time to report all this.

It is awesome if it is possible to avoid this with 3.13+ TypeVar defaults. Yes, your approach to check the interpreter's version is totally fine, we are already doing that in _typing.py.

Regarding SyncMiddleware, I guess we ought to publish it in typing.py.
However, could you elaborate what you mean by saying that it is impossible to inject generics?
Cf:

>>> import falcon
>>> from falcon._typing import SyncMiddleware
>>> SyncMiddleware[falcon.Request, falcon.Response]
typing.Union[falcon._typing.WsgiMiddlewareWithProcessRequest[falcon.request.Request, falcon.response.Response], falcon._typing.WsgiMiddlewareWithProcessResource[falcon.request.Request, falcon.response.Response], falcon._typing.WsgiMiddlewareWithProcessResponse[falcon.request.Request, falcon.response.Response]]

And yes, it is OK to colocate these TypeVars in _typing.py.

Anyway, I'll whip up one or a bunch of PRs addressing these things.

Thanks a lot in advance! If the concepts are independent from each other, a number of small PRs is usually easier/faster to get reviewed and merged (divide et impera), but we would welcome your suggestions either way.

[CaselIT]

Using defaults in 3.13 is a good suggestion, thanks. I did not think about it when reviewing the pr