Designing Clean Python Library APIs: A Practical Checklist

This article is based on the 2017 PyCon talk “How to make a good library API” and presents a checklist of useful advice for building Python library APIs.

Simplicity

Include simple client code in the README, e.g., the Pendulum README starts with a short user example.

Reduce redundant code: count the lines from the first line to the actual API call. For example, urllib2 has far more boilerplate than the Requests library.

Provide use‑case documentation, such as the examples on https://python-social-auth-docs.readthedocs.io/en/latest/use_cases.html .

Iteratively improve defaults: sensible default values based on the most common usage patterns.

Do not copy‑paste source code snippets into your API.

Avoid confusing input: Check for ambiguous parameter names (e.g., Scrapy’s to parameter accepting a list of strings). Detect unnecessary object instantiation just to call an API (e.g., requiring StringIO for a file‑like argument). Prefer built‑in types over custom ones when possible.

Follow the Principle of Least Astonishment: ensure default behavior matches user expectations regarding performance, side effects, safety, reliability, and constraints.

Provide proper abstraction: users should care about *what* to solve, not *how* it is solved. Avoid “leaky abstractions” such as treating remote resources like local ones.

Make the API feel like native Python: follow Python conventions (e.g., dict.get(key, default) style arguments).

Consistency

Naming should follow Python conventions and PEP‑8; tools like flake8 can enforce this.

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

Define null/empty values consistently (e.g., None , False , [] , '' , 0 ).

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

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

Flexibility

Reduce overall discontinuity: Ensure each class has a single responsibility; split if necessary. Avoid functions that do multiple unrelated tasks; split them unless performance demands a combined function. Provide refactoring hooks or callbacks for users who need to modify behavior. Avoid hidden parameters; expose all relevant options. Return all information a user might need. Support comprehensive testing, e.g., mock all relevant paths.

Build layered abstractions: simple to highly customized (e.g., Celery’s @app.task decorator and custom task classes).

Allow users to bypass abstractions when necessary (e.g., Django’s .extra and .raw for raw SQL).

Standardize error messages across back‑ends (e.g., unified database connection error messages).

Follow Pythonic idioms: Use properties for getters/setters. Leverage magic methods ( __repr__ , operator overloads). Use context managers ( with ) for resource lifecycles. Employ decorators, iterators, generators, asyncio , built‑in collections, and high‑order functions like list.sort(key=…) . Apply pipeline, inheritance, and generator patterns where appropriate (e.g., python‑social‑auth pipeline, Django class inheritance, Scrapy generators). Embrace duck typing and “if it walks like a duck…” principles.

Internationalize user‑visible strings.

Security

Audit documentation for warning words (e.g., “warning”, “careful”) and revise code to be safer.

Use Python’s warnings module to emit standard warnings.

Make unsafe behavior explicit; avoid silent defaults like fields = None without explanation.

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

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

Fail fast: raise clear exceptions (e.g., ValueError for invalid arguments, TypeError for incompatible types) with helpful messages.

Summary

The goal of a well‑designed API is to make simple tasks simple, complex tasks possible, and to eliminate error‑prone usage.