python-best-practiceslisted
Install: claude install-skill mahdy-gribkov/arcana
# Modern Python
Target Python 3.14 or newer unless `requires-python` says otherwise; then use what that floor allows. Python 3.15 adds explicit lazy
imports (`lazy import x`, PEP 810) and makes UTF-8 the default for file I/O without an `encoding` argument (PEP 686); pass `encoding`
explicitly in code that must behave the same on older versions. Read `pyproject.toml` and the lockfile first and follow the tools the
project already uses.
## Rules
1. **One tool per job**: uv for environments, dependencies and the lockfile; ruff for lint and format; one strict type checker (mypy or
pyright, not both in CI); pytest for tests.
2. **Types on every function signature.** Built-in generics (`list[str]`), `X | None`, `collections.abc` types for parameters, PEP 695
syntax (`type Alias = ...`, `def f[T](...)`). `Any` only at an untyped boundary, narrowed immediately.
3. **Parse at the boundary.** External data (requests, files, env, queues) goes through a Pydantic model or an explicit parser once;
inside, use dataclasses and trust the types.
4. **No blocking calls in async code.** `time.sleep`, `requests`, sync database drivers and large file reads go through
`asyncio.to_thread` or have an async counterpart. Every network call has a timeout.
5. **Catch specific exceptions.** No bare `except:`; `except Exception` only at a top-level boundary that logs and re-raises or returns
an error response. Chain with `raise NewError(...) from err`.
6. **Configuration is required, not