Essential Checklist for Designing Clean Python Library APIs

Simplicity

Include simple client code in the README, e.g., Pendulum's README starts with basic usage.

Reduce redundant code; count lines from the first line to the actual API call. Compare urllib2 with requests for less boilerplate.

Provide use‑case examples, such as the Python‑Social‑Auth use‑case 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 support both single values and collections where appropriate.

Prefer built‑in types over custom ones when possible.

Follow the Principle of Least Astonishment: defaults should match user expectations regarding performance, side effects, security, and reliability.

Abstract implementation details; expose what the user needs to solve, not how.

Make the API feel like native Python, adhering to Python conventions (e.g., dict‑style get).

Consistency

Follow PEP 8 naming conventions; use tools like flake8 to enforce style.

Maintain consistent terminology and ordering (e.g., string_encode vs decode_string).

Standardize handling of empty values (None, False, [], '', 0) and avoid surprising truthiness.

Keep parameter order consistent across similar functions.

Ensure similar behaviors have similar signatures (e.g., numbers.sort() vs sort(numbers)).

Flexibility

Reduce overall discontinuity by ensuring each class has a single responsibility.

Split functions that perform multiple actions, unless high‑frequency calls justify a combined interface.

Provide refactoring hooks or callbacks instead of requiring users to copy‑paste code.

Expose underlying parameters when useful, rather than hiding them.

Return comprehensive information that callers may need.

Design APIs to handle all relevant user scenarios.

Test each mockable path, e.g., sched.scheduler with timefunc and delayfunc.

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

Leverage Python idioms: properties for getters/setters, magic methods for operator overloading, __repr__ for debugging, context managers, decorators, iterators, generators, and asyncio for async work.

Security

Audit documentation for warning‑type language and replace it with safer patterns.

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

Avoid unsafe defaults; do not assign placeholder values like fields = None indiscriminately.

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

Do not rely on call order; use context managers where appropriate.

Fail fast with clear exception types (e.g., raise ValueError for invalid formats, TypeError for incompatible types) and informative messages.

Conclusion

The checklist aims to make simple tasks simple, turn complex problems into realistic solutions, and eliminate erroneous usage patterns.