Falcon: feat: add type information - mypy support

[CoreyCole]

As of PEP 561 it is now possible for packages to provide typing information, with different options of how to do so. I'm wondering what would be the preferred course of action to include these.

It seems we could start with partial stubs where we could define things that would be most helpful/commonly used (i.e. request/response)

[CoreyCole]

This is an example of a separate stubs package for numpy https://github.com/numpy/numpy-stubs

[CoreyCole]

I'm still new to using mypy and I realized today we already have typing information for falcon, I just didn't know how to utilize it:

def on_post(self, req: falcon.Request, res: falcon.Response):

This gives me what I'm looking for. I'm going to leave this open to get clarification on the current state of type information in the repository to see if there is help needed anywhere for it.

[CoreyCole]

so the current state of falcon types is that they work well for annotations, but not for running mypy. When I run mypy on my project, I get errors like

error: Cannot find module named 'falcon'

I think this is because mypy doesn't look directly in site-packages unless it finds PEP 561 implementation or stubs. I've created this falcon-stubs project using stubgen: https://github.com/CoreyCole/falcon-stubs

Putting these in my project folder, i.e. myproject/stubs/falcon and then assigning the $MYPYPATH to point to that stubs folder is solving the problem for me

[CoreyCole]

Are maintainers here ok with me leaving those stubs up and open sourced for others to use/contribute to?

[rafi]

Would be lovely if falcon supported PEP 561

[vytas7]

@CoreyCole Falcon is open source software with a permissive license, you are very welcome to do any derivative work :slightly_smiling_face:

It may be interesting and useful for users incorporating mypy in their tool chain.

As for maintaining it officially with Falcon, it is always the question of cost, testing, available bandwidth etc.
Personally I think it may make even more sense for Falcon 3.0 or 3.1 when we are dropping Python 2.7 and 3.4, so the preliminary plan is we would, effectively, only support Python versions allowing type annotations natively. Then we could discuss the possibility of annotating Falcon itself without the need for stubs.

[kgriffs]

Now that we have dropped support for Python 2.7, let's move forward with adding type hints to Falcon's public interface directly via annotations.

[jxub]

I could help with that. Do I work against the last tag (2.0.0rc4), checkout directly from master or otherwise?

[vytas7]

Hi @jxub !
And that sounds great!!

You check out directly from master :+1: .
The 2.x series supports Python 2, and type annotations don't work there.

[jxub]

@vytas7 Perfect, thanks!

[jxub]

I've created a first PR to review the API class annotations (mostly for myself) at https://github.com/jxub/falcon/pull/1. I'm planning of getting rid of these type aliases on top in the api.py file ASAP. However, some types, like the handlers, have pretty complex signatures so I have to rely on the Any type as well.

[vytas7]

Important: it seems that Cython can now pick up and enforce those type annotations.
Which is great if it leads to an even further speed bump, but it is unfortunately not always the case, as demonstrated by @CaselIT.

We'll need to tread carefully when it comes to performance-sensitive parts, and we may need to tell Cython not to actually use those annotations in cases where they only lead to slowdowns.

[CaselIT]

Here are the relevant bit in the cython docs.
http://docs.cython.org/en/latest/src/tutorial/pure.html#static-typing

Just to specify, I've tried only a very naive test, so I don't think a meaningful conclusion could be drawn from it

[mcobzarenco]

What's the status of this issue? Does anyone have any experience using Falcon with types?

For context, I'm investigating replacing bottle in our product with Falcon. This project looks really exciting 💯, but worried about production readiness in the absence of static type checking

[Spenhouet]

@mcobzarenco My static type checker tells me:

import falcon
       ^^^^^^
       Stub file not found for "falcon"

and using falcon.Request as type annotation does not really help the static type checker.

So I guess the state is that falcon does not yet support static type checkers like MyPy or PyRight.

[SteKarab]

What else is expected of this ticket? Is it a matter of expanding/updating the stubs project?

[hojlind]

Is there any updates on this issue? As far as I can find, currently the only stubs available is the 3 year old ones found in the external repository. Trying to develop with type checking enabled is quite a hassle unfortunately.

[vytas7]

Hi @hojlind !
And no, unfortunately there are currently no updates on typing as we were focused on shipping 3.0, and then fixing a couple of bugs found therein as part of the 3.0.1 release.

However, now that the above has been delivered, we're working on merging the PR backlog, and brainstorming features for the 3.x series: https://github.com/falconry/falcon/issues/1894. Typing is on our radar, but we haven't decided its priority yet vs other potential improvements. (I've added it to the roadmap issue though.)

[hojlind]

That sounds great! I am rather new to doing larger projects in python, and equally new to how typing works in python, and what the general sentiment about adding types everywhere is. Adding stubs next to the source itself however, as suggested in #1894 sounds like a good idea, as long as the time is there for it of course :)
Am I wrong in assuming that it should be fairly straightforward, as the documentation seems to have types defined for parameters and return values everywhere? If not, perhaps I can be the next guy in line to say "i can do it".