following-conventions

# Python Coding Conventions

Coding standards for Python projects at Tenzir.

## Required Tools

All projects use:

- **uv** — Dependency management and virtual environments
- **Ruff** — Linting and formatting
- **Mypy** — Static type checking
- **pytest** — Testing

## Default Libraries

Prefer to use these libraries to ensure uniform codebase across Tenzir
repositories:

- **pydantic** - Defining and validating models
- **FastAPI** - Declaring REST APIs
- **Click** - Providing a CLI interface

## Quality Gates

Run before committing or releasing:

```sh
uv run ruff check \
  && uv run ruff format --check \
  && uv run mypy \
  && uv run pytest \
  && uv build
```

The chain fails fast on the first error.

## Python Version

Target Python 3.12+. Use modern syntax and stdlib features freely—no
backwards-compatibility with older versions.

## Coding Style

### Formatting

- Ruff controls whitespace: 4-space indentation, double-quoted strings
- 88 character line limit (Ruff/Black default)
- Let Ruff order imports automatically

### Type Hints

- All public surfaces must be fully typed
- Strict Mypy settings reject untyped or partial definitions
- Avoid `Any`; fix warnings rather than ignoring them

### Package structure and imports

- Keep `__init__.py` files empty. They are only used to mark a directory as
  importable but do not contain any content, let alone non-trivial code.
- Always use absolute imports from the package top level:
  `from this_package.foo import bar` instead of `from .foo import bar`.
- Never use wildcard imports

### Naming Conventions

| Element   | Convention      | Example             |
| --------- | --------------- | ------------------- |
| Modules   | `snake_case`    | `my_module.py`      |
| Functions | `snake_case`    | `calculate_total()` |
| Variables | `snake_case`    | `user_count`        |
| Classes   | `PascalCase`    | `DataProcessor`     |
| Constants | `CONSTANT_CASE` | `MAX_RETRIES`       |

### CLI Conventions

- Use kebab-case