command_tree package

Submodules

command_tree.argument module

class command_tree.argument.AddArgumentHandler

Bases: command_tree.argument.AddArgumentHandlerBase

Add argument by the default way.

add(parser, *args, **kwargs)

clone()

class command_tree.argument.AddArgumentHandlerBase

Bases: object

Interface for override the default way to use argparser.ArgumenParser.add_argument() function.

Typical usage of this is the MutuallyExclusiveGroup and the ArgumentGroup.

add(parser, *args, **kwargs)

Add argument to parser.

Parameters:

• parser (argparse.ArgumentParser) – the parent parser instance
• args (list) – all pos args for ArgumentParser.add_argument
• kwargs (dict) – all keyword args for ArgumentParser.add_argument

Returns:

the result of the ArgumentParser.add_argument

Return type:

argparse.Action

clone()

Return a new instance the current class

class command_tree.argument.Argument(identifier, args=None, kwargs=None, name_generator=None)

Bases: object

Descriptor for an argparser.ArgumentParser argument.

Parameters:

• identifier (str) – name of the the handler function’s parameter which is declared in the code
• args (list) – all positional arguments for argparser.ArgumenParser.add_argument()
• kwargs (dict) – all keywird arguments for argparser.ArgumenParser.add_argument()
• name_generator (callable) – will be used for the automatic name generation but only if the name not specified explicitly first parameter will be the object name

add_to_parser(parser)

Add this argument to a parser.

Parameters:parser (argparse.ArgumentParser) –

clone(exclude=[])

is_common()

item

set_common(value=True)

command_tree.command_tree module

class command_tree.command_tree.CommandTree(config=None)

Bases: object

Define the main API for build a tree with argparse.

It defines decorators and other functions to it.

Parameters:config (Config) – config

add_argument(obj, *args, **kwargs)

Decorator for argument creation.

Parameters:

• obj – class or function handler
• kwargs (args,) – All other arguments will passed to the ArgumentParser.add_argument function

Returns:

the argument descriptor instance

Return type:

argument.Argument

add_leaf(func, name=None, **kwargs)

Add leaf to the tree.

Parameters:

• func (function) – the handler function
• name (str) – the node name
• items (list) – explicit list of all the sub nodes
• kwargs – all other keyword arguments will passed to the ArgumentParser.add_subparsers().add_parser function

Returns:

the item descriptor instance

Return type:

Leaf

add_node(cls, name=None, items=None, **kwargs)

Add node to the tree.

Parameters:

• cls (type) – the handler class
• name (str) – the node name
• items (list) – explicit list of all the sub nodes
• kwargs – all other keyword arguments will passed to the ArgumentParser.add_subparsers().add_parser function

Returns:

the item descriptor instance

Return type:

Node

add_root(cls, items=None, **kwargs)

Add root node to the tree.

Parameters:

• cls (type) – the handler class
• items (list) – explicit list of all the sub nodes
• kwargs – all other keyword arguments will passed to the argparser.ArgumentParser constructor

Returns:

the item descriptor instance

Return type:

Node

argument(*args, **kwargs)

Decorator for argument creation.

All arguments will passed to the argparse.ArgumentParser.add_argument() function

Returns:wrapper Return type:function

build(parser=None)

Build the parser tree.

Parameters:parser (argparse.ArgumentParser) – external parser to build Returns:the builded parser Return type:argparse.ArgumentParser

children

common_argument(*args, **kwargs)

Decorator for argument creation.

All arguments will passed to the argparse.ArgumentParser.add_argument() function

Returns:wrapper Return type:function

execute(parser=None, args=None)

Build the parsers and execute it.

It will be run the handler function chosed by the user.

Parameters:

• parser (argparse.ArgumentParser) – external parser built by the CommandTree.build
• args (list) – external arguments to parse by the argument parser

Returns:

The return value of the leaf handler function

generate_name_for_argument(args, kwargs, identifier)

items

leaf(name=None, **kwargs)

Decorator for leaf creation.

Parameters:

• name (str) – the node name
• kwargs – all other keyword arguments will passed to the ArgumentParser.add_subparsers().add_parser function

Returns:

wrapper

Return type:

function

node(name=None, items=None, **kwargs)

Decorator for node creation.

Parameters:

• name (str) – the node name
• items (list) – explicit list of all the sub nodes
• kwargs – all other keyword arguments will passed to the ArgumentParser.add_subparsers().add_parser function

Returns:

wrapper

Return type:

function

node_handler(func)

Decorator for mark a function to handle the childless nodes.

optional(cls)

Decorator for optional subparsers.

root(items=None, **kwargs)

Special node decorator; it can used only once.

Parameters:

• items (list) – explicit list of all the sub nodes
• kwargs – all other keyword arguments will passed to the ArgumentParser.add_subparsers().add_parser function

Returns:

wrapper

Return type:

function

subparser_arguments(**kwargs)

Decorator for set argument to the ArgumentParser.add_subparsers() created by the node.

All keyword argument will passed to the ArgumentParser.add_subparsers()

Returns:wrapper Return type:function

command_tree.config module

class command_tree.config.Config(docstring_parser=<command_tree.doc_string_parser.GoogleParser object>, get_default_from_function_param=True, get_argument_type_from_function_default_value_type=True, change_underscores_to_hyphens_in_names=False, prepend_double_hyphen_prefix_if_arg_has_default=False, generate_simple_hyphen_name=False)

Bases: object

Config holder class for the CommandTree.

Parameters:

• docstring_parser (ParserBase) – If there is doc declared in the class or function some data from the docstring will be parsed out. At this time only the help string is used, but if you want to disable the docstring parsing, set None to this value.
• get_default_from_function_param (bool) – If provided the default value in the leaf decorated function declaration and there is not set already by the decorator, the builder will take that value and add to the ArgumentParser.add_argument’s parameters.
• get_argument_type_from_function_default_value_type (bool) – If the default value provided somehow (by the decorator or the function declaration), and the type is not set already by the decorator, the type of the default value will be used as argument type.
• change_underscores_to_hyphens_in_names (bool) – If the argument, leaf or node name contains any underscore, and there is no explicit name specified, the name generator will replace any underscores (‘_’) to hyphens (‘-‘). So if the function or argument name is ‘command_name’ the generate name will be ‘command-name’ if this setting is enabled.
• prepend_double_hyphen_prefix_if_arg_has_default (bool) – If the name not defined explicit, and there is a default value for the argument add hyphen prefix to the generated argument name.
• generate_simple_hyphen_name (dict or bool) – If there is no explicit name set and this value is not None, the CommandTree try to generate a name whith a simple hyphen prefix. So if the argument name is ‘arg1’, the generated name will be ‘-a’. But the config value is a dict, for override this method with a custom mapping. If this value is {“arg1”: “a1”}, the generated argument name will be ‘-a1’.

command_tree.doc_string_parser module

class command_tree.doc_string_parser.DocStringInfo(description=None)

Bases: object

Structured info about the object’s docstring.

Parameters:description (str) – the object description, typically the first line of the docstring

class Argument(name, help=None)

Bases: object

Structured info about one argument.

Parameters:

• name (str) – the name of the argument
• help (str) – the description of the argument

add_argument_info(arginfo)

Add an argument info instance.

Parameters:arginfo (DocStringInfo.Argument) – the info instance

class command_tree.doc_string_parser.GoogleParser

Bases: command_tree.doc_string_parser.ParserBase

Parser class for Google style doc string comment format.

See: https://google.github.io/styleguide/pyguide.html#Comments

parse(content)

See: command_tree.doc_string_parser.ParserBase.parse().

class command_tree.doc_string_parser.ParserBase

Bases: object

Base class to define interface for the doc string parser classes

parse(content)

Parse the docstring content.

Parameters:content (str) – the whole docstring content Returns:structured info Return type:DocStringInfo

command_tree.exceptions module

exception command_tree.exceptions.ArgumentException(message, context=None)

Bases: command_tree.exceptions.ExceptionOnContext

exception command_tree.exceptions.CommandTreeException

Bases: Exception

exception command_tree.exceptions.ExceptionOnContext(message, context=None)

Bases: command_tree.exceptions.CommandTreeException

exception command_tree.exceptions.ItemException(message, context=None)

Bases: command_tree.exceptions.ExceptionOnContext

exception command_tree.exceptions.LeafException(message, context=None)

Bases: command_tree.exceptions.ItemException

exception command_tree.exceptions.NodeException(message, context=None)

Bases: command_tree.exceptions.ItemException

exception command_tree.exceptions.RootNodeException(message, context=None)

Bases: command_tree.exceptions.NodeException

command_tree.groups module

class command_tree.groups.ArgumentGroup(command_tree, title=None, description=None)

Bases: command_tree.groups.GroupBase

Group for create MutuallyExclusiveGroup as described as argparse.ArgumentParser.add_argument_group().

class AddArgumentHandler(title=None, description=None)

Bases: command_tree.groups.GroupAddArgumentHandler

clone()

class command_tree.groups.GroupAddArgumentHandler(factory, argument_group=None)

Bases: command_tree.argument.AddArgumentHandlerBase

add(parser, *args, **kwargs)

get_group(parser)

get_parent(parser)

class command_tree.groups.GroupBase(command_tree, handler)

Bases: object

Interface class to define group handlers.

Parameters:

• command_tree (CommandTree) – a CommandTree instance
• handler (AddArgumentHandlerBase) – command_tree.argument.AddArgumentHandlerBase based class instance

argument(*args, **kwargs)

Decorator for argument creation.

All arguments will passed to the ArgumentParser.add_argument function

Returns:wrapper function Return type:function

common_argument(*args, **kwargs)

Decorator for argument creation.

All arguments will passed to the ArgumentParser.add_argument function

Returns:wrapper function Return type:function

handler

class command_tree.groups.MutuallyExclusiveGroup(command_tree, required=False, argument_group=None)

Bases: command_tree.groups.GroupBase

Group for create MutuallyExclusiveGroup as described as argparse.ArgumentParser.add_mutually_exclusive_group().

class AddArgumentHandler(required, argument_group=None)

Bases: command_tree.groups.GroupAddArgumentHandler

clone()

command_tree.item module

class command_tree.item.Item(name, obj, id, arguments, parser_args=None, docstring_parser=None, name_generator=None)

Bases: object

Represents an argparse.ArgumentParser object.

Parameters:

• name (str) – the name of the item
• obj (type) – the function or class handler type
• id (int) – unique id for the item, will be use in the ordering
• arguments (OrderedDict) – argument name (str) -> argument descriptor dict (Arguments)
• parser_args (dict) – arguments for argparse.ArgumentParser constructor
• docstring_parser (ParserBase) – a ParserBase derived class instance
• name_generator (callable) – will be used for the automatic name generation but only if the name not specified explicitly first parameter will be the object name

arguments

Getter for argument list.

Returns

OrderedDict: str -> Argument instances

build(parser)

Build the argument parser tree.

Parameters:parser (argparse.ArgumentParser) – a parser instance to build

build_arguments(parser)

Add arguments to a parser.

Parameters:parser (argparse.ArgumentParser) – the parent parser

id

Getter for id

name

Getter for name.

obj

Getter for the obj – class or function.

obj_name

Getter for the class or function name.

Returns:the name Return type:str

parse_doc_string()

Parse the doc string

parser_args

Getter for parser args.

reindex(new_id)

Rewrite the id.

Parameters:new_id (int) – the new id

traverse_for_common_arguments()

Iterate through the arguments and the sub items if has any and do the things to build the common args.

command_tree.leaf module

class command_tree.leaf.Leaf(name, func, id, arguments, parser_args=None, docstring_parser=None, name_generator=None)

Bases: command_tree.item.Item

An item what will not has any sub items, only arguments.

For other args see command_tree.item.Item

Parameters:func (function) – the handler function

build(parser)

See command_tree.item.Item.build().

obj_name

See command_tree.item.Item.obj_name().

traverse_for_common_arguments()

See command_tree.item.Item.traverse_for_common_arguments().

command_tree.node module

class command_tree.node.CommonArgumentProxy(node)

Bases: object

class command_tree.node.Node(name, cls, id, arguments, items=None, parser_args=None, docstring_parser=None, name_generator=None)

Bases: command_tree.item.Item

An item what may have sub nodes or leafs.

Holding a class type and instance.

For other args see command_tree.item.Item

Parameters:

• cls (type) – the class handler type
• items (list) – list of command_tree.item.Item decorated objects

build(parser)

See command_tree.item.Item.build().

create_handler_instance(arguments)

TODO

fetch()

Iterate throught the class attributes (classes or functions) and search for sub items.

It is assumes that the sub items has been decorated already.

get_item(name)

Get the specfified sub item by name.

Parameters:name (str) – the sub item’s name Returns:the sub item or None Return type:Item

handle(kwargs)

has_handler

instance

Getter for instance.

instance_arguments

Getter for the instance arguments.

Returns:the handler constructor arguments Return type:dict

items

Getter for the list of the sub items.

Returns:Item based instances Return type:list

obj_name

See command_tree.item.Item.obj_name().

parent

required

set_subparser_arguments(kwargs)

Set subparser arguments

Parameters:kwargs (dict) – key-value pairs for ArgumentParser.add_subparsers()

traverse_for_common_arguments()

See command_tree.item.Item.traverse_for_common_arguments().

command_tree.types module

command_tree.types.valid_dir(value)

Function what is can be used as argument type to check the file is exists or not.

Example

>>> from argparse import ArgumentParser
>>> from command_tree import valid_dir
>>> parser = ArgumentParser()
>>> parser.add_argument("dir", type = valid_dir)
>>> print(parser.parse_args())
Namespace(dir='/')

command_tree.types.valid_file(value)

Function what is can be used as argument type to check the file is exists or not.

Example

>>> from argparse import ArgumentParser
>>> from command_tree import valid_file
>>> parser = ArgumentParser()
>>> parser.add_argument("file", type = valid_file)
>>> print(parser.parse_args())
Namespace(file='setup.py')

Module contents