Supporting Class APIs

Supporting Class APIs#

The decree_tree.DecreeTree has several other classes as parents. It is not expected that they would be used directly. However, the following is a reference guide.

Decree#

It is possible to create single-level commands using the Decree class:

class decree_tree.decree.Decree(*, name=None, prog_is_name=False, version=None)#

A class for creating a command using argparse.

Configure variables that change during execution.

Parameters:

  • name (str | None) – the command name, if overriding it for the instance

  • prog_is_name (bool) – whether to use self.name as the program name in help

  • version (str | None) – version information to display

help: ClassVar[str] = ''#

short help text to use (allows __doc__ to be lengthy)

options: Namespace#

the set of argparse-processed options to be used

name: str = ''#

the name of the command, if not snake-cased class name

prog_is_name: bool#

whether to use the name as the prog, for help

version: str | None#

version information; use --version to show

configure_parser(subparsers=None)#

Configure the parser for this object. Typically not called by nor overridden in end-user code.

Parameters:

subparsers (_SubParsersAction | None) – the subparsers object from a parent, if any

Raises:

ValueError – when the configuration of the name or prog is incorrect

Return type:

None

parser_options()#

Add to and override options passed to the argparse parser.

Returns:

dict[str, Any] – the options to provide to the parser

run(argv=None, options=None)#

Run the command by itself via command line or with defined arguments.

Parameters:

  • argv (Sequence[str] | None) – command-line arguments to parse

  • options (Namespace | None) – processed arguments, circumventing parse_args if specified

Returns:

Any – the results, to facilitate testing

add_arguments(parser)#

Add arguments to parser (not self._decree_parser), if any. Subclass overrides typically include a call to super().add_arguments(parser). Handle manual argument processing in process_options, not here.

Parameters:

parser (ArgumentParser) – the parser to which arguments will be added

Return type:

None

preprocess_options(argv=None, options=None)#

Populate self.options if it isn’t already. Typically not called by nor overridden in end-user code.

Parameters:

  • argv (Sequence[str] | None) – command-line arguments to parse

  • options (Namespace | None) – processed arguments, circumventing parse_args if specified

Return type:

None

process_options()#

Perform any needed processing on the options, prior to execution. Subclass overrides typically include a call to super().process_options().

Return type:

None

execute()#

Execute [sub]command processing. Subclass overrides typically include a call to super().execute().

Returns:

Any – any required data

Tree#

It is possible to create generic trees of objects using the Tree class:

class decree_tree.tree.Tree(**kwargs)#

Bases: Generic[T]

Manage a generic tree structure.

Initialize the tree structure.

Parameters:

**kwargs (Any) – any keyword arguments needed for subclass customization

append_child(child)#

Append a new child.

Parameters:

child (TypeVar(T, bound= Tree) | Type[TypeVar(T, bound= Tree)]) – the object, class, or subclass to append

Returns:

TypeVar(T, bound= Tree) – the child itself, in case it was created within this method

property children: list[T]#

Provide a copy of the child objects. This could be a generator, but since the list of children is expected to be short, there shouldn’t be a need.

Returns:

the list of child instances

child_index(name, raise_exception=False)#

Determine the index of a child.

Parameters:

  • name (str) – the name of the child to look up

  • raise_exception (bool) – whether to raise an exception if the child cannot be found

Raises:

InvalidName – if the child cannot be found and raise_exception is True

Returns:

int | None – the index of the child or None if not found

property child_names: list[str]#

Provide a list of the names of the child objects. This could be a generator, but since the list of children is expected to be short, there shouldn’t be a need.

Returns:

the list of the names of the child instances

clear_children()#

Clear the list of children.

Return type:

None

property count_children: int#

Provide the number of children.

Returns:

the number of children

find_child(name, raise_exception=False)#

Find a direct child by name and return it or None.

Parameters:

  • name (str) – the name of the child to find

  • raise_exception (bool) – whether to raise an exception if the child cannot be found

Raises:

InvalidName – if the child cannot be found and raise_exception is True

Returns:

TypeVar(T, bound= Tree) | None – the child or None if not found

get_child(*args)#

Look up and provide the nested child object.

Parameters:

*args (str) – the nested path of names to the requested object

Raises:

InvalidName – if a matching object cannot be found

Returns:

Tree[TypeVar(T, bound= Tree)] – the object found

property get_name: str#

A way to determine the “name” of an object. Rather than try to directly include the “name” variable from Decree in Tree, define a method that is intended to be overridden by a subclass. This method could perhaps be private, but that would force special handling in several Tree methods.

Returns:

the “name” of the instance

insert_child(index, child)#

Insert a new child.

Parameters:

  • index (int) – the position at which to insert the child

  • child (TypeVar(T, bound= Tree) | Type[TypeVar(T, bound= Tree)]) – the object, class, or subclass to insert

Returns:

TypeVar(T, bound= Tree) – the child object

property parent: T | None#

Return the parent of the object, if any.

Returns:

the parent object or None

property parents: list[T]#

Generate a list of the parents of this tree, in order. This could be a generator, but since the list of parents is expected to be short, there shouldn’t be a need.

Returns:

the parents

property parent_names: list[str]#

Generate a list of the names of the parents of this tree, in order. This could be a generator, but since the list of parents is expected to be short, there shouldn’t be a need.

Returns:

the names of the parents

remove_child(name)#

Remove a child.

Parameters:

name (str) – The name of the child to remove.

Return type:

None

replace_child(name, child, raise_exception=False)#

Replace a child.

Parameters:

  • name (str) – the name of the child to replace

  • child (TypeVar(T, bound= Tree) | Type[TypeVar(T, bound= Tree)]) – the new object, class, or subclass

  • raise_exception (bool) – the raise_exception argument to the index() call

Returns:

TypeVar(T, bound= Tree) | None – the instantiated child object

sort_children(*, key=None, reverse=False)#

Alphabetically sort the list of subcommands in place.

Parameters:

  • key (Callable[[TypeVar(T, bound= Tree)], SupportsLT | SupportsGT] | None) – a single-argument function used to extract the comparison key for each child

  • reverse (bool) – whether to sort in reverse

Return type:

None