Type Annotation and mypy support

[Kludex]

Checklist

• [X] There are no similar issues or pull requests for this yet.
• [x] I discussed this idea on the community chat and feedback is positive.

Summary

I've seen somewhere here that we want to have mypy. To be more organized, I've created the table below, so we can divide and conquer :sunglasses: :+1:

I'll be creating the PRs for those files in the following days.

All files

uvicorn
├── config.py ✅
├── _handlers ✅
├── importer.py ✅
├── __init__.py ✅
├── lifespan ✅
├── logging.py ✅
├── loops ✅
├── __main__.py ✅
├── main.py ✅
├── middleware ✅
├── protocols ➖
│   ├── http ✅ 
│   ├── __init__.py ✅
│   ├── utils.py ✅
│   └── websockets ➖
│       ├── auto.py ✅
│       ├── __init__.py ✅
│       ├── websockets_impl.py ✅ 
│       └── wsproto_impl.py ➖
├── server.py ✅
├── subprocess.py ✅
├── supervisors ✅
└── workers.py ✅

✅: Merged. ➖: PR available / WIP. ❌: Available to pick.

EDIT: I've simplified the report.

[jkklapp]

@Kludex are the files without a PR associated "up for grabs"?

[Kludex]

Yes. But I think both h11 and httptools implementation files need others to be merged before (not sure).

But yeah, you can go for it. Ping me on that PR once you've finished so I can update the list above, please. Also, be aware that we're trying to match this: https://github.com/django/asgiref/blob/main/asgiref/typing.py, which is on the main branch, but it was not released yet.

EDIT: Looks like there will be a release on asgiref today. So we can start using it.

[br3ndonland]

Thanks for initiating this, @Kludex! 👏

It would be great to have type annotations in this project, and I'm happy to help. I'll start contributing PRs and code reviews as time allows.

[br3ndonland]

This blog post by @tomchristie inspired me to be more diligent about using type annotations (and asyncio):

Python async frameworks - Beyond developer tribalism

Having to think about if a function does or doesn’t make I/O or could otherwise block is unarguably more complex than not having to think about it. It’s also more precise - you’re having to think about that for a reason, and done properly it’s presenting you with more information as a result. Being able to reason more clearly about which parts of your framework stack do or don’t perform I/O has a cost but also brings benefits.

There’s an analogy to make there in that writing Python using explicitly enforced typing is likely to be a harder than writing Python in an untyped style. It’s harder because you’re also being more precise. That’s not necessarily either good or bad, but it is definitively different.

I would include unit testing as a third entry in this category. After consistently working at unit testing, type annotations, and asyncio, a developer's understanding of their code will be in a completely different realm than before.

[euri10]

ADDED tests:

• [ ] tests
  • [x] conftest.py
  • [x] importer
    • [x] init.py
    • [x] raise_import_error.py
    • [x] test_importer.py
  • [x] init.py
  • [ ] middleware
    • [ ] test_debug.py
    • [ ] test_logging.py
    • [ ] test_message_logger.py
    • [ ] test_proxy_headers.py
    • [ ] test_wsgi.py
  • [ ] protocols
    • [ ] test_http.py
    • [ ] test_utils.py
    • [ ] test_websocket.py
  • [x] response.py
  • [ ] supervisors
    • [x] test_multiprocess.py
    • [ ] test_reload.py
  • [ ] test_auto_detection.py
  • [x] test_cli.py
  • [x] test_config.py
  • [x] test_default_headers.py
  • [x] test_lifespan.py
  • [x] test_main.py
  • [x] test_ssl.py
  • [x] utils.py

[sebastian-philipp]

(would be great to have a py.typed file as well)

[Kludex]

Yes. py.typed, as per PEP 561, will be added when all files are covered.

[Kludex]

Only 3 missing... I'm excited! We are almost there!

[Kludex]

Only 2 missing 🤩

[Kludex]

One missing. One... 🙏 😭 🎉 🏃

[ananthb]

Are we there yet?

[Kludex]

You'll see a GIF with fireworks when we finish here... 😅

There's still one file missing. The thing is that while adding type annotations we usually find small bugs, and those need to fixed separately before the file gets fully type annotated.

We are getting there.

[liorsbg]

This is awesome

[davidbrochart]

Maybe a dumb question, but will this allow mypyc compilation?

[Kludex]

It's on my plans to study the possibility, but I know nothing about mypyc.

@abersheeran knows stuff. :eyes:

[abersheeran]

mypyc requires stricter type annotations and has little support for dynamic features. uvicorn may not be ready yet.

By the way, In baize, mypyc improves performance by about 30%. It may not improve uvicorn as expected.

[Kludex]

• py.typed added on https://github.com/encode/uvicorn/pull/1687.

It will be available from 0.19.0.

[Kludex]

We finish the package code. Now let's finish the test files. :sweat_smile: