python-trio / python-trio/trio
Add collection of worked examples to tutorial
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 7.3k
- Forks
- 431
- Avg merge
- 2d 17h
- Merged PRs (30d)
- 6
Description
We should refactor the tutorial into an initial part that's similar to what we have now, or the middle part of my talk, and then a collection of examples that also serve as excuses to go into more depth on particular topics.
I expect the list will grow over time, but here are some ideas. (Actually the main reason I'm filing this is to have a place collect these so I don't lose them.)
-
The current tracing demo should move here. It's a good intro to trio introspection and to co-op concurrency, but having it in the main tutorial like it is now is a big blob of text for folks to wade through if they already know this stuff. (We can/should link to it from the async/await intro though.)
-
Happy eyeballs (for people who saw the talk but want a text version; as a demo of passing nursery objects around; ...)
-
Multiplexing rpc (#467)
-
Catch-all exception handler
-
Custom nursery, like a race function or ignore-errors nursery (maybe both)
-
Some standard stuff like echo server, proxy, fast web spider, ... Whatever doesn't end up in the main tutorial. (We could have echo server and TCP proxy as two examples, then show how to run them both within a single process as an example of implementing multi-protocol servers... and also to show off how
proxy_one_waycan be re-used for both! Maybe the proxy should demonstrate mirroringlocalhost:12345tohttpbin:80, so people can try it out with their web browsers?) -
trio-asyncio example?
-
nursery.start
Possibly some of these could be combined or form sequences, eg echo server -> catch all handler -> nursery.start
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the current tutorial and tracing demo mentioned in the issue, then review the linked multiplexing RPC issue and the proposed example topics. Define a workable tutorial structure and decide which examples belong outside the main tutorial. Done means the tutorial is reorganized and the selected worked examples are collected with appropriate links and depth.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100