Supporting Class APIs

The DecreeTree class has two parents. It is not expected that they would be used directly. However, the following is a reference guide for them and for other classes used via composition.

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

Raises:

ValueError – if name is an empty string

help: ClassVar[str] = ''

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

argument_parser_class

the argument parser to use at the root level (and inherited there from)

alias of ModifiedArgumentParser

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

debug_tracing: bool

whether to show debug tracing statements

repr_kwargs()

Provide relevant non-default __init__ kwargs for __repr__.

Returns:

dict[str, str | bool | None] – the relevant kwargs in the desired order

configure_parser()

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

Return type:

None

parser_options(subparser=False)

Add to and override options passed to the argparse parser.

Parameters:

subparser (bool) – whether the options are applied to a subparser applied via subparsers.add_parser() versus a top level parser initialization

Returns:

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

debug_print(message, **kwargs)

Print an internal debug statement. Could be overridden to use logging. By default, expects message to support str.format() substitution, including the self variable.

Parameters:

• message (str) – the message to print, using str.format() keywords

• **kwargs (Any) – the arguments to specify to str.format() in addition to self

Return type:

None

run(argv=None, options=None, *, debug_tracing=False, argument_parser_class=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

• debug_tracing (bool) – whether to show debug tracing statements

• argument_parser_class (type[ArgumentParser] | None) – an override for the argument parser class

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

ModifiedArgumentParser

The ModifiedArgumentParser class enhances the standard argparse.ArgumentParser parser:

class decree_tree.parser.ModifiedArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

Bases: ArgumentParser

An enhanced argument parser subclass.

parse_known_args(args=None, namespace=None)

Force parse_known_args to behave like parse_args. This ensures that usage statements for unexpected arguments are as specific as possible for the chosen subcommand. Note that add_subparsers calls will reuse the caller’s own class by default.

Parameters:

• args (Sequence[str] | None) – the list of strings to parse

• namespace (Any | None) – an object to take the attributes, defaulting to an argparse.Namespace object

Returns:

tuple[Any, list[str]] – a two item tuple containing the populated namespace and the list of remaining argument strings