When should I use varargs in designing a Python API?
api, python, variadic-functions
Solution
Consider using varargs when you expect your users to specify the list of arguments as code at the callsite or having a single value is the common case. When you expect your users to get the arguments from somewhere else, don't use varargs. When in doubt, err on the side of not using varargs.
Using your examples, the most common usecase for os.path.join is to have a path prefix and append a filename/relative path onto it, so the call usually looks like os.path.join(prefix, some_file). On the other hand, any() is usually used to process a list of data, when you know all the elements you don't use any([a,b,c]), you use a or b or c.
Problem
Is there a good rule of thumb as to when you should prefer varargs function signatures in your API over passing an iterable to a function? ("varargs" being short for "variadic" or "variable-number-of-arguments"; i.e. `*args`) For example, `os.path.join` has a vararg signature: ``` os.path.join(first_component, *rest) -> str ``` Whereas `min` allows either: ``` min(iterable[, key=func]) -> val min(a, b, c, ...[, key=func]) -> val ``` Whereas `any`/`all` only permit an iterable: ``` any(iterable) -> bool ```