Designing Clean Python Library APIs: A Practical Checklist

Simplicity

Include simple client code in the README, as demonstrated by Pendulum.

Eliminate redundant code by counting lines from the start to the actual API call; compare urllib2 with Requests for excess boilerplate.

Provide clear use‑case examples, such as the Python‑Social‑Auth documentation.

Offer sensible default values based on common usage patterns.

Place the most frequently used parameters first and group similar ones together, mirroring conventions like JavaScript's history.pushState signature.

Avoid copying raw source snippets into your API.

Consistency

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

Maintain consistent terminology, ordering, abbreviations, underscore usage, singular/plural forms, and boolean naming (e.g., button.enabled vs button.disabled ).

Define a uniform meaning for null values (e.g., None , False , [] , '' , 0 ) and watch out for surprising cases like bool(datetime.time(0)) .

Keep parameter order consistent across functions (e.g., datetime.datetime(year, month, …) vs datetime.timedelta(days, …) ).

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

Flexibility

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

Avoid functions that perform multiple actions; split them unless high‑frequency calls justify a combined function.

Provide refactoring hooks and callbacks instead of encouraging copy‑paste modifications.

Expose necessary parameters of lower‑level APIs rather than hiding them.

Return all information a user might need and handle all possible usage scenarios.

Test each mockable component thoroughly; use sched.scheduler and related parameters as examples.

Security

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

Use Python's warnings module to emit standard 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 context managers ( with statements) where appropriate.

Adopt Pythonic error handling: raise specific exceptions (e.g., ValueError , TypeError ) with clear messages.

Conclusion

The checklist aims to make simple tasks simple, complex tasks achievable, and erroneous designs impossible, guiding developers toward clean, consistent, flexible, and secure Python library APIs.