API Reference¶
This page documents the public API exposed by ArgComb.
-
@
argcomb.
argcomb
(default: typing.Optional[argcomb.Condition], /, **kwargs: argcomb.ArgumentSpec)¶ Check that the combination of arguments passed to a function by the caller is valid.
The first argument is a condition which, if supplied, is always evaluated. For example:
@argcomb(Or("a", "b")) def f(a=None, b=None): ...
The
Condition
Or("a", "b")
stipulates that the caller must pass at least one ofa
orb
as an argument tof
when calling it, otherwise anInvalidArgumentCombination
exception will be raised.Subsequent arguments determine further validation that should be carried out if an additional argument is specified. This validation can optionally vary depending on the value that the caller passes for this argument.
@argcomb(Or("a", "b"), a="c") def g(a=None, b=None, c=None): ... @argcomb(Or("a", "b"), a={1: "b", 2: "c", Else: Or("b", "c")) def h(a=None, b=None, c=None): ...
For
g
, at least one ofa
orb
must be passed, and ifa
is passed thenc
must be passed too.For
h
, at least one ofa
orb
must be passed. Ifa
is passed then further validation will take place depending on the value ofa
. Ifa==1
thenb
must also be passed. Ifa==2
thenc
must also be passed. Ifa
takes any value except1
or2
then at least one ofb
orc
must be passed.- Parameters
default – a
Condition
that must always evaluate toTrue
in order for the call to be considered valid.kwargs – for each keyword argument, the name is assumed to be the name of a variable that the caller may supply, and the value determines any validation actions that should take place if that variable is passed by the caller to the decorated function.
-
exception
argcomb.
InvalidArgumentCombination
¶ Raised when the caller passes an invalid argument combination.
-
class
argcomb.
Or
(*args: argcomb.Condition)¶ Logical OR condition.
An
Or
condition will evaluate toTrue
if any of its child conditions evaluates toTrue
.- Parameters
args – conditions from which this new condition should be constructed.
-
class
argcomb.
And
(*args: argcomb.Condition)¶ Logical AND condition.
An
And
condition will evaluate toTrue
only if all its child conditions evaluate toTrue
.- Parameters
args – conditions from which this new condition should be constructed.
-
class
argcomb.
Xor
(*args: argcomb.Condition)¶ Logical XOR condition.
An
Xor
condition will evaluate toTrue
only if exactly 1 of its child conditions evaluates toTrue
.- Parameters
args – conditions from which this new condition should be constructed.
-
class
argcomb.
Not
(arg: argcomb.Condition)¶ Logical NOT condition.
An
Not
condition will evaluate toTrue
only if its child condition evaluates toFalse
.- Parameters
arg – the child condition that this new condition is based on
-
argcomb.
Condition
= typing.Union[str, argcomb.DerivedCondition]¶ Type definition for conditions. A condition can take one of two forms:
A string containing the name of a variable. In this case, the condition evaluates to
True
if the variable named in the string is passed by the caller, orFalse
otherwise.An instance of
Or
,And
,Xor
, orNot
. Such conditions are called “derived conditions”, as they are derived from other conditions.
Since derived conditions can be constructed from other derived conditions, arbitrarily complex conditions can be created, for example:
my_condition = Or(And("a", "b"), Not(Xor("a", "c", "d")))
-
argcomb.
ArgumentSpec
= typing.Union[typing.Dict[typing.Any, argcomb.Condition], argcomb.Condition]¶ Type definition for argument specification.
Argument specifications determine what validation is done in respect of the caller supplying a certain argument.
An argument specification can either be a
Condition
or a dictionary mapping values toCondition
s.If an argument specification is a
Condition
then validation of that argument will succeed if the condition is valid. If the argument specification is a dictionary mapping values toCondition
s then theCondition
will be chosen based on the value of the argument being validated.If an argument specification is a dictionary, a special key
Else
is available to serve as a catch-all for values not otherwise handled. If noElse
key is present and the value of the argument is also not present, no validation will take place. For example:@argcomb(a={1: "b", 2: "c"}) def f(a, b, c): ...
In this case,
f(a=1, b=2)
is valid butf(a=2, b=2)
is not.f(a=3)
is valid.@argcomb(a={1: "b", Else: "c"}) def f(a, b, c): ...
Now
f(a=3)
is not valid, butf(a=3, c=2)
is valid.
-
argcomb.
Else
¶ Special value to indicate validation behaviour when a value-specific condition is not available. See
ArgumentSpec
for more details.