typedargs.annotate module

Decorators that allow you to annotate type information with a function or class.

Summary

Functions:

annotated	Mark a function as callable from the command line.
context	Declare that a class defines a context.
context_from_module	Given a module, create a context from all of the top level annotated symbols in that module.
docannotate	Annotate a function using information from its docstring or from type annotations.
finalizer	Indicate that this function destroys the context in which it is invoked, such as a quit method on a subprocess or a delete method on an object.
get_help	Return usage information about a context or function.
param	Decorate a function to give type information about its parameters.
return_type	Specify that this function returns a typed value.
returns	Specify how the return value of this function should be handled.
short_description	Given an object with a docstring, return the first line of the docstring
stringable	Specify that the return value should just be printed as a string.
takes_cmdline	Annotate that a function should take the entire command line.

Reference

typedargs.annotate.context_from_module(module)

Given a module, create a context from all of the top level annotated symbols in that module.

typedargs.annotate.get_help(func)

Return usage information about a context or function.

For contexts, just return the context name and its docstring For functions, return the function signature as well as its argument types.

Parameters:func (callable) – An annotated callable function Returns:The formatted help text Return type:str

typedargs.annotate.param(name, type_name, *validators, **kwargs)

Decorate a function to give type information about its parameters.

This function stores a type name, optional description and optional list of validation functions along with the decorated function it is called on in order to allow run time type conversions and validation.

Parameters:

• name (string) – name of the parameter
• type_name (string) – The name of a type that will be known to the type system by the time this function is called for the first time. Types are lazily loaded so it is not required that the type resolve correctly at the point in the module where this function is defined.
• validators (list(string or tuple)) –

  A list of validators. Each validator can be defined either using a string name or as an n-tuple of the form [name, *extra_args]. The name is used to look up a validator function of the form validate_name, which is called on the parameters value to determine if it is valid. If extra_args are given, they are passed as extra arguments to the validator function, which is called as:

  validator(value, *extra_args)

• desc (string) – An optional descriptioon for this parameter that must be passed as a keyword argument.

Returns:

A decorated function with additional type metadata

Return type:

callable

typedargs.annotate.returns(desc=None, printer=None, data=True)

Specify how the return value of this function should be handled.

Parameters:

• desc (str) – A deprecated description of the return value
• printer (callable) – A callable function that can format this return value
• data (bool) – A deprecated parameter for specifying that this function returns data.

typedargs.annotate.stringable(func)

Specify that the return value should just be printed as a string.

Parameters:func (callable) – The function that we wish to annotate.

typedargs.annotate.return_type(type_name, formatter=None)

Specify that this function returns a typed value.

Parameters:

• type_name (str) – A type name known to the global typedargs type system
• formatter (str) – An optional name of a formatting function specified for the type given in type_name.

typedargs.annotate.context(name=None)

Declare that a class defines a context.

Contexts are for use with HierarchicalShell for discovering and using functionality from the command line.

Parameters:name (str) – Optional name for this context if you don’t want to just use the class name.

typedargs.annotate.finalizer(func)

Indicate that this function destroys the context in which it is invoked, such as a quit method on a subprocess or a delete method on an object.

typedargs.annotate.takes_cmdline(func)

Annotate that a function should take the entire command line.

typedargs.annotate.docannotate(func)

Annotate a function using information from its docstring or from type annotations.

If function has a type annotations then docstring types would be ignored. The annotation actually happens at the time the function is first called to improve startup time. For this function to work, the docstring must be formatted correctly. You should use the typedargs pylint plugin to make sure there are no errors in the docstring.

This decorator is also could be used on classes to annotate their __init__() method. If decorator applied on a class then the priority for source of type info would be:

__init__() type annotations -> class docstring -> __init__() docstring

Class docstring would be taken if it contains any argument type information. __init__() docstring would be ignored in this case.

typedargs.annotate.annotated(func, name=None)

Mark a function as callable from the command line.

This function is meant to be called as decorator. This function also initializes metadata about the function’s arguments that is built up by the param decorator.

Parameters:

• func (callable) – The function that we wish to mark as callable from the command line.
• name (str) – Optional string that will override the function’s built-in name.

typedargs.annotate.short_description(func)

Given an object with a docstring, return the first line of the docstring