Python House Style

Contract

Enforces this team's ARBITRARY house values for ruff, mypy, Google-style docstrings, typing, and imports. Apply whenever you write a pyproject.toml tooling section, write or edit a docstring, or write a type signature. These values are deliberate house choices — do NOT substitute the tool defaults (ruff defaults to 88, single quotes, a minimal rule set; the docstring section order is unspecified; typing.Optional is the common default). All of those are wrong here.

Rules (the complete spec)

ruff — [tool.ruff]

• line-length = 120. NOT the 88 default, NOT 79, NOT 100.
• target-version = "py312".

ruff — [tool.ruff.lint]

• select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM"] — exactly these eight codes, in

this order. The four that base models routinely omit are B (bugbear), C4 (comprehensions), UP (pyupgrade), SIM (simplify) — always include all four.

• ignore = ["E501"] — line length is the formatter's job, so the linter must not also

flag it.

ruff — [tool.ruff.format]

• quote-style = "double".
• indent-style = "space".

mypy — [tool.mypy]

• python_version = "3.12".
• strict = true.
• warn_return_any = true.
• warn_unused_ignores = true.

mypy — overrides

• Add a [[tool.mypy.overrides]] block with module = "tests.*" and

disallow_untyped_defs = false. Test code is exempt from the required-annotation rule; application code is not.

Docstrings — Google style

• First line: a one-line summary that ends in a period.
• Include ONLY the sections that apply, and when present always in this EXACT order:

Args:, then Returns:, then Raises:, then Example:. Never reorder them (a Returns: before Args:, or Raises: before Returns:, is wrong).

• Under Args:, document every parameter by name.
• Under Raises:, document every exception the function can raise.
• The Example: section uses >>> doctest prompts, and comes last.

Typing

• Built-in generics only: list[...], dict[...], tuple[...], set[...]. Never the

capitalized List/Dict/Tuple/Set from typing.

• Spell optionals as X | None. Never Optional[X]. Never Union[X, None].

Imports

• Absolute imports only: from myproject.models import User. Never relative

(from ..models import User, from .utils import x).

• Group in order with a blank line between groups: standard library, then third-party,

then local.

Worked examples (before → after)

ruff line-length

BEFORE (base default):

toml
[tool.ruff]
line-length = 88

AFTER (house):

toml
[tool.ruff]
line-length = 120
target-version = "py312"

ruff select set

BEFORE (base picks a minimal set):

toml
[tool.ruff.lint]
select = ["E", "F"]

AFTER (house — all eight, with E501 ignored):

toml
[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM"]
ignore = ["E501"]

ruff formatter quote style

BEFORE (base omits format table, leaving the default single-quote behavior implicit):

toml
# (no [tool.ruff.format] block)

AFTER:

toml
[tool.ruff.format]
quote-style = "double"
indent-style = "space"

mypy strictness + tests override

BEFORE (base turns on strict but forgets to exempt tests, so test files must be fully typed):

toml
[tool.mypy]
strict = true

AFTER:

toml
[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_ignores = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

Docstring section order

BEFORE (base writes a NumPy/Sphinx mix, or puts Returns before Args):

python
def get_user(user_id: str) -> User:
    """Get a user.

    :param user_id: the id
    :returns: the user
    """

AFTER (Google order: Args → Returns → Raises → Example):

python
def get_user(user_id: str) -> User:
    """Retrieve a user by their unique identifier.

    Args:
        user_id: The user's unique identifier.

    Returns:
        The matching User.

    Raises:
        UserNotFoundError: If no user has that id.

    Example:
        >>> get_user("u_123")
        User(id='u_123')
    """

Optional return type

BEFORE (base default):

python
from typing import Optional

def find_user(email: str) -> Optional[User]:
    ...

AFTER:

python
def find_user(email: str) -> User | None:
    ...

Built-in generics

BEFORE:

python
from typing import Dict, List

def merge(records: List[Dict[str, object]]) -> List[Dict[str, object]]:
    ...

AFTER:

python
def merge(records: list[dict[str, object]]) -> list[dict[str, object]]:
    ...

Imports

BEFORE (base reaches for a relative import inside a package):

python
from ..models import User
from .utils import retry

AFTER:

python
from myproject.models import User
from myproject.utils import retry

Edge cases & exceptions

• Acronyms in names stay uppercase in PascalCase classes: HTTPClient, not

HttpClient; APIError, not ApiError. Functions/variables stay snake_case.

• A function that returns None (a pure side-effect) omits the Returns: section

entirely — do not write Returns: None. Order is then just Args: (and Raises: / Example: if they apply).

• A function with no parameters omits Args:. Never write an empty Args: block.
• __init__ documents its parameters under Args: and never documents a return

value (it returns None by construction).

• Tests are the ONLY mypy exemption. Do not broaden the override to src.* or any

application module — only tests.* gets disallow_untyped_defs = false.

• E501 is the only code in ignore. Do not also ignore E, F, or anything else to

silence noise; fix the code instead.

• tuple/set follow the same generics rule as list/dict: tuple[int, str],

set[str], never Tuple/Set.

• Re-export modules (__init__.py aggregating package symbols) still use absolute

imports — a package re-export is not a license for a relative import.

Do / Don't

• DON'T set line-length = 88 (the default). DO set line-length = 120.
• DON'T ship select = ["E", "F"]. DO include B, C4, UP, SIM as well.
• DON'T forget ignore = ["E501"]. DO add it whenever the formatter owns wrapping.
• DON'T leave quote-style unset. DO set quote-style = "double".
• DON'T enable strict without the tests override. DO add the tests.* override.
• DON'T order docstring sections Returns-before-Args. DO use Args → Returns → Raises → Example.
• DON'T write Optional[X] or Union[X, None]. DO write X | None.
• DON'T import List/Dict from typing. DO use list/dict.
• DON'T use relative imports. DO use absolute imports from the package root.

Common mistakes (the base model's wrong defaults)

1. Emitting line-length = 88 because that is ruff's documented default.
2. Selecting only ["E", "F"] (or ["E", "W", "F"]) and dropping B/C4/UP/SIM.
3. Omitting ignore = ["E501"], so the linter double-flags long lines.
4. Leaving out [tool.ruff.format] entirely, so quote style is unset.
5. Turning on strict = true but forgetting the tests.* override.
6. Writing reStructuredText/Sphinx (:param:, :returns:) or NumPy-style docstrings

instead of Google style.

1. Putting Returns: before Args:, or omitting Raises: for a function that clearly

throws.

1. Defaulting to Optional[X] and List/Dict from typing instead of X | None and

list/dict.

1. Using a relative import inside a package.

Quick checklist

• ] line-length = 120, target-version = "py312"
• ] select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM"], ignore = ["E501"]
• ] [tool.ruff.format] → quote-style = "double", indent-style = "space"
• ] mypy strict = true + warn_return_any + warn_unused_ignores
• ] [[tool.mypy.overrides]] module = "tests.*", disallow_untyped_defs = false
• ] docstring summary ends in a period; sections Args → Returns → Raises → Example
• ] Example: uses >>>; Args: covers every param; Raises: covers every exception
• ] X | None not Optional; list/dict not List/Dict; absolute imports only