python-trio / python-trio/trio

Add collection of worked examples to tutorial

Open
#472 43 comments 6 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs
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_way can be re-used for both! Maybe the proxy should demonstrate mirroring localhost:12345 to httpbin: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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.