# Python Best Practices

> Write maintainable Python with small functions, explicit boundaries, guard clauses, and readable state flow. Use when refactoring Python services, helpers, modules, or async logic for clarity—not generic test writing, tooling setup, or database transaction implementation.

- Skill: `hoangnguyen0403/python-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add hoangnguyen0403/python-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/python-best-practices/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/hoangnguyen0403/python-best-practices

---


# Python Best Practices

## **Priority: P1 (HIGH)**

## Rules

- Prefer small focused functions over long stateful procedures.
- Push parsing, formatting, transport, and persistence into separate helpers.
- Return early on invalid or terminal states.
- Pass collaborators in; do not hide them behind globals or import-time singletons.
- Keep naming literal and domain-specific.

## Recipe

1. **Split orchestration from transformation**.
2. **Extract repeated shape cleanup** into one helper.
3. **Keep side effects at edges** and pure decisions in the middle.
4. **Use fakes in tests** instead of patching deep internal chains when possible.

## Anti-Patterns

- **No god functions**: break report builders and workflow loops into tested slices.
- **No boolean soup**: name decision helpers instead of stacking flags inline.
- **No hidden retries**: surface retry policy near the call site.
- **No print-debugging in shared runtime code**: use structured logging or test assertions.

## References

- [Framework Map](../references/framework-map.md)