unavlab
43 lines
1.6 KiB
Markdown
43 lines
1.6 KiB
Markdown
# 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. |