When should I use varargs in designing a Python API?

Question

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

Answer 1

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.