10-python-standards

---

Python Engineering Standards

These rules apply to Python source code.

Project-specific conventions documented in ENGINEERING.md take precedence over these defaults.

---

Type Safety

Use type annotations for all public functions, methods, and module-level constants where appropriate.

Prefer explicit types over Any.

Prefer structured domain models over untyped dictionaries.

Prefer:

• explicit return types;
• typed collections;
• dataclasses or Pydantic models where appropriate;
• Protocol for behavioral interfaces.

Avoid unnecessary use of:

• Any;
• dict[str, Any];
• untyped containers.

---

Function Design

Functions should:

• have a single responsibility;
• have explicit inputs and outputs;
• minimize side effects;
• remain reasonably small.

Prefer pure functions whenever practical.

Use descriptive names that express business intent.

Avoid vague names such as:

def process(data):
    ...

---

Class Design

Classes should have a single responsibility.

Prefer composition over inheritance.

Prefer dependency injection over hidden global state.

Avoid deep inheritance hierarchies unless clearly justified.

---

Error Handling

Raise exceptions that accurately describe failures.

Catch only exceptions that can be handled meaningfully.

Never silently ignore exceptions.

Avoid:

except Exception:
    pass

Exception messages should help diagnose the problem.

---

Logging

Use the project's logging framework.

Prefer parameterized logging.

Example:

logger.info("Created task %s", task_id)

Avoid:

logger.info(f"Created task {task_id}")

Never use print() outside CLI utilities or interactive scripts.

---

Imports

Keep imports at module level.

Avoid:

• circular dependencies;
• import-time side effects;
• unnecessary dynamic imports.

Use TYPE_CHECKING for type-only imports that would otherwise create dependency cycles.

Group imports according to PEP 8.