claude-skills/my-python-senior/systems.md

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.