Cleo allows you to create beautiful and testable command-line commands.
Project description
Cleo allows you to create beautiful and testable command-line commands.
It is heavily inspired by the Symfony Console Component, with some useful additions.
Full documentation available here: http://cleo.readthedocs.org
Creating a basic Command
To make a command that greets you from the command line, create greet_command.py and add the following to it:
def greet(input_, output_):
name = input_.get_argument('name')
if name:
text = 'Hello %s' % name
else:
text = 'Hello'
if input_.get_option('yell'):
text = text.upper()
output_.writeln(text)
greet_command = {
'demo:greet': {
'description': 'Greets someone',
'arguments': [{
'name': {
'description': 'Who do you want to greet?',
'required': False
}
}],
'options': [{
'yell': {
'shortcut': 'y',
'description': 'If set, the task will yell in uppercase letters',
'value_required': None
}
}],
'code': greet
}
}
You also need to create the file to run at the command line which creates an Application and adds commands to it:
#!/usr/bin/env python
# -*- coding: utf-8 -*-
from greet_command import greet_command
from cleo import Application
application = Application()
application.add(greet_command)
if __name__ == '__main__':
application.run()
Test the new command by running the following
$ python application.py demo:greet John
This will print the following to the command line:
Hello John
You can also use the --yell option to make everything uppercase:
$ python application.py demo:greet John --yell
This prints:
HELLO JOHN
Coloring the Output
Whenever you output text, you can surround the text with tags to color its output. For example:
# green text output_.writeln('<info>foo</info>') # yellow text output_.writeln('<comment>foo</comment>') # black text on a cyan background output_.writeln('<question>foo</question>') # white text on a red background output_.writeln('<error>foo</error>')
It is possible to define your own styles using the class OutputFormatterStyle:
style = OutputFormatterStyle('red', 'yellow', ['bold', 'blink'])
output_.get_formatter().set_style('fire', style)
output_.writeln('<fire>foo</fire>')
Available foreground and background colors are: black, red, green, yellow, blue, magenta, cyan and white.
And available options are: bold, underscore, blink, reverse and conceal.
You can also set these colors and options inside the tagname:
# green text output_.writeln('<fg=green>foo</fg=green>') # black text on a cyan background output_.writeln('<fg=black;bg=cyan>foo</fg=black;bg=cyan>') # bold text on a yellow background output_.writeln('<bg=yellow;options=bold>foo</bg=yellow;options=bold>')
Verbosity Levels
Cleo has 3 levels of verbosity. These are defined in the Output class:
Mode |
Value |
---|---|
Output.VERBOSITY_QUIET |
Do not output any messages |
Output.VERBOSITY_NORMAL |
The default verbosity level |
Output.VERBOSITY_VERBOSE |
Increased verbosity of messages |
You can specify the quiet verbosity level with the --quiet or -q option. The --verbose or -v option is used when you want an increased level of verbosity.
It is possible to print a message in a command for only a specific verbosity level. For example:
if Output.VERBOSITY_VERBOSE <= output_.get_verbosity():
output_.writeln(...)
There are also more semantic methods you can use to test for each of the verbosity levels:
if output_.is_quiet():
# ...
if output_.is_verbose():
# ...
When the quiet level is used, all output is suppressed as the default Output.write() method returns without actually printing.