Type hints are one of those things that's perpetually on my "it would be nice to learn about these someday" list, so I haven't done anything with them in trio myself, but people are interested in adding them (e.g. @Fuyukai, + some discussion). Seems like a good idea to me.

Like I said, I don't know much about this. Looking at PEP 561, it sounds like the ideal is to use inline type hints where possible, and where it's not, to fall back to .pyi files that we maintain and ship alongside the corresponding .py files? Is that right?

That means that this interacts with #542: until we make our imports less magical, inline type hints probably aren't going to work. In some cases that might be fine and we should just use .pyi files, but it seems like right now there are lot of places where inline type hints would be the right approach, just we need to clean up the imports first, and that's a good idea anyway, so we might want to start there.

This is something we'd want to do incrementally. Maybe something like: (1) figure out how to get mypy to run on trio at all, (2) get that running in travis-ci so we don't regress, (3) start incrementally adding type hints, while making sure mypy can understand them, starting from the simplest/lowest-hanging fruit?

I know there's a growing body of experience with adding type hints to projects, but I'm not super familiar with it... if you know good articles please add links to them here :-). To get us started:

• How Zulip approached this: http://blog.zulip.org/2016/10/13/static-types-in-python-oh-mypy/
• Clearer Code at Scale: Static types at Zulip and Dropbox – talk that @gnprice gave at PyCon this year