# Systems Python Guidelines

## CLI tools and system utilities

- Prefer `argparse` or `typer` for CLIs, not ad-hoc `sys.argv` parsing.
- Always provide:
  - `--help` with clear descriptions
  - examples in docstrings or README
  - reasonable defaults and safe behavior.
- For non-trivial tools, separate:
  - CLI entrypoint (`main()` or Typer app)
  - core logic in importable modules (no side effects on import).

## Logging and diagnostics

- Use the `logging` module instead of `print` for diagnostics.
- Provide configurable log levels; default to `INFO` for CLI tools.
- For structured logging, prefer JSON-compatible formats when integrating with centralized logging.
- Avoid logging secrets, access tokens, and PII.

## Configuration

- Prefer explicit configuration (CLI args, env vars, config files) over hidden magic.
- Use `pydantic` or `dataclasses` for structured config when appropriate.
- For multi-environment setups, support:
  - baseline config
  - overrides via env or separate files.

## Packaging and layout

- Use modern packaging (`pyproject.toml` with `setuptools`/`hatch`/`poetry`).
- Standard layout:
  - `src/<package_name>/...`
  - `tests/`
  - minimal, well-documented dependencies.
- For tools that may be reused, publishable or installable layout is preferred even in internal projects.

## Error handling

- Fail fast on invalid configuration or obvious misuse.
- Wrap external calls (filesystem, network, subprocesses) with clear error messages.
- Use custom exception types where it improves clarity.
- Never silently swallow exceptions; at minimum, log with context.