Using returns in downstream library code

Basic returns usage (Success/Failure, .bind, @safe) is covered by training data. This skill targets the edges that get missed: picking the right container, keeping the IO/async markers, not bailing out of the container early, designing a public API around it, and the pyrefly type-checker reality (returns ships a mypy plugin that no other checker can run).

Pick the container by the kind of failure

The most common miss is collapsing distinct failure kinds onto Result. Match the container to what can go wrong: