subcommand – Creating commands with Subcommands

This module provides scaffolding for subcommand classes. Individual subcommands are defined in SCEngine. SCEngine is a drop-in replacement for CLIEngine. Then add each class to the SCController.subEngines list on a subclass of SCController. SCController can be run the same way CLIEngine works. Both SCController and SCEngine are subclasses of CLIEngine and should behave naturally with a CLIEngine-style configuration.

Base Class API Documentation

class pyshell.subcommand.SCEngine(command=None, **kwargs)

A base engine for use as a subcommand or stand-alone command like CLIEngine. When used as a sub-command, it should be attached to a SCController to act as the base command.

Parameters:command – The command name for this object. It can also be set as a class attribute: cls.command It cannot be changed once the program has initialized.

command

docstring for command

help

The help for this sub-parser or parses

init()

Post-initialization functions. These will be run after the sub-parser is established.

parse()

Parse. By default, does nothing if this object is a subcommand.

configure()

Configure this object. Does nothing if this object is a subcommand.

after_configure()

Actions to be run after configuration. This method can be overwritten to provide custom actions to be taken before the engine gets configured.

arguments(*args)

Parse the given arguments. If no arguments are given, parses the known arguments on the command line. Generally this should parse all arguments except -h for help, which should be parsed last after the help text has been fully assembled. The full help text can be set to the self.parser.epilog attribute.

Parameters:*args – The arguments to be parsed.

Similar to taking the command line components and doing " -h --config test.yml".split(). Same signature as would be used for argparse.ArgumentParser.parse_args()

before_configure()

Actions to be run before configuration. This method can be overwritten to provide custom actions to be taken before the engine gets configured.

config

pyshell.config.Configuration object for this engine.

configure_logging()

Configure the logging system using the configuration underneath config["logging"] as a dictionary configuration for the logging module.

description

The textual description of the command line interface, set as the description of the parser from argparse.

do()

This method should handle the main operations for the command line tool. The user should overwrite this method in Engine subclasses for thier own use. The KeyboardInterrupt or SystemExit errors will be caught by kill()

kill()

This function should forcibly kill any subprocesses. It is called when do() raises a KeyboardInterrupt or SystemExit to ensure that any tasks can be finalized before the system exits. Errors raised here are not caught.

log

This engine’s logger

opts

Command Line Options, as paresed, for this engine

parser

argparse.ArgumentParser instance for this engine.

run()

This method is used to run the command line engine in the expected order. This method should be called to run the engine from another program.

classmethod script()

The class method for using this module as a script entry point. This method ensures that the engine runs correctly on the command line, and is cleaned up at the end.

class pyshell.subcommand.SCController(**kwargs)

An engine for the creation of python packages

subEngines = []

A list of SCEngine subclasses which define the subcommands for this engine. This is the only attribute required for a working SCController.

mode

Return the mode

subcommand

The active subcommand.

do()

Call the subcommand do() method.

after_configure()

Actions to be run after configuration. This method can be overwritten to provide custom actions to be taken before the engine gets configured.

arguments(*args)

Parse the given arguments. If no arguments are given, parses the known arguments on the command line. Generally this should parse all arguments except -h for help, which should be parsed last after the help text has been fully assembled. The full help text can be set to the self.parser.epilog attribute.

Parameters:*args – The arguments to be parsed.

Similar to taking the command line components and doing " -h --config test.yml".split(). Same signature as would be used for argparse.ArgumentParser.parse_args()

before_configure()

Actions to be run before configuration. This method can be overwritten to provide custom actions to be taken before the engine gets configured.

config

pyshell.config.Configuration object for this engine.

configure_logging()

Configure the logging system using the configuration underneath config["logging"] as a dictionary configuration for the logging module.

description

The textual description of the command line interface, set as the description of the parser from argparse.

init()

Initialization after the parser has been created.

kill()

Killing mid-command, calls the active subcommand kill() method.

log

This engine’s logger

opts

Command Line Options, as paresed, for this engine

parser

argparse.ArgumentParser instance for this engine.

run()

This method is used to run the command line engine in the expected order. This method should be called to run the engine from another program.

classmethod script()

The class method for using this module as a script entry point. This method ensures that the engine runs correctly on the command line, and is cleaned up at the end.

parse()

Parse command line args

configure()

Configure the package creator