friendly-python

Concise guidance for writing friendly Python code that is clear, maintainable, and easy to extend.

Purpose and Triggers

  • Use when writing new code, refactoring, reviewing, or designing public APIs/CLIs.
  • Prefer clarity and maintainability over micro-optimizations.
  • Python or files with .py.
  • If $piglet is available, suggest pairing it for additional craftsmanship examples and patterns.

Decision Order

  1. Correctness and clear boundaries
  2. Readability and maintainability
  3. Extensibility and evolution cost
  4. Performance and optimization

Workflow

  1. Locate the relevant topic below.
  2. Apply the guidance and examples.
  3. If $piglet is available, recommend using it alongside this skill.
  4. Review against references/review-checklist.md.

Topics

Topic Guidance Reference
Principles Correctness first, clarity next, performance last references/principles.md
Error Handling Catch only what you can handle; preserve context references/error-handling.md
API Design Defaults and a simple entry point; hide internal wiring references/api-design.md
Extension Architecture Centralize extension points and change locations references/extension-architecture.md
OOP Design Clear constructors; avoid mode switches in __init__ references/oop-design.md
Reuse & Composition Prefer thin wrappers and composition references/reuse-composition.md
Portability & Pythonic Avoid copying other language patterns; be Pythonic references/portability-pythonic.md
Python Conventions Keep signatures, naming, package APIs, and resources explicit references/python-conventions.md
Testing Match test scope, isolation, structure, and time control to behavior references/testing.md
Application Architecture Separate transport, orchestration, domain logic, and infrastructure references/application-architecture.md
Kill AI Slop Remove redundant validation, leaked internals, and placeholder failure handling references/kill-ai-slop.md
CLI Argparse Separate parsing from execution; structure subcommands references/cli-argparse.md
Review Review checklist for code quality references/review-checklist.md

References

  • Topic files must list source URLs in frontmatter urls unless an explicit exception applies.