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!