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#

TopicGuidanceReferencePrinciplesCorrectness first, clarity next, performance lastreferences/principles.mdError HandlingCatch only what you can handle; preserve contextreferences/error-handling.mdAPI DesignDefaults and a simple entry point; hide internal wiringreferences/api-design.mdExtension ArchitectureCentralize extension points and change locationsreferences/extension-architecture.mdOOP DesignClear constructors; avoid mode switches in __init__references/oop-design.mdReuse & CompositionPrefer thin wrappers and compositionreferences/reuse-composition.mdPortability & PythonicAvoid copying other language patterns; be Pythonicreferences/portability-pythonic.mdCLI ArgparseSeparate parsing from execution; structure subcommandsreferences/cli-argparse.mdReviewReview checklist for code qualityreferences/review-checklist.md

References#

• Each topic file lists source URLs in its frontmatter urls.