variadic is a Python (2.7+ and 3.4+) function decorator to write variadic functions accepting a mix of arguments and iterables of those arguments. Oh, and they keep their argspec, so tools doing introspection (Sphinx doc, IDEs, etc.) will work well. No ugly `f(*args, **kwds)` in your doc!

It’s licensed under the MIT license. It’s available on the Python package index, its documentation is hosted by Python and its source code is on GitHub.

Questions? Remarks? Bugs? Want to contribute? Open an issue!

## Quick start¶

Install from PyPI:

```\$ pip install variadic
```

Import:

```>>> from variadic import variadic
```

Define a function:

```>>> @variadic(int)
... def f(*args):
...   return args
>>> f(1, 2, [3, 4], xrange(5, 8))
(1, 2, 3, 4, 5, 6, 7)
```

## User guide¶

### Introduction¶

```>>> @variadic(int)
... def f(*xs):
...   return xs
```

It can be called with a variable number of arguments:

```>>> f()
()
>>> f(1, 2, 3, 4)
(1, 2, 3, 4)
```

So far, no change, but it can also be called with lists (any iterable, in fact) of arguments:

```>>> f([])
()
>>> f([1, 2, 3], (4, 5, 6))
(1, 2, 3, 4, 5, 6)
>>> f(xrange(1, 4))
(1, 2, 3)
```

And you can even mix them:

```>>> f(1, [2, 3], (4, 5), xrange(6, 8))
(1, 2, 3, 4, 5, 6, 7)
```

Positional arguments, default values and keyword arguments are OK as well:

```>>> @variadic(int)
... def f(a, b=None, *cs, **kwds):
...   return a, b, cs, kwds
>>> f(1)
(1, None, (), {})
>>> f(1, d=4)
(1, None, (), {'d': 4})
>>> f(1, 2, (3, 4), 5, d=6)
(1, 2, (3, 4, 5), {'d': 6})
```

### Pearls¶

#### Documentation generated by Sphinx for decorated functions¶

It looks like a regular variadic function:

`demo`(a, b=None, *xs, **kwds)

Demo function.

Parameters: a – A b – B xs – Xs kwds – keywords

#### TypeError raised when calling with bad arguments¶

Exactly as if it was not decorated:

```>>> @variadic(int)
... def f(*xs):
...   pass
>>> f(a=1)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: f() got an unexpected keyword argument 'a'
```

#### Exception raised by the decorated function¶

`@variadic` adds just one stack frame with the same name as the decorated function:

```>>> @variadic(int)
... def f(*xs):
...   raise Exception
>>> f()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<ast_in_variadic_py>", line 1, in f
File "<stdin>", line 3, in f
Exception
```

## Reference¶

`variadic`(typ)

Decorator taking a variadic function and making a very-variadic function from it: a function that can be called with a variable number of iterables of arguments.

Parameters: typ – the type (or tuple of types) of arguments expected. Variadic arguments that are instances of this type will be passed to the decorated function as-is. Others will be iterated and their contents will be passed.