python-api-checklist
python-api-checklist copied to clipboard
ideas for useful additions
some ideas:
-
use keyword-only arguments for any function argument with a non-obvious meaning, e.g. a function that fetches "items" (whatever those may be) from a url, but can optionally take a timeout should use
def fetch_items(url, *, timeout=...)
to force the caller to be explicit. this makes code that calls this function much simpler to read. "explicit is better than implicit." -
never use
True
/False
return values to indicate success or failure. instead, raise an appropriate exception when things go wrong, and if the function succeeds, return either nothing (side effect only) or a meaningful value. this is especially important for security-sensitive apis, e.g.verify_signature(data, sig)
should always raise an exception since a status code is easy to ignore, which may lead to serious bugs.
Thanks @wbolster! I'll work to incorporate that later.