ideas for useful additions

[wbolster]

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.

[fjsj]

Thanks @wbolster! I'll work to incorporate that later.