Trio – async I/O for humans and snake people

P.S. your API is a user interface – Kenneth Reitz

Trio is an experimental attempt to produce a production-quality, permissively licensed, async/await-native I/O library for Python, with an emphasis on usability and correctness – we want to make it easy to get things right.

Traditionally, async programming is quite challenging, with many subtle edge cases that are easy to get wrong. The addition of asyncio to the standard library was a huge advance, but things have continued to move forward since then, and ironically, asyncio suffers from backwards-compatibility constraints that make it difficult for it to take full advantage of the new language features that it motivated. The result can be somewhat confusing, and there's a widespread sense that we can do better.

Trio is my attempt to ingest the ideas from asyncio and other systems and to improve upon them. In particular, it's heavily inspired from studying and working on Dave Beazley's curio, and my analysis of how it avoids many of the pitfalls of callback-based async programming models like asyncio; trio tries to take these ideas further. Other influences include C#, Erlang, and others. But you don't need to know any of that to use trio.

Our (possibly overambitious!) goal is that if you're coming from an async I/O library that was created in the pre-async/await era, then switching to trio should feel like switching from urllib2 to requests, or from C to Python. Of course, whether we can live up to that is an open question! Trio represents one fairly opinionated vision for the future of asynchronous I/O in Python, but it's not the only such vision. If you're interested in trio, then you should certainly check out asyncio and curio too.

So... where to next?

I want to know more! Check out the documentation!

I want to dive in and try it! Awesome! python3 -m pip install -U trio (or py -3 -m pip install -U trio on Windows) and start with the tutorial. (If you already know async/await, then you might want to jump straight to the networking section.) And if you use it for anything more than toy experiments, then you should read and subscribe to this issue.

But wait, will it work on my system? Probably! As long as you have either CPython 3.5+ or a PyPy 3.5 prerelease, and are using Linux, MacOS, or Windows, then trio should absolutely work. *BSD and illumos likely work too, but we don't have testing infrastructure for them. All of our dependencies are pure Python, except for CFFI on Windows, and that has wheels available.

I want to help! You're the best! There's tons of work to do – filling in missing functionality, building up an ecosystem of trio-using libraries, usability testing (e.g., maybe try teaching yourself or a friend to use trio and make a list of every error message you hit and place where you got confused?), improving the docs, ... We don't have a CONTRIBUTING.md yet (want to help write one?), but you can check out our issue tracker, and depending on your interests check out our labels for low-hanging fruit, significant missing functionality, open questions regarding high-level design, ...

I don't have any immediate plans to use it, but I love geeking out about I/O library design! That's a little weird? But tbh you'll fit in great. Check out our discussion of design choices, reading list, and issues tagged design-discussion.

I want to make sure my company's lawyers won't get angry at me! No worries, trio is permissively licensed under your choice of MIT or Apache 2. See LICENSE for details.

Code of conduct

Contributors are requested to follow our code of conduct in all project spaces.