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 of a or b as an argument to f when calling it, otherwise an InvalidArgumentCombination 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 of a or b must be passed, and if a is passed then c must be passed too.

For h, at least one of a or b must be passed. If a is passed then further validation will take place depending on the value of a. If a==1 then b must also be passed. If a==2 then c must also be passed. If a takes any value except 1 or 2 then at least one of b or c must be passed.

Parameters

  • default – a Condition that must always evaluate to True 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 to True if any of its child conditions evaluates to True.

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 to True only if all its child conditions evaluate to True.

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 to True only if exactly 1 of its child conditions evaluates to True.

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 to True only if its child condition evaluates to False.

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:

  1. 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, or False otherwise.

  2. An instance of Or, And, Xor, or Not. 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 to Conditions.

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 to Conditions then the Condition 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 no Else 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 but f(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, but f(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.