Python Bible (Python 3.14)

Targets: Python 3.14 · Previous line: Python 3.13 (trailing section) · Tooling: uv · ruff · mypy/ty · prek · pytest

Version Policy

This skill documents one Python line: the current one. Keep it that way when you update it.

Main path = the current feature release. Today that is Python 3.14. When 3.15 ships, the main path moves to it in the same edit.
Unmarked prose means the current line, and there is no marker form. Python ships features only in a feature release, and the main path always is the current feature release — so nothing in it can post-date the line, and a version suffix would have nothing to qualify. (This is where the sibling
```
ac-django
```
policy differs: Django adds features within a line, so it needs version markers; Python does not.) Do not write "On Python 3.X+, ..." or "if you are on 3.13" in the main path — a conditional in the main path is the defect this rule exists to stop.
Older lines get one trailing section each, at the end of
SKILL.md
, and nothing anywhere else — the reference files carry the current line only and get no trailing section of their own. Today that is
```
## Previous line: Python 3.13
```
. It carries the diff a reader on that version needs: what is missing, what to use instead, and what to change on upgrade.
Research order when refreshing.
```
https://docs.python.org/3/whatsnew/
```
and the library reference first. Then the sources already cited under Canonical Sources. Blogs and newsletters last, briefly, for what the docs do not cover.
Rotation. Each October a new line ships: re-base unmarked prose on it, replace the trailing section with the line being retired, drop stale markers.

Canonical Sources

Python docs: https://docs.python.org/3/
Ruff docs: https://docs.astral.sh/ruff/
uv docs: https://docs.astral.sh/uv/
mypy docs: https://mypy.readthedocs.io/
pytest docs: https://docs.pytest.org/
Typer (CLI): https://typer.tiangolo.com/

Reference Files (load as needed)

File	Covers	When to load
`references/style-and-typing.md`	Style, Pythonic idioms, type annotations, readability rules	Writing or reviewing any Python code
`references/oop-and-design.md`	OOP patterns, data models, factories, properties, design principles	Designing classes, data models, module structure
`references/testing-and-tooling.md`	Testing patterns, pytest setup, tooling (uv/ruff/mypy/prek), quality gates	Writing tests, setting up a project, CI

Dependencies

Standalone. No dependencies on other skills.

When used alongside ac-django, provides generic Python guidelines that complement Django-specific patterns.

Trigger QA (Release Gate)

Before shipping skill changes, validate activation behavior with sample prompts:

Should trigger:
- "Write a CLI script that processes CSV files."
- "Review this Python class for design issues."
- "Set up testing for this Python microservice."
Should NOT trigger:
- "Add a Django model field and migration."
- "Set up git worktrees for a ticket."
- "Implement project delivery workflow."

If behavior under-triggers or over-triggers, tighten

description

cues before release.

Example: Adding a new data model

User says: "Add a

LoanApplication

data model with validation"

Load
```
references/oop-and-design.md
```
for data model patterns
Load
```
references/style-and-typing.md
```
for typing conventions
Use a dataclass or attrs/pydantic if the project already uses them
Add full type annotations, use
```
@cached_property
```
for derived attributes
Name the factory
```
build_loan_application(...)
```
if needed in tests
Mirror the module path in
```
tests/
```
for the test file

Prime Directives

Pythonic first

Prefer the idiomatic Python solution over a generic one.
Use list comprehensions, walrus operator (
```
:=
```
),
```
itertools
```
,
```
operator
```
where they clarify intent.
Avoid intermediate variables that are only used once.
Prefer t-strings (
```
t"..."
```
, PEP 750) over f-strings when building SQL, HTML, shell commands, or templates from interpolated values. A t-string evaluates to a
```
string.templatelib.Template
```
, not a
```
str
```
: the static text and each
```
Interpolation
```
stay separable, so a processing function can escape every interpolated value for its target grammar. The safety is in that function — the stdlib ships none, so use a library's or write one. A
```
Template
```
passed where a
```
str
```
is expected is an error, not an escape.
Use the stdlib
```
compression.zstd
```
for zstd rather than the third-party
```
zstandard
```
package.
```
compression.lzma
```
,
```
compression.bz2
```
,
```
compression.gzip
```
and
```
compression.zlib
```
are the preferred import names for those modules too; the originals still work and are not deprecated.
```
tarfile
```
,
```
zipfile
```
and
```
shutil
```
read and write zstd archives.
Omit the brackets in a multi-type
```
except
```
when there is no
```
as
```
clause (PEP 758):
```
except TimeoutError, ConnectionRefusedError:
```
. With
```
as
```
, the brackets are still required.
Never
```
return
```
,
```
break
```
, or
```
continue
```
out of a
```
finally
```
block — it swallows the in-flight exception, and the compiler emits a
```
SyntaxWarning
```
for it (PEP 765).

Types are documentation

Full, modern annotations everywhere:
```
list[str]
```
,
```
str | None
```
,
```
dict[str, int]
```
.
Use the
```
type
```
statement for recurring complex types.
No duck-typing: if you are checking for attribute existence before acting, the type hint is too broad — narrow it.

No docstrings — names are the docs

Use short, expressive function and variable names.
Comment ONLY the non-obvious WHY. Never restate the code; never write a signature-echo docstring.
A long comment is a code smell — refactor or rename instead of explaining. Multi-line comments are legit only for a genuine non-obvious why, never to narrate the code.
Use vertical whitespace to group related lines.

Clean imports

All
```
import
```
statements at the top of the file.
No function-level imports, no
```
try...except ImportError
```
guards. (Repo-specific conventions may relax this for established circular-import patterns.)
Assume all dependencies are installed.

No dirty hacks

Pick the straightforward solution. If it doesn't exist, reconsider the design.
Do not fight third-party frameworks — follow their intended patterns.

Review Checklist

Style

no single-use intermediate variables
list comprehensions / stdlib idioms used where appropriate
vertical whitespace groups related logic

Typing

full modern annotations on all public functions and methods
```
type
```
statement used for complex/recurring types
no duck-typing (no
```
hasattr
```
guards in place of proper types)

Imports

all imports at top of file
no
```
try...except ImportError
```
blocks
no function-level imports

OOP / Design

data models are first-class (not plain dicts passed around)
factories named
```
build_...
```
application logic in methods, not module-scope functions
```
@property
```
/
```
@cached_property
```
for derived attributes

Best Practices

UTC timezone-aware datetimes throughout
boolean params preceded by
```
, *,
```
```
try
```
blocks and context managers are minimal (ideally one line each)

Architectural Health (Module-Level)

Apply to full files touched by the diff, not just changed lines:

no module with >500 LOC (split by concern)
no module with >10 module-level functions (use classes)
module-level functions are justified — default is methods on a class
no god-module (single file mixing unrelated concerns — CLI wiring + business logic + subprocess management = split)
no complexity rule suppressions (
```
C901
```
,
```
PLR09xx
```
) in
```
pyproject.toml
```
beyond the
```
python-boilerplate
```
baseline
tests assert behavior through public interfaces, not by patching private functions or asserting subprocess command lists

Testing

Integration-First Testing (Non-Negotiable)

Write integration tests for happy paths, unit tests for edge cases. This maximizes confidence per line of test code.

Integration tests exercise multiple modules together with real (or near-real) I/O. They catch the bugs that matter most: broken contracts between modules, wrong assumptions about state, ordering issues. Mock only what you cannot control (network, external processes, databases).
Unit tests target specific functions in isolation — but only when the function has edge cases worth covering (error handling, boundary values, complex branching). Don't unit-test trivial glue code.
Don't duplicate coverage. If a happy path is already covered by an integration test, don't write a unit test for the same path. Unit tests should cover what integration tests cannot reach efficiently (rare error branches, corner cases).
E2E tests (browser, full-stack) are separate — they belong in frontend/application test suites, not in library or infrastructure code. Write them when testing user-visible behavior end-to-end.

Test Conciseness (Non-Negotiable)

Tests must be easy to read and maintain. Verbose tests get skimmed, misunderstood, and copy-pasted without thought.

One assertion per concept. A test method should test one behavior. Multiple assertions are fine when they verify different facets of the same behavior.
Use fixtures for setup, not copy-paste. Repeated setup code across test methods means a missing fixture or parametrize.
Parametrize over copy-paste. When multiple tests differ only in input/output values, use
```
@pytest.mark.parametrize
```
. Five test methods that differ by one string are one parametrized test.
Name tests after the behavior, not the method.
```
test_returns_error_when_db_missing
```
beats
```
test_db_import_3
```
.
No unnecessary mocks. Only mock what you cannot control (network, clock, external processes). Over-mocking makes tests tautological — they test the mocks, not the code.
Flat over nested. Prefer module-level test functions or flat test classes. Deeply nested class hierarchies in tests add complexity without value.
Prefer context managers (
with patch(...)
) over
monkeypatch
. Context managers clearly isolate the scope that needs the mock. Use
```
monkeypatch
```
only when it genuinely simplifies the test (e.g., env vars,
```
chdir
```
, patching attributes on fixtures that outlive the test body).

Checklist

test file mirrors
```
src
```
module path
test class and method names describe the behavior under test
happy path covered by integration test; unit tests cover edge cases
no duplicated coverage between integration and unit tests
```
@pytest.mark.parametrize
```
used where 3+ tests differ only by input/output
fixtures used for repeated setup — no copy-pasted boilerplate
mocks only for external boundaries (subprocess, network, clock)

Previous line: Python 3.13

Everything above targets Python 3.14. On 3.13:

No t-strings. Build SQL/HTML with the target library's own parameterisation or escaping (
```
cursor.execute(sql, params)
```
,
```
markupsafe
```
), never f-string interpolation.
No
compression.zstd
. The third-party
```
zstandard
```
package is the option;
```
tarfile
```
/
```
zipfile
```
/
```
shutil
```
do not read or write zstd.
Annotations are evaluated eagerly.
```
from __future__ import annotations
```
is still needed for forward references, and there is no
```
annotationlib
```
— use
```
typing.get_type_hints()
```
. The main path's ruff config bans that import (
```
lint.flake8-tidy-imports.banned-api."__future__.annotations"
```
in
```
references/testing-and-tooling.md
```
); drop that one entry while the project targets 3.13, and restore it on 3.14.

except
needs brackets for multiple types:

except (TimeoutError, ConnectionRefusedError):

Free-threading is experimental, not officially supported, and carries a much larger single-threaded penalty than 3.14's ~5–10%.
Pin
```
python_version
```
/
```
python-version
```
to
```
"3.13"
```
in the mypy/ty config while the project targets it.

ac-python

NPX Install

Tags

SKILL.md Content