Essential Checklist for Designing Clean Python Library APIs

Simplicity

Include simple client code examples in the README, as Pendulum does.

Minimize redundant code; count the lines from the start of a file to the actual API call.

Provide clear use‑case documentation, e.g., the Python‑Social‑Auth use‑cases page.

Offer sensible default values based on common usage patterns.

Place the most frequently used parameters first and group similar ones together.

Avoid copying raw source snippets into the API.

Prevent ambiguous parameter names and prefer built‑in types over custom ones when possible.

Consistency

Follow Python naming conventions (PEP 8) and use tools like flake8 to enforce them.

Maintain consistent terminology, ordering, abbreviations, underscores, singular/plural forms, and boolean naming.

Define and use a uniform representation for null values (None, False, [], "", 0) and beware of surprising truthiness.

Keep parameter order consistent across similar functions, e.g., datetime constructors.

Ensure similar behaviors have similar interfaces, such as numbers.sort() vs sort(numbers) .

Flexibility

Reduce overall discontinuity by ensuring each class has a single responsibility; split classes that handle multiple concerns.

Break functions that perform multiple actions (containing "and") into smaller functions, unless performance considerations dictate otherwise.

Avoid hidden parameters; expose all necessary arguments to the user.

Provide comprehensive information in API responses, handling all relevant cases.

Support thorough testing, including mocking of low‑level functions when needed.

Offer layered abstractions, from simple decorators like @app.task to customizable task classes.

Leverage Python idioms: properties for getters/setters, magic methods for operator overloading, __repr__ for debugging, context managers for resource handling, decorators for registration, iterators, generators, asyncio for async work, and built‑in collections.

Security

Audit documentation for warning words (e.g., "warning", "careful") and revise code to improve safety.

Use the built‑in warnings module to emit runtime warnings.

Explicitly handle unsafe behaviors, avoiding ambiguous defaults like fileds = None .

Prefer explicit registration functions or decorators over implicit name‑based linking.

Do not rely on call order; use with statements where appropriate.

Raise clear exceptions (e.g., ValueError for invalid formats, TypeError for incompatible types) with informative messages.

Conclusion

The checklist aims to make simple tasks straightforward, turn complex problems into manageable solutions, and eliminate errors permanently when designing Python library APIs.