Developer Interface

This part of the documentation covers the interface of terminal. Terminal only depends on Python’s built-in batteries, it is lightweight.

Command

Command is the interface which you can create a command parser.

class terminal.Command(name, description=None, version=None, usage=None, title=None, func=None, help_footer=None, arguments=None)

The command interface.

New in version 0.4: The arguments parameters were added.

Parameters:
  • name – name of the program
  • description – description of the program
  • version – version of the program
  • usage – usage of the program
  • title – title of the program
  • func – command function to be invoked
  • arguments – positional arguments

Create a Command instance in your cli file:

from terminal import Command
command = Command('name', 'description', 'version')

The command will add a default help option. If you set a version parameter, it will add a default version option too. You can add more options:

command.option('-v, --verbose', 'show more logs')

# required option in < and >
command.option('-o, --output <output>', 'the output file')

# optional option in [ and ]
command.option('-o, --output [output]', 'the output file')

# set a default value in description
command.option('-o, --source [dir]', 'the output file, default: src')

Usually you will need a subcommand feature, add a subcommand like this:

subcommand = Command('build', 'build command')
subcommand.option('--source <source>', 'source directory')

command.action(subcommand)

A subcommand is a full featured Command, which means you can add a subcommand to the subcommand too. We can also add a subcommand with the decorator feature:

@command.action
def build(output='_build'):
    '''
    generate the documentation.

    :param output: the output directory
    '''
    do_something(output)

After defining the command, we can parse the command line argv:

command.parse()

If we have pased --verbose in the terminal, we can get:

assert command.verbose is True
action(command)

Add a subcommand. (Alias subcommand).

Parameters:command – a function or a Command

You can add a Command as an action, or a function:

command.action(subcommand)

If you prefer a decorator:

@command.action
def server(port=5000):
    '''
    docstring as the description

    :param port: description of port
    '''
    start_server(port)

It will auto generate a subcommand from the server method.

args

argv that are not for options.

get(key)

Get parsed result.

After parse() the argv, we can get the parsed results:

# command.option('-f', 'description of -f')
command.get('-f')

command.get('verbose')
# we can also get ``verbose``: command.verbose
option(name, description=None, action=None, resolve=None)

Add or get option.

Here are some examples:

command.option('-v, --verbose', 'show more log')
command.option('--tag <tag>', 'tag of the package')
command.option('-s, --source <source>', 'the source repo')
Parameters:
  • name – arguments of the option
  • description – description of the option
  • action – a function to be invoked
  • resolve – a function to resolve the data
parse(argv=None)

Parse argv of terminal

Parameters:argv – default is sys.argv
parse_options(arg)

Parse options with the argv

Parameters:arg – one arg from argv
print_help()

Print the help menu.

print_title(title)

Print output the title.

You can create a colorized title by:

class MyCommand(Command):

    def print_title(self, title):
        if 'Options' in title:
            print(terminal.magenta(title))
        elif 'Commands' in title:
            print(terminal.green(title))
        return self

You can get the color function with terminal.

print_version()

Print the program version.

subcommand(command)

Alias for Command.action.

validate_options()

Validate options

class terminal.Option(name, description=None, action=None, resolve=None)

The Option object for Command.

Parameters:
  • name – the name of the option, usually like -v, --verbose
  • description – the description of this option
  • action – a function to be invoke when this option is found
  • resolve – a function to transform the option data
parse(name, description)

Parse option name.

Parameters:
  • name – option’s name
  • description – option’s description

Parsing acceptable names:

  • -f: shortname
  • –force: longname
  • -f, –force: shortname and longname
  • -o <output>: shortname and a required value
  • -o, –output [output]: shortname, longname and optional value

Parsing default value from description:

  • source directory, default: src
  • source directory, default: [src]
  • source directory, default: <src>
to_python(value=None)

Transform the option value to python data.

Logger

Logger is the interface which you can create a logging instance. We do have a initialized instance on terminal:

>>> terminal.log.info('this is the default log instance')
class terminal.Logger(**kwargs)

The Logger interface.

Parameters:
  • verbose – control if the log to show verbose log
  • quiet – control if the log to show debug and info log
  • indent – control the indent level, default is zero

Play with Logger, it supports nested logging:

log = Logger()
log.info('play with log')

log.start('start a indent level')
log.info('this log will indent two spaces')
log.end('close a indent level')
config(**kwargs)

Config the behavior of Logger.

Control the output to show Logger.verbose log:

log.config(verbose=True)

Control the output to show only the Logger.warn and Logger.error log:

log.config(quiet=True)
debug(*args)

The debug level log.

end(*args)

End a nested log.

error(*args)

The error level log.

info(*args)

The info level log.

message(level, *args)

Format the message of the logger.

You can rewrite this method to format your own message:

class MyLogger(Logger):

    def message(self, level, *args):
        msg = ' '.join(args)

        if level == 'error':
            return terminal.red(msg)
        return msg
start(*args)

Start a nested log.

verbose

Make it the verbose log.

A verbose log can be only shown when user want to see more logs. It works as:

log.verbose.warn('this is a verbose warn')
log.verbose.info('this is a verbose info')
warn(*args)

The warn level log.

Prompt

Prompt are functions to communicate with the terminal.

terminal.prompt(name, default=None)

Grab user input from command line.

Parameters:
  • name – prompt text
  • default – default value if no input provided.
terminal.password(name, default=None)

Grabs hidden (password) input from command line.

Parameters:
  • name – prompt text
  • default – default value if no input provided.
terminal.confirm(name, default=False, yes_choices=None, no_choices=None)

Grabs user input from command line and converts to boolean value.

Parameters:
  • name – prompt text
  • default – default value if no input provided.
  • yes_choices – default ‘y’, ‘yes’, ‘1’, ‘on’, ‘true’, ‘t’
  • no_choices – default ‘n’, ‘no’, ‘0’, ‘off’, ‘false’, ‘f’
terminal.choose(name, choices, default=None, resolve=None, no_choice=('none', ))

Grabs user input from command line from set of provided choices.

Parameters:
  • name – prompt text
  • choices – list or tuple of available choices. Choices may be single strings or (key, value) tuples.
  • default – default value if no input provided.
  • no_choice – acceptable list of strings for “null choice”

Colors

class terminal.Color(*items)

Color object for painters.

You should always use the high-level API of colors and styles, such as red and bold.

But if you are so interested in this module, you are welcome to use some advanced features:

s = Color('text')
print(s.bold.red.italic)

All ANSI colors and styles are available on Color.

terminal.colorize(text, color, background=False)

Colorize text with hex code.

Parameters:
  • text – the text you want to paint
  • color – a hex color or rgb color
  • background – decide to colorize background
colorize('hello', 'ff0000')
colorize('hello', '#ff0000')
colorize('hello', (255, 0, 0))

Front colors

terminal.black(text)

Black color.

terminal.red(text)

Red color.

terminal.green(text)

Green color.

terminal.yellow(text)

Yellow color.

terminal.blue(text)

Blue color.

terminal.magenta(text)

Magenta color.

terminal.cyan(text)

Cyan color.

terminal.white(text)

White color.

Background colors

terminal.black_bg(text)

Black background.

terminal.red_bg(text)

Red background.

terminal.green_bg(text)

Green background.

terminal.yellow_bg(text)

Yellow background.

terminal.blue_bg(text)

Blue background.

terminal.magenta_bg(text)

Magenta background.

terminal.cyan_bg(text)

Cyan background.

terminal.white_bg(text)

White background.

Styles

terminal.bold(text)

Bold style.

terminal.faint(text)

Faint style.

terminal.italic(text)

Italic style.

terminal.underline(text)

Underline style.

Blink style.

terminal.overline(text)

Overline style.

terminal.inverse(text)

Inverse style.

terminal.conceal(text)

Conceal style.

terminal.strike(text)

Strike style.