python-conventions

Python Conventions (stack-agnostic, Python 3.10+)

This skill encodes idioms that reduce bugs and improve readability in any Python codebase. Apply alongside the active framework plugin's conventions skill (e.g., django-plugin:django-conventions, fastapi-plugin:fastapi-conventions).

Detection

Read pyproject.toml to determine the target Python version before writing code:

# pyproject.toml — Poetry style
[tool.poetry.dependencies]
python = "^3.10"

# pyproject.toml — PEP 621 style
[project]
requires-python = ">=3.10"

Also check for a .python-version file (used by pyenv):

cat .python-version   # e.g. "3.12.3"

Match the project's minimum version — do not use Python 3.11+ features (e.g. StrEnum, tomllib, ExceptionGroup) on a 3.10 project. All idioms in this skill apply from 3.10 onwards.

Type hints — always on

Annotate every function parameter, return type, and class attribute. Type hints are documentation that a machine can check.

from __future__ import annotations  # enables forward references on 3.10

from collections.abc import Sequence


def greet(name: str, times: int = 1) -> str:
    return (f"Hello, {name}!\n" * times).rstrip()


def first_active(users: Sequence[User]) -> User | None:  # union syntax (3.10+)
    return next((u for u in users if u.is_active), None)

Use from __future__ import annotations at the top of files that reference types not yet defined at parse time (forward references, self-referential types). It defers evaluation of all annotations to strings, avoiding NameError.

For library or shared utility code, use TypeVar and Generic to express parametric types:

from typing import TypeVar, Generic

T = TypeVar("T")


class Result(Generic[T]):
    def __init__(self, value: T, ok: bool) -> None:
        self.value = value
        self.ok = ok

    @classmethod
    def success(cls, value: T) -> Result[T]:
        return cls(value, ok=True)

    @classmethod
    def failure(cls, value: T) -> Result[T]:
        return cls(value, ok=False)