writing-python-code

Writing Python Code

Quick reference

• Python 3.13 only; deps via uv; line length 88 chars (Ruff/Black).
• No f-strings in logger calls — use log.info("x: %s", val).
• Type annotations on every function and method.
• Files ≤ 1000 lines — refactor via Extract Class, Mixins, Strategy, etc.
• Coverage ≥ 80% for non-Reflex classes and Reflex State classes.
• Task runner: task format, task lint, task test (not make).

Code style

Logging

import logging

log = logging.getLogger(__name__)

log.info("Loaded items: %d", count)          # ✅ parameterized
# log.info(f"Loaded items: {count}")         # ❌ f-string

Never use print or printf. Log levels: debug → internal state, info → milestones, warning → recoverable, error → serious.

Type hints

def process(data: dict[str, Any], count: int = 0) -> list[str]: ...

async def handler(value: str) -> AsyncGenerator[Any, Any]:
    yield

• Do not mix Literal[...] with str — pick one.
• Remove unused imports immediately (F401).
• Remove unused args or prefix with _ (ARG001).

Imports & formatting

• Ruff handles lint + format; run task format before committing.
• Break long calls/strings to fit 88 chars.

File size rule

No Python file may exceed 1000 lines. When approaching the limit, apply clean code refactoring strategies.

Design patterns & refactoring strategies: See references/clean-code.md.

Testing

Coverage target: ≥ 80% for services, repositories, models, utilities, and Reflex State classes. UI component rendering is best-effort.

task test                           # full suite with coverage
uv run pytest tests -k assistant    # targeted
uv run pytest tests -x              # stop on first failure

Test patterns, fixtures, Reflex State testing: See references/testing.md.

Security & config

• No credentials in code/history; use .env locally, Key Vault in prod.
• Access Pydantic SecretStr via .get_secret_value().
• Parameterized logs; avoid sensitive values.
• Use appkit_commons.database.session_manager.get_session_manager().session() for DB access outside Reflex handlers (not rx.session()).