wilderness package

Submodules

wilderness.application module

Application class

This module contains the Application class.

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.application.Application(name: str, version: str, author: Optional[str] = None, title: Optional[str] = None, description: Optional[str] = None, default_command: Optional[str] = None, add_help: bool = True, extra_sections: Optional[Dict[str, str]] = None, prolog: Optional[str] = None, epilog: Optional[str] = None, options_prolog: Optional[str] = None, options_epilog: Optional[str] = None, add_commands_section: bool = False)

Bases: DocumentableMixin

Base class for applications

This is the main Application object that Wilderness applications are expected to inherit from. All text that is supplied to the man pages, such as the description, can use basic formatting constructs documented in the ManPage.groffify() method.

Parameters:

• name (str) – The name of the application.

• version (str) – The version of the application, to be used in creating the man pages.

• author (Optional[str]) – The author(s) of the application. This is used in the man pages, but is not actually visible in the output (it is recorded in the metadata header of the man pages).

• title (Optional[str]) – The title of the application is used as a short description. It shows up in the man pages as the text after the application name in the first section.

• description (Optional[str]) – Long description of the application. This is used in the man pages in the DESCRIPTION section after the synopsis.

• default_command (Optional[str]) – The default command to run when none is supplied on the command line. By default this is omitted and the help text is shown instead, but some applications may want to run a particular command as default instead.

• add_help (bool) –

  Whether to add help commands or not. This adds support for the traditional help flags -h or --help for the short help text on the command line, as well as the help command that opens the man pages for the subcommands of the application. Note that the short help text on the command line typically provides a list of available commands.

  See the FakeDF example for an application where this is not enabled.

• extra_sections (Optional[Dict[str, str]]) – Additional sections of documentation for the man page. This is expected to be provided as a dictionary where the keys are the section headers and the values are the section text. Basic formatting constructs such as lists and enumerations are understood by the text processor (see ManPage.groffify() for further details).

• prolog (Optional[str]) – Text to be shown in the short command line help text, before the (grouped) list of available commands. Newline characters are preserved.

• epilog (Optional[str]) – Text to be shown in the short command line help text, after the list of available commands. Newline characters are preserved.

• options_prolog (Optional[str]) – Text to be shown in the man page before the list of options. See the FakeDF application for an example.

• options_epilog (Optional[str]) – Text to be shown in the man page after the list of options. See the FakeDF application for an example.

• add_commands_section (bool) – Whether to automatically generate a section in the application man page that lists the available commands.

add(command: Command)

Add a command to the application

Note that the register method of the command is called when it is added to the application.

Parameters:

command (wilderness.command.Command) – The command to add to the application.

add_argument(*args, **kwargs) → Action

Add an argument to the application

This wraps the argparse.ArgumentParser.add_argument method, with the minor difference that it supports a “description” keyword argument, which will be used to provide a long help message for the argument in the man page.

add_group(title: str) → Group

Create a group of commands

Parameters:

title (str) – The title for the group.

Returns:

The created command group.

Return type:

wilderness.group.Group

property author: str

The author(s) of the application

property commands: List[Command]

List the commands registered to the application

Returns:

commands – The list of commands registered to the application.

Return type:

List[wilderness.command.Command]

create_manpage() → ManPage

Create the Manpage for the application

Returns:

man_page – The generated ManPage object.

Return type:

wilderness.manpages.ManPage

format_help() → str

Format the command line help for the application

This method creates the help text for the command line, which is typically printed when the -h / –help / help command line arguments are used. The print_help() method calls this method to format the help text.

Returns:

help_text – The help text as a single string.

Return type:

str

get_command(command_name: str) → Command

Get a command by name

Parameters:

command_name (str) – The name of the command to find

Returns:

command – The instance of the Command to be returned.

Return type:

wilderness.command.Command

Raises:

KeyError – If no command with the provided name can be found, a KeyError is raised.

get_commands_text() → str

property groups: List[Group]

List the groups registered to the application

If no groups have been added to the application but commands have been added, this property will contain a single group, the root group.

Returns:

groups – The list of groups registered to the application

Return type:

List[wilderness.group.Group]

handle() → int

Main method to override for single-command applications.

When creating a single-command application (such as the FakeDF example), this method must be overridden with the actual functionality. For multi-command applications, this method is not used.

Returns:

return_code – The return code of the application, to be used as the return code on the command line.

Return type:

int

property name: str

The name of the application

print_help(file: Optional[TextIO] = None)

Print the command line help text for the application

Parameters:

file (Optional[TextIO]) – The file to which to write the help text. If omitted, the help text will be written to sys.stdout.

register()

Register arguments to the application

Override this method to add command line arguments to the application (using self.add_argument, etc). For single-command applications, this should be used to add all command line arguments. For multi-command applications, this method can be used to add arguments that apply to all commands, or arguments such as –version.

This method is called upon initialization of the Application object.

run(args: Optional[List[str]] = None, namespace: Optional[Namespace] = None, exit_on_error: bool = True) → int

Main method to run the application

Parameters:

• args (Optional[List[str]]) – List of arguments to the application. This is typically only used for testing, as by default the arguments will be read from the command line.

• namespace (Optional[argparse.Namespace]) – Namespace object to save the arguments to. By default a new argparse.Namespace object is created.

• exit_on_error (bool) – Whether or not to exit when argparse encounters an error.

Returns:

return_code – The return code of the application, to be used as the return code at the command line.

Return type:

int

run_command(command: Command) → int

Run a particular command directy

Parameters:

command (wilderness.command.Command) – The command to execute

Returns:

return_code – The return code of the handle() method of the command.

Return type:

int

set_epilog(epilog: str) → None

Set the epilog of the command line help text

Parameters:

epilog (str) – Text to include at the end of the command line help text.

set_prolog(prolog: str) → None

Set the prolog of the command line help text

Parameters:

prolog (str) – Text to include before the list of commands in the command line help text. The prolog is printed after the synopsis of the application.

property version: str

The version of the package or application

wilderness.argparse_wrappers module

ArgumentParser override

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.argparse_wrappers.ArgumentGroup(group: _ArgumentGroup)

Bases: object

add_argument(*args, **kwargs)

property command: Optional[wilderness.command.Command]

class wilderness.argparse_wrappers.ArgumentParser(*args, exit_on_error=True, **kwargs)

Bases: ArgumentParser

exit(status: Optional[int] = 0, message: Optional[str] = None)

class wilderness.argparse_wrappers.MutuallyExclusiveGroup(meg: _MutuallyExclusiveGroup)

Bases: object

add_argument(*args, **kwargs)

property command: Optional[wilderness.command.Command]

wilderness.command module

Command definition

This module contains the definitions for the Command class.

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.command.Command(name: str, title: Optional[str] = None, description: Optional[str] = None, add_help: bool = True, extra_sections: Optional[Dict[str, str]] = None, options_prolog: Optional[str] = None, options_epilog: Optional[str] = None)

Bases: DocumentableMixin

add_argument(*args, **kwargs)

add_argument_group(*args, **kwargs) → ArgumentGroup

add_mutually_exclusive_group(*args, **kwargs) → MutuallyExclusiveGroup

property application: Optional[wilderness.application.Application]

create_manpage() → ManPage

abstract handle() → int

property name: str

register()

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

property title: Optional[str]

wilderness.documentable module

DocumentableMixin definitions

A documentable is either an application or command, for which we can generate a manpage.

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.documentable.DocumentableMixin(description: Optional[str] = None, extra_sections: Optional[Dict[str, str]] = None, options_prolog: Optional[str] = None, options_epilog: Optional[str] = None)

Bases: object

property args: Namespace

The parsed command line arguments

property argument_help: Dict[str, Optional[str]]

abstract create_manpage() → ManPage

property description: Optional[str]

get_options_text() → str

get_synopsis(width: int = 80) → str

property parser: ArgumentParser

wilderness.formatter module

HelpFormatter

We have a slightly adjusted HelpFormatter that we use for the manpages.

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.formatter.HelpFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: HelpFormatter

wilderness.group module

Group definitions

This module contains the definitions for the Group class, which is used to collect distinct Command objects for the application.

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.group.Group(title: Optional[str] = None, is_root: bool = False)

Bases: object

add(command: wilderness.command.Command) → None

property application: Optional[wilderness.application.Application]

property commands: List[wilderness.command.Command]

commands_as_actions() → List[Action]

property is_root: bool

Return whether the groups is its Application’s root group

set_app(app: wilderness.application.Application) → None

property title: Optional[str]

wilderness.help module

Help command definitions

This module contains the definitions for our HelpCommand and our HelpAction. The HelpCommand takes care of opening the manpage when the “help” subcommand is called, and the HelpAction is slightly modified to use our help text formatter (see the Application class).

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.help.HelpCommand

Bases: Command

handle() → int

register()

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

wilderness.help.have_man_command() → bool

wilderness.help.help_action_factory(app: wilderness.application.Application)

wilderness.manpages module

Code to generate manpages

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.manpages.ManPage(application_name: str, author: Optional[str] = '', command_name: Optional[str] = None, date: Optional[str] = None, title: Optional[str] = None, version: Optional[str] = '')

Bases: object

add_section(label: str, text: str) → None

add_section_synopsis(synopsis: str) → None

export(output_dir: str) → str

groffify(text: str) → str

Format a text line for use in manpages

This function supports several basic formatting constructs. First, newlines in the text are preserved. Next, lists can be created by starting lines with * , as long as each list entry starts on its own line (that is, separated by n). Indented text can be created by prefixing a line with one or more t characters. Numbered lists are also recognized, as long as each item starts with 1. (that is, a digit followed by a period, followed by a space).

Parameters:

text (str) – The text to convert

Returns:

formatted_text – The formatted text ready for use in manpage documents.

Return type:

str

groffify_line(line: str) → str

header() → str

metadata() → List[str]

property name: str

preamble() → List[str]

section_name() → str

wilderness.manpages.build_manpages(app: wilderness.application.Application, output_directory: str = 'man') → None

Write manpages to the output directory

Parameters:

• app (wilderness.Application) – The application for which to generate manpages.

• output_directory (str) – The output directory to which to write the manpages.

wilderness.tester module

Tester class

This module contains the CommandTester class.

Author: G.J.J. van den Burg License: See the LICENSE file. Copyright: 2021, G.J.J. van den Burg

This file is part of Wilderness.

class wilderness.tester.Tester(app: Application)

Bases: object

property application: Application

clear()

get_return_code() → Optional[int]

get_stderr() → Optional[str]

get_stdout() → Optional[str]

test_application(args: Optional[List[str]] = None) → None

test_command(cmd_name: str, args: List[str]) → None

Module contents

class wilderness.Application(name: str, version: str, author: Optional[str] = None, title: Optional[str] = None, description: Optional[str] = None, default_command: Optional[str] = None, add_help: bool = True, extra_sections: Optional[Dict[str, str]] = None, prolog: Optional[str] = None, epilog: Optional[str] = None, options_prolog: Optional[str] = None, options_epilog: Optional[str] = None, add_commands_section: bool = False)

Bases: DocumentableMixin

Base class for applications

This is the main Application object that Wilderness applications are expected to inherit from. All text that is supplied to the man pages, such as the description, can use basic formatting constructs documented in the ManPage.groffify() method.

Parameters:

• name (str) – The name of the application.

• version (str) – The version of the application, to be used in creating the man pages.

• author (Optional[str]) – The author(s) of the application. This is used in the man pages, but is not actually visible in the output (it is recorded in the metadata header of the man pages).

• title (Optional[str]) – The title of the application is used as a short description. It shows up in the man pages as the text after the application name in the first section.

• description (Optional[str]) – Long description of the application. This is used in the man pages in the DESCRIPTION section after the synopsis.

• default_command (Optional[str]) – The default command to run when none is supplied on the command line. By default this is omitted and the help text is shown instead, but some applications may want to run a particular command as default instead.

• add_help (bool) –

  Whether to add help commands or not. This adds support for the traditional help flags -h or --help for the short help text on the command line, as well as the help command that opens the man pages for the subcommands of the application. Note that the short help text on the command line typically provides a list of available commands.

  See the FakeDF example for an application where this is not enabled.

• extra_sections (Optional[Dict[str, str]]) – Additional sections of documentation for the man page. This is expected to be provided as a dictionary where the keys are the section headers and the values are the section text. Basic formatting constructs such as lists and enumerations are understood by the text processor (see ManPage.groffify() for further details).

• prolog (Optional[str]) – Text to be shown in the short command line help text, before the (grouped) list of available commands. Newline characters are preserved.

• epilog (Optional[str]) – Text to be shown in the short command line help text, after the list of available commands. Newline characters are preserved.

• options_prolog (Optional[str]) – Text to be shown in the man page before the list of options. See the FakeDF application for an example.

• options_epilog (Optional[str]) – Text to be shown in the man page after the list of options. See the FakeDF application for an example.

• add_commands_section (bool) – Whether to automatically generate a section in the application man page that lists the available commands.

add(command: Command)

Add a command to the application

Note that the register method of the command is called when it is added to the application.

Parameters:

command (wilderness.command.Command) – The command to add to the application.

add_argument(*args, **kwargs) → Action

Add an argument to the application

This wraps the argparse.ArgumentParser.add_argument method, with the minor difference that it supports a “description” keyword argument, which will be used to provide a long help message for the argument in the man page.

add_group(title: str) → Group

Create a group of commands

Parameters:

title (str) – The title for the group.

Returns:

The created command group.

Return type:

wilderness.group.Group

property author: str

The author(s) of the application

property commands: List[Command]

List the commands registered to the application

Returns:

commands – The list of commands registered to the application.

Return type:

List[wilderness.command.Command]

create_manpage() → ManPage

Create the Manpage for the application

Returns:

man_page – The generated ManPage object.

Return type:

wilderness.manpages.ManPage

format_help() → str

Format the command line help for the application

This method creates the help text for the command line, which is typically printed when the -h / –help / help command line arguments are used. The print_help() method calls this method to format the help text.

Returns:

help_text – The help text as a single string.

Return type:

str

get_command(command_name: str) → Command

Get a command by name

Parameters:

command_name (str) – The name of the command to find

Returns:

command – The instance of the Command to be returned.

Return type:

wilderness.command.Command

Raises:

KeyError – If no command with the provided name can be found, a KeyError is raised.

get_commands_text() → str

property groups: List[Group]

List the groups registered to the application

If no groups have been added to the application but commands have been added, this property will contain a single group, the root group.

Returns:

groups – The list of groups registered to the application

Return type:

List[wilderness.group.Group]

handle() → int

Main method to override for single-command applications.

When creating a single-command application (such as the FakeDF example), this method must be overridden with the actual functionality. For multi-command applications, this method is not used.

Returns:

return_code – The return code of the application, to be used as the return code on the command line.

Return type:

int

property name: str

The name of the application

print_help(file: Optional[TextIO] = None)

Print the command line help text for the application

Parameters:

file (Optional[TextIO]) – The file to which to write the help text. If omitted, the help text will be written to sys.stdout.

register()

Register arguments to the application

Override this method to add command line arguments to the application (using self.add_argument, etc). For single-command applications, this should be used to add all command line arguments. For multi-command applications, this method can be used to add arguments that apply to all commands, or arguments such as –version.

This method is called upon initialization of the Application object.

run(args: Optional[List[str]] = None, namespace: Optional[Namespace] = None, exit_on_error: bool = True) → int

Main method to run the application

Parameters:

• args (Optional[List[str]]) – List of arguments to the application. This is typically only used for testing, as by default the arguments will be read from the command line.

• namespace (Optional[argparse.Namespace]) – Namespace object to save the arguments to. By default a new argparse.Namespace object is created.

• exit_on_error (bool) – Whether or not to exit when argparse encounters an error.

Returns:

return_code – The return code of the application, to be used as the return code at the command line.

Return type:

int

run_command(command: Command) → int

Run a particular command directy

Parameters:

command (wilderness.command.Command) – The command to execute

Returns:

return_code – The return code of the handle() method of the command.

Return type:

int

set_epilog(epilog: str) → None

Set the epilog of the command line help text

Parameters:

epilog (str) – Text to include at the end of the command line help text.

set_prolog(prolog: str) → None

Set the prolog of the command line help text

Parameters:

prolog (str) – Text to include before the list of commands in the command line help text. The prolog is printed after the synopsis of the application.

property version: str

The version of the package or application

class wilderness.Command(name: str, title: Optional[str] = None, description: Optional[str] = None, add_help: bool = True, extra_sections: Optional[Dict[str, str]] = None, options_prolog: Optional[str] = None, options_epilog: Optional[str] = None)

Bases: DocumentableMixin

add_argument(*args, **kwargs)

add_argument_group(*args, **kwargs) → ArgumentGroup

add_mutually_exclusive_group(*args, **kwargs) → MutuallyExclusiveGroup

property application: Optional[wilderness.application.Application]

create_manpage() → ManPage

abstract handle() → int

property name: str

register()

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

property title: Optional[str]

class wilderness.Group(title: Optional[str] = None, is_root: bool = False)

Bases: object

add(command: wilderness.command.Command) → None

property application: Optional[wilderness.application.Application]

property commands: List[wilderness.command.Command]

commands_as_actions() → List[Action]

property is_root: bool

Return whether the groups is its Application’s root group

set_app(app: wilderness.application.Application) → None

property title: Optional[str]

class wilderness.Tester(app: Application)

Bases: object

property application: Application

clear()

get_return_code() → Optional[int]

get_stderr() → Optional[str]

get_stdout() → Optional[str]

test_application(args: Optional[List[str]] = None) → None

test_command(cmd_name: str, args: List[str]) → None

wilderness.build_manpages(app: wilderness.application.Application, output_directory: str = 'man') → None

Write manpages to the output directory

Parameters:

• app (wilderness.Application) – The application for which to generate manpages.

• output_directory (str) – The output directory to which to write the manpages.