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.
- name – the name of the option, usually like
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
andLogger.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
andbold
.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.
-
terminal.
blink
(text)¶ Blink style.
-
terminal.
overline
(text)¶ Overline style.
-
terminal.
inverse
(text)¶ Inverse style.
-
terminal.
conceal
(text)¶ Conceal style.
-
terminal.
strike
(text)¶ Strike style.