| name | designing-python-apis |
| description | Designs intuitive Python library APIs following principles of simplicity, consistency, and discoverability. Handles API evolution, deprecation, breaking changes, and error handling. Use when designing new library APIs, reviewing existing APIs for improvements, or managing API versioning and deprecations. |
Python API Design
Core Principles
- Simplicity: Simple things simple, complex things possible
- Consistency: Similar operations work similarly
- Least Surprise: Behave as users expect
- Discoverability: Find via autocomplete and help
Progressive Disclosure Pattern
from mylib import encode, decode
result = encode(37.7749, -122.4194)
from mylib import Encoder
encoder = Encoder(precision=15)
from mylib.internals import BitEncoder
Naming Conventions
encode(), decode(), validate()
get_user(), get_config()
is_valid(), has_permission()
to_dict(), from_json()
Error Handling
class MyLibError(Exception):
"""Base exception with helpful messages."""
def __init__(self, message: str, *, hint: str = None):
super().__init__(message)
self.hint = hint
raise ValidationError(
f"Latitude must be -90 to 90, got {lat}",
hint="Did you swap latitude and longitude?"
)
Deprecation
import warnings
def old_function():
warnings.warn(
"old_function() deprecated, use new_function()",
DeprecationWarning,
stacklevel=2,
)
return new_function()
Anti-Patterns
process(data, True, False, True)
process(data, validate=True, cache=False)
def process(items: list = []):
def process(items: list | None = None):
For detailed patterns, see:
Review Checklist
Naming:
- [ ] Clear, self-documenting names
- [ ] Consistent patterns throughout
- [ ] Boolean params read naturally
Parameters:
- [ ] Minimal required parameters
- [ ] Sensible defaults
- [ ] Keyword-only after positional clarity
Errors:
- [ ] Custom exceptions with context
- [ ] Helpful error messages
- [ ] Documented in docstrings
Learn More
This skill is based on the Ergonomics section of the Guide to Developing High-Quality Python Libraries by Will McGinnis. See these posts for deeper coverage: