Package

arg

class arg.Args(wraps)[source]

The primary Args class that orchestrates running of python-args decorators.

Responsible for parsing call args and orchestrating various run modes. Can be used to construct other top-level python-args decorators that interface with the library.

property partial

Return a partial version of the Args where validators, contexts, and defaults can run against partial arguments.

property pre_func

Return a version of the Args where everything before the main function runs.

exception arg.BindError[source]

When a function can’t be bound to arguments

For example, if @args.defaults or @args.validators have functions that take arguments with names other than the function they are decorating, a BindError could be thrown if the called function does not have all necessary arguments.

arg.call()[source]

Obtains the current python-args call

The current call is always set by the __call__ method of the Args class when invoking running.

If called outside of a python-args call, will return None

arg.contexts(*context_managers, **named_context_managers)[source]

Enter contexts based on arguments.

Parameters
  • *context_managers (List[contextmanager]) – A list of context managers that will be entered before calling the function. Context managers can take arguments that the function takes.

  • **named_context_managers (Dict[contextmanagers]) – Naming a context manager will assign the context manager resource to the argument name, allowing the function (or other args decorators) to use it.

arg.defaults(**default_funcs)[source]

Process default values to function arguments.

Parameters

**default_funcs (Dict[func]) – A mapping of argument names to functions that should process those arguments before they are provided to the function call.

Examples

Pre-process a string argument so that it is always uppercase:

@arg.defaults(arg_name=lambda arg_name: arg_name.upper())
def my_func(arg_name):
    # arg_name will be the uppercase version when my_func is called
class arg.first(*lazy_vals, default=<object object>)[source]

Obtain the result of the first lazy method that can be executed without binding errors.

Examples

Assign arg to a function result if the function can be bound, otherwise assign it to the value of arg2:

@arg.defaults(arg=arg.first(arg.func(...), arg.val('arg2')))
def my_func(arg):
    ...

Assign arg to the value of arg1, arg2, or arg3. As shown below, passing in a string is the same for passing in an arg.val:

@arg.defaults(arg=arg.first('arg1', 'arg2', 'arg3'))
def my_func(arg):
    ...

Similarly, passing in a function is the same for passing in an arg.func:

@arg.defaults(arg=arg.first(lambda a: 'a', lambda b: 'b'))
def my_func(arg):
    ...

Assign arg to the value of arg2 or arg3. Default it to the value of “nothing” if none of those argument exist:

@arg.defaults(arg=arg.first('arg1', 'arg2', default='nothing'))
def my_func(arg):
    ...
class arg.func(wraps, default=<object object>)[source]

For lazy calling of a function.

All python-args decorator functions are wrapped in this. The func class lazily evaluates these functions and dynamically binds arguments.

This class can still be used directly in other scenarios, although it is never required to use it directly in python-args decorators, it can be used by other python-args utilities (like arg.init).

class arg.init(class_, *args, **kwargs)[source]

For lazy initialization of a class.

Args and keyword arguments can also be lazily loaded with arg.func, arg.init, arg.val or any lazy python-args utilities.

class arg.Lazy[source]

A base class for lazy utilties

Tracks a call chain that can later be lazily evaulated.

For example, @arg.val is a lazy utility that can obtain the value of an argument (@arg.val(‘arg_name’)) and then apply chained operations (@arg.val(‘arg_name’).strip() to strip a string for example).

arg.load(lazy, **call_args)[source]

Loads a lazy object with arguments.

We cannot override __call__ on lazy objects since lazy objects are chainable. So we must go through this interface to evaluate them.

arg.parametrize(**parametrize_funcs)[source]

Parametrize a function’s arguments.

Parameters

**parametrize_funcs (Dict[func]) – A mapping of argument names to functions that return iterables. The argument will be parametrized over the iterable, calling the underlying function for each element.

Returns

Parametrized functions return a list of all results.

Return type

list

Examples

This is an example of parametrizing a function that doubles a value:

@arg.parametrize(val=arg.val('vals'))
def double(val):
    return val * 2

assert double(vals=[1, 2, 3]) == [2, 4, 6]
arg.s(*arg_decorators)[source]

Creates a python-args class from multiple decorators. Useful for creating higher-level methods of running functions.

Parameters

*arg_decorators (List[Args]) – A list of python-args decorators (@arg.validators, @arg.contexts, etc)

Returns

An Args class with the appropriate decorators applied. If no arg_decorators are provided, will return an Args class with no decorators.

Return type

Args

class arg.val(arg, default=<object object>)[source]

A shortcut that lazily returns the value of an argument.

arg.validators(*validation_funcs)[source]

Run validators over arguments.

Parameters

*validation_funcs (List[func]) – Functions that validate arguments. Argument names of the calling function are used to determine which validators to run.

Examples

Validate an email address is correct::

def validate_email(email):
    if email.not_valid_address():
        raise ValueError('Email is invalid')

@arg.validators(validate_email)
def my_func(email):
    # A ValueError will be raised when calling with an invalid email