canonical_args package

Submodules

canonical_args.function module

Provides decorators and utilities for interfacing canonical_args with python methods.

canonical_args.function.arg_spec(spec, register=True)

Decorates a method, and checks args against spec.

Parameters:
  • spec (dict) – the arg spec dict
  • register (bool) – default True, registers the spec directly to the function variable scope. once registered, the spec can be retrieved with func.get_spec().
canonical_args.function.get_spec(func)

instance method inserted dynamically into a method scope, allowing retrieval of the arg spec associated with the message:

>>> @arg_spec({...}, register=True)
... def f(x):
...     return x
...
>>> function.get_spec()
{...}

Can also be used directly, as in:

>>> function.get_spec(some.function.name)
{...}
canonical_args.function.im_arg_spec(spec, register=True)

Decorates an instance method, and checks args against spec.

Parameters:
  • spec (dict) – the arg spec dict
  • register (bool) – default True, registers the spec directly to the function variable scope. once registered, the spec can be retrieved with func.get_spec().
canonical_args.function.register_spec(func, spec)

add the argspec var to the function scope

canonical_args.structure module

Provides utilities for checking the structure of a list or dict against provided structure mandates and details.

canonical_args.structure.checkspec(spec, args=[], kwargs={})

canonical_args.check module

class canonical_args.check.ChoiceOfOne

Bases: list

class canonical_args.check.StructuredList

Bases: list

class canonical_args.check.StructuredListType

Bases: type

canonical_args.check.check_subtype(subname, subtype, subarg, should_cast=False)

check the type of subarg against the potential subtypes.

Parameters:
  • subname (str) – the name of the arg (for error formatting)
  • subtype (<type 'type'> or canonical_args.check.ChoiceOfOne) – the type to check against
  • subarg – the argument whose type is being checked
  • should_cast (bool) – default False, when True, will attempt to cast the subarg to type subtype. can only work for native types and cls with appropriate constructors.
Returns:

subarg or correct type (possibly altered if should_cast)

If subtype is of type ChoiceOfOne, type of subarg will be compared against the list of potentials. Else, will be a straight isinstance check.

canonical_args.check.check_value(subname, subtypes, subvalues, subarg)

Check the subarg against the "values" ref.

canonical_args.check.check_value_comparison(subname, subvalues, subarg)

Check the subarg against the comparison string in subvalues.

Parameters:
  • subname (str) – the name of the argument (for error parsing)
  • subvalues (str) – the string containing the comparisons to assert. eg. "((<10||>10)&&!=5)||(<=0&&!=-3)"
  • subarg – the value of the argument
Raises:

AssertionError – if the assertion of the subvalues string fails.
canonical_args.check.check_value_range(subname, subvalues, subarg)

Check the subarg against a number range.

Parameters:
  • subname (str) – the name of the argument (for error parsing)
  • subvalues (str) – a string representing the range: "range(min, max)" . Note that the range is inclusive!
  • subarg – the value of the argument
Raises:

AssertionError – if subarg is not within number range
canonical_args.check.check_value_whitelist(subname, subvalues, subarg)

Check the subarg against a subvalues.

Parameters:
  • subname (str) – the name of the argument (for error parsing)
  • subvalues (list) – a list of allowed values
  • subarg – the value of the argument
Raises:

AssertionError – if subarg not in subvalues
canonical_args.check.cls(subtype)
canonical_args.check.dynamic_import(class_string)

perform a python import, attempting first the new-style (aka getattr(module, "submodule")), and falling back to old style (aka exec "from {} import {}".format(...))

Parameters:class_string (str) – a python import string pointing to the class. eg. package.module.submodule.AClass
Returns:types.ClassType, the imported class.

Note

this method can also work for packages and modules, not only classes.

canonical_args.check.eval_subtype(subtype)

get the subtype from a subtype string.

Parameters:subtype (str or unicode) – the string version of the type

Acceptable values:

Format Use
“int” native types: str, float, int, bool, dict, list, etc.
“one([])” choice of one, can nest ‘cls’ calls here
“structlist([])” a structured list structlist([int, str, float])
“cls(‘’)” a class import string
“NoneType” evaluates to type(None)
“TypeType” evaluates to <type 'type'>
canonical_args.check.one(subtype)
canonical_args.check.structlist(subtype)
canonical_args.check.type_to_string(subtype)

convert a subtype (aka, types.* to a string)

>>> type_to_string(type(10))
'int'
>>> type_to_string(package.module.SomeObject())
'package.module.SomeObject'

Module contents

Make top-level imports available.

canonical_args.check_args(spec, args=[], kwargs={})
canonical_args.checkspec(spec, args=[], kwargs={})
canonical_args.arg_spec(spec, register=True)

Decorates a method, and checks args against spec.

Parameters:
  • spec (dict) – the arg spec dict
  • register (bool) – default True, registers the spec directly to the function variable scope. once registered, the spec can be retrieved with func.get_spec().
canonical_args.im_arg_spec(spec, register=True)

Decorates an instance method, and checks args against spec.

Parameters:
  • spec (dict) – the arg spec dict
  • register (bool) – default True, registers the spec directly to the function variable scope. once registered, the spec can be retrieved with func.get_spec().
canonical_args.register_spec(func, spec)

add the argspec var to the function scope