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.
-
property
-
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 ofarg2
:@arg.defaults(arg=arg.first(arg.func(...), arg.val('arg2'))) def my_func(arg): ...
Assign
arg
to the value ofarg1
,arg2
, orarg3
. As shown below, passing in a string is the same for passing in anarg.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 ofarg2
orarg3
. 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
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.
-
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