API Design: Lessons Learned
A talk from Raymond Hettinger at PyCon US 2011 that was timely for me.
Apologies for any errors in this index.
- High-level considerations (eg environment, extent of use)
- 5:40: Coercion of multiple types into a single type: “tighten it up to make sure that unwanted types do not accidentally get caught in the mix.”
- 10:00: Design classes for subclassing. Have the API access private equivalents (eg
x = __x
) so that x can be safely overridden. - 15:00: Consider keeping your API flexible. The more public, the more flexible.
- 19:30: Conflicting constructor requirements:
- Good: Classmethods (eg dict(items_list) and dict.from_keys(iterable))
- Bad: Dealing with multiple signatures with one constructor (eg min() taking different types of objects).
- 27:00: Conflicting positional arguments. Solution: when writing arguments, make them keyword-only, by putting them after a
*
:def sorted(iterable, *, reverse=False, key=None)
(from here)def concat(*args, sep="/")
(from the Python 3 tutorial)
- 30:40: Conflicting subclass signatures: (understood option a but not option b)
- 44:00: Flat really is often better than nested!