| name | python-libraries |
| description | Reach for this project's preferred, well-supported libraries instead of hand-rolling. Use when choosing a library for HTTP, retries, JSON, or parsing, or whenever you are about to write something the standard library or a maintained package already does. |
Python Libraries
Prefer well-supported libraries (and the standard library) over hand-rolled code — it is
less to maintain and less to get wrong than reinventing a solved problem.
Don't reinvent the wheel
- Don't hand-roll retry or backoff loops — use
stamina (it wraps tenacity with sane
defaults: capped attempts, jitter, and retrying only the exceptions you name). Set a
timeout and exclude non-retryable errors, such as a 4xx that won't change on retry.
- Don't reimplement what
itertools (stdlib) or more-itertools already provide
(grouping, chaining, windowing, accumulating) — reach for them instead. See
python-code-style for the broader "prefer stdlib idioms" rule.
- Don't parse HTML or XML with regex — use
parsel (XPath and CSS selectors).
HTTP
- Use an HTTP client with async support — this rules out
requests and urllib.
- Match the async client the repo already uses rather than introducing a second one, and
don't add another HTTP client as a (dev) dependency without a concrete reason.
- Set an explicit timeout on outbound requests; a single client-level default is fine,
but never rely on the library default, which is often
None (waits forever).
JSON
- Use
orjson over the standard library json for serialising and deserialising — it is
faster and better-behaved.
- When a Pydantic model is involved, go straight to and from JSON bytes with
Model.model_validate_json(raw) and model.model_dump_json() — one fast
parse-and-validate pass.
- Don't call an HTTP response's
.json() and hand the resulting dict to Pydantic: that
parses twice (the client builds a dict, then Pydantic re-validates it). Pass the raw
bytes (response.content) to Model.model_validate_json(...) instead.
See python-async for deploying on uvloop, and python-datetime for dates and times.
