Python Coding Standards

Sylla-specific standards for the Python data-engine codebase. All rules are settled and enforced in code review. Full rationale and code examples for every rule are in references/standards.md .

How to Apply This Skill

• For quick lookups (rule name, convention), use the Quick Reference tables below.

• For rationale, code examples, or edge cases, consult references/standards.md .

• When reviewing code, run through the Code Smell Checklist at the bottom of this file.

All work must satisfy readability, KISS, DRY, YAGNI, and security — specifically: no eval /exec /pickle , T | None over Optional[T] , explicit return types on public functions, and @property for computed attributes.

Quick Reference

Type Annotations

Rule Standard

Optional types T | None — never Optional[T]

Return types on public functions Required

Return types on internal helpers Inferred is acceptable

Computed attributes @property — never get_x() methods

Generics list[str] , dict[str, int] — never List , Dict from typing

Datetime datetime.now(timezone.utc) — never datetime.utcnow()

Imports & Modules

Rule Standard

Import location Top of module always

Function-level imports Only to break circular dependencies

Import order stdlib > third-party > local (isort enforced)

Unused imports Remove — never comment out

Functions & Classes

Rule Standard

Docstrings Google-style on public APIs

Max function length ~50 lines — split if longer

Nesting Max 3 levels — use early returns

Abstract base classes ABC

• @abstractmethod for shared contracts

Protocols Use for structural typing when ABC is too rigid

Error Handling

Rule Standard

Bare except

Banned

Broad except Exception

Only at top-level boundaries with logging

Silent except: pass

Banned

Logging library structlog with bound loggers

Error messages Include context (IDs, operation name)

Custom exceptions Inherit from domain-specific base, not bare Exception

Async Patterns

Rule Standard

Parallel async calls asyncio.gather(*tasks)

HTTP client httpx.AsyncClient with explicit timeouts

Sync calls in async Banned — use asyncio.to_thread() if unavoidable

Client lifecycle Context managers (async with ) for connection pools

Pydantic Models

Rule Standard

Extra fields model_config = ConfigDict(extra="forbid")

Field metadata Field(description="...") on every field

Computed attributes @property — never get_x()

Enums in models Use StrEnum for string enums

Naming

Thing Convention

Files & folders snake_case

Variables & functions snake_case

Classes PascalCase

Constants SCREAMING_SNAKE_CASE

Private attributes Single leading underscore _name

Type variables PascalCase (T , ResponseT )

Boolean variables is_ , has_ , can_ prefix

Tooling

Tool Config

Black line-length 88, target py311

isort profile "black", line_length 88

MyPy strict — disallow_untyped_defs = true , warn_return_any = true

Pytest pythonpath = ["."] , testpaths = ["tests"]

Flake8 Ignore E203, W503 (Black-incompatible rules)

Code Smell Checklist

Before opening a PR, check:

• Optional[T] — change to T | None

• datetime.utcnow() — change to datetime.now(timezone.utc)

• get_x() method for a simple computed attribute — change to @property

• Import inside a function body (no circular dependency reason) — move to top of module

• Function >~50 lines — split it

• 3 levels of nesting — use early returns

• Bare except or except: pass — catch specific exceptions, log the error

• except Exception in non-boundary code — narrow the exception type

• Magic number/string — extract to SCREAMING_SNAKE_CASE constant

• typing.List , typing.Dict , typing.Tuple — use built-in list , dict , tuple

• Missing return type on public function — add explicit annotation

• eval() , exec() , pickle.loads() — find a safe alternative

• HTTP request without timeout — add explicit timeout

• datetime.utcnow() — use datetime.now(timezone.utc)

• Sync blocking call inside async function — use asyncio.to_thread()

• N+1 query pattern (DB/API call inside loop) — batch or use asyncio.gather

• Pydantic model missing ConfigDict(extra="forbid") — add it

• get_x() method that is a simple property — convert to @property