skills.rest
asarchami
asarchamiCOMMUNITY
Explore all skills by this author →
GitHub

python-api-design

Designs Python library APIs with naming conventions, error handling, and deprecation patterns.

1|2|Updated Nov 25, 2017
Search Tags:#code review#error handling#api design#python#library#deprecation#naming conventions
One-click install
npx skills add https://github.com/asarchami/dotfiles --skill python-api-design-asarchami
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: python-api-design
Source: https://github.com/asarchami/dotfiles/tree/main/dot_config/opencode/skills/python/api-design
Command: npx skills add https://github.com/asarchami/dotfiles --skill python-api-design-asarchami

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Python library authors often ship APIs that are inconsistent, hard to discover, or painful to evolve, leading to confused users and breaking-change churn. This Skill provides concrete principles and patterns for designing intuitive, maintainable Python library APIs. ## Core Features & Use Cases - API Design Principles: Applies simplicity, consistency, least surprise, and discoverability through progressive disclosure patterns (simple functions, configurable classes, low-level internals). - Naming & Error Conventions: Enforces verb-based action names, get_/is_/has_/to_ prefixes, custom exception hierarchies with helpful hints, and structured deprecation warnings. - Use Case: When building a new Python library, use this Skill to review your public interface against the included checklist, catching boolean traps, mutable default arguments, and unclear parameter ordering before release. ## Quick Start Ask the agent to review your Python library's public API for naming consistency, error handling, and deprecation strategy.

Frequently Asked Questions about python-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a good Python library API?▼

Follow progressive disclosure: expose simple module-level functions for common cases, configurable classes for advanced use, and low-level internals for power users. Keep naming consistent with verb-based actions and get_/is_/to_ prefixes.

How to deprecate a function in Python without breaking users?▼

Emit a DeprecationWarning with warnings.warn, pointing users to the replacement function and setting stacklevel=2 so the warning shows the caller's location. Keep the old function working as a thin wrapper around the new one.

What naming conventions should Python library functions follow?▼

Use verbs for actions like encode() and validate(), get_ prefixes for retrieval, is_/has_/can_ for booleans, and to_/from_ for conversions. Consistent patterns make APIs discoverable via autocomplete and documentation.

Why are mutable default arguments bad in Python APIs?▼

Mutable defaults like def process(items: list = []) are shared across all calls, causing state to leak between invocations. Use None as the default and create the list inside the function body instead.

When should I use keyword-only arguments in Python?▼

Use keyword-only arguments when a function has multiple boolean or configuration flags, since positional booleans like process(data, True, False) are unreadable. Keyword arguments like validate=True make call sites self-documenting.

Related Skills

Explore More Software Engineering Skills→
pxlcrtivpxlcrtiv

setup-matt-pocock-skills

Configure repository issue trackers, triage labels, and domain documentation layout.

Community
Intermediate
hpsgdhpsgd

write-changelog

Generate structured changelogs from Git history and PR merges.

Official
Advanced
zhenzhizhi12zhenzhizhi12
2

cangjie-error-handle

Explain Cangjie error handling with exceptions, custom exceptions, and Option types.

Community
Intermediate
lunarmoon26lunarmoon26

tech-breakdown-in-chinese

Writes Chinese technical articles that derive architectures step by step from pain points.

Community
Intermediate