Exploring the Demo App¶
The cliff source package includes a demoapp
directory containing
an example main program with several command plugins.
Setup¶
To install and experiment with the demo app you should create a virtual environment and activate it. This will make it easy to remove the app later, since it doesn’t do anything useful and you aren’t likely to want to hang onto it after you understand how it works.
$ pip install virtualenv
$ virtualenv .venv
$ . .venv/bin/activate
(.venv)$
Next, install cliff in the same environment.
(.venv)$ python setup.py install
Finally, install the demo application into the virtual environment.
(.venv)$ cd demoapp
(.venv)$ python setup.py install
Usage¶
Both cliff and the demo installed, you can now run the command
cliffdemo
.
For basic command usage instructions and a list of the commands available from the plugins, run:
(.venv)$ cliffdemo -h
or:
(.venv)$ cliffdemo --help
Run the simple
command by passing its name as argument to cliffdemo
.
(.venv)$ cliffdemo simple
The simple
command prints this output to the console:
sending greeting
hi!
To see help for an individual command, use the help
command:
(.venv)$ cliffdemo help files
or the --help
option:
(.venv)$ cliffdemo files --help
The Source¶
The cliffdemo
application is defined in a cliffdemo
package
containing several modules.
main.py¶
The main application is defined in main.py
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | import sys
from cliff.app import App
from cliff.commandmanager import CommandManager
class DemoApp(App):
def __init__(self):
super(DemoApp, self).__init__(
description='cliff demo app',
version='0.1',
command_manager=CommandManager('cliff.demo'),
deferred_help=True,
)
def initialize_app(self, argv):
self.LOG.debug('initialize_app')
def prepare_to_run_command(self, cmd):
self.LOG.debug('prepare_to_run_command %s', cmd.__class__.__name__)
def clean_up(self, cmd, result, err):
self.LOG.debug('clean_up %s', cmd.__class__.__name__)
if err:
self.LOG.debug('got an error: %s', err)
def main(argv=sys.argv[1:]):
myapp = DemoApp()
return myapp.run(argv)
if __name__ == '__main__':
sys.exit(main(sys.argv[1:]))
|
The DemoApp
class inherits from App
and overrides
__init__()
to set the program description and version number. It
also passes a CommandManager
instance configured to look for
plugins in the cliff.demo
namespace.
The initialize_app()
method of DemoApp
will be invoked
after the main program arguments are parsed, but before any command
processing is performed and before the application enters interactive
mode. This hook is intended for opening connections to remote web
services, databases, etc. using arguments passed to the main
application.
The prepare_to_run_command()
method of DemoApp
will be
invoked after a command is identified, but before the command is given
its arguments and run. This hook is intended for pre-command
validation or setup that must be repeated and cannot be handled by
initialize_app()
.
The clean_up()
method of DemoApp
is invoked after a
command runs. If the command raised an exception, the exception object
is passed to clean_up()
. Otherwise the err
argument is
None
.
The main()
function defined in main.py
is registered as a
console script entry point so that DemoApp
can be run from
the command line (see the discussion of setup.py
below).
simple.py¶
Two commands are defined in simple.py
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | import logging
from cliff.command import Command
class Simple(Command):
"A simple command that prints a message."
log = logging.getLogger(__name__)
def take_action(self, parsed_args):
self.log.info('sending greeting')
self.log.debug('debugging')
self.app.stdout.write('hi!\n')
class Error(Command):
"Always raises an error"
log = logging.getLogger(__name__)
def take_action(self, parsed_args):
self.log.info('causing error')
raise RuntimeError('this is the expected exception')
|
Simple
demonstrates using logging to emit messages on the
console at different verbose levels.
(.venv)$ cliffdemo simple
sending greeting
hi!
(.venv)$ cliffdemo -v simple
prepare_to_run_command Simple
sending greeting
debugging
hi!
clean_up Simple
(.venv)$ cliffdemo -q simple
hi!
Error
always raises a RuntimeError
exception when it
is invoked, and can be used to experiment with the error handling
features of cliff.
(.venv)$ cliffdemo error
causing error
ERROR: this is the expected exception
(.venv)$ cliffdemo -v error
prepare_to_run_command Error
causing error
ERROR: this is the expected exception
clean_up Error
got an error: this is the expected exception
(.venv)$ cliffdemo --debug error
causing error
this is the expected exception
Traceback (most recent call last):
File ".../cliff/app.py", line 218, in run_subcommand
result = cmd.run(parsed_args)
File ".../cliff/command.py", line 43, in run
self.take_action(parsed_args)
File ".../demoapp/cliffdemo/simple.py", line 24, in take_action
raise RuntimeError('this is the expected exception')
RuntimeError: this is the expected exception
Traceback (most recent call last):
File "/Users/dhellmann/Envs/cliff/bin/cliffdemo", line 9, in <module>
load_entry_point('cliffdemo==0.1', 'console_scripts', 'cliffdemo')()
File ".../demoapp/cliffdemo/main.py", line 33, in main
return myapp.run(argv)
File ".../cliff/app.py", line 160, in run
result = self.run_subcommand(remainder)
File ".../cliff/app.py", line 218, in run_subcommand
result = cmd.run(parsed_args)
File ".../cliff/command.py", line 43, in run
self.take_action(parsed_args)
File ".../demoapp/cliffdemo/simple.py", line 24, in take_action
raise RuntimeError('this is the expected exception')
RuntimeError: this is the expected exception
list.py¶
list.py
includes a single command derived from
cliff.lister.Lister
which prints a list of the files in the
current directory.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | import logging
import os
from cliff.lister import Lister
class Files(Lister):
"""Show a list of files in the current directory.
The file name and size are printed by default.
"""
log = logging.getLogger(__name__)
def take_action(self, parsed_args):
return (('Name', 'Size'),
((n, os.stat(n).st_size) for n in os.listdir('.'))
)
|
Files
prepares the data, and Lister
manages the
output formatter and printing the data to the console.
(.venv)$ cliffdemo files
+---------------+------+
| Name | Size |
+---------------+------+
| build | 136 |
| cliffdemo.log | 2546 |
| Makefile | 5569 |
| source | 408 |
+---------------+------+
(.venv)$ cliffdemo files -f csv
"Name","Size"
"build",136
"cliffdemo.log",2690
"Makefile",5569
"source",408
show.py¶
show.py
includes a single command derived from
cliff.show.ShowOne
which prints the properties of the named
file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 | import logging
import os
from cliff.show import ShowOne
class File(ShowOne):
"Show details about a file"
log = logging.getLogger(__name__)
def get_parser(self, prog_name):
parser = super(File, self).get_parser(prog_name)
parser.add_argument('filename', nargs='?', default='.')
return parser
def take_action(self, parsed_args):
stat_data = os.stat(parsed_args.filename)
columns = ('Name',
'Size',
'UID',
'GID',
'Modified Time',
)
data = (parsed_args.filename,
stat_data.st_size,
stat_data.st_uid,
stat_data.st_gid,
stat_data.st_mtime,
)
return (columns, data)
|
File
prepares the data, and ShowOne
manages the
output formatter and printing the data to the console.
(.venv)$ cliffdemo file setup.py
+---------------+--------------+
| Field | Value |
+---------------+--------------+
| Name | setup.py |
| Size | 5825 |
| UID | 502 |
| GID | 20 |
| Modified Time | 1335569964.0 |
+---------------+--------------+
setup.py¶
The demo application is packaged using setuptools.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 | #!/usr/bin/env python
PROJECT = 'cliffdemo'
# Change docs/sphinx/conf.py too!
VERSION = '0.1'
from setuptools import setup, find_packages
try:
long_description = open('README.rst', 'rt').read()
except IOError:
long_description = ''
setup(
name=PROJECT,
version=VERSION,
description='Demo app for cliff',
long_description=long_description,
author='Doug Hellmann',
author_email='doug.hellmann@gmail.com',
url='https://github.com/openstack/cliff',
download_url='https://github.com/openstack/cliff/tarball/master',
classifiers=['Development Status :: 3 - Alpha',
'License :: OSI Approved :: Apache Software License',
'Programming Language :: Python',
'Programming Language :: Python :: 2',
'Programming Language :: Python :: 2.7',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.2',
'Intended Audience :: Developers',
'Environment :: Console',
],
platforms=['Any'],
scripts=[],
provides=[],
install_requires=['cliff'],
namespace_packages=[],
packages=find_packages(),
include_package_data=True,
entry_points={
'console_scripts': [
'cliffdemo = cliffdemo.main:main'
],
'cliff.demo': [
'simple = cliffdemo.simple:Simple',
'two_part = cliffdemo.simple:Simple',
'error = cliffdemo.simple:Error',
'list files = cliffdemo.list:Files',
'files = cliffdemo.list:Files',
'file = cliffdemo.show:File',
'show file = cliffdemo.show:File',
'unicode = cliffdemo.encoding:Encoding',
'hooked = cliffdemo.hook:Hooked',
],
'cliff.demo.hooked': [
'sample-hook = cliffdemo.hook:Hook',
],
},
zip_safe=False,
)
|
The important parts of the packaging instructions are the
entry_points
settings. All of the commands are registered in the
cliff.demo
namespace. Each main program should define its own
command namespace so that it only loads the command plugins that it
should be managing.
Command Extension Hooks¶
Individual subcommands of an application can be extended via hooks
registered as separate plugins. In the demo application, the
hooked
command has a single extension registered.
The namespace for hooks is a combination of the application namespace
and the command name. In this case, the application namespace is
cliff.demo
and the command is hooked
, so the extension
namespace is cliff.demo.hooked
. If the subcommand name includes
spaces, they are replaced with underscores (“_
”) to build the
namespace.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 | # All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import logging
from cliff.command import Command
from cliff.hooks import CommandHook
class Hooked(Command):
"A command to demonstrate how the hooks work"
log = logging.getLogger(__name__)
def take_action(self, parsed_args):
self.app.stdout.write('this command has an extension\n')
class Hook(CommandHook):
"""Hook sample for the 'hooked' command.
This would normally be provided by a separate package from the
main application, but is included in the demo app for simplicity.
"""
def get_parser(self, parser):
print('sample hook get_parser()')
parser.add_argument('--added-by-hook')
return parser
def get_epilog(self):
return 'extension epilog text'
def before(self, parsed_args):
self.cmd.app.stdout.write('before\n')
def after(self, parsed_args, return_code):
self.cmd.app.stdout.write('after\n')
|
Although the hooked
command does not add any arguments to the
parser it creates, the help output shows that the extension adds a
single --added-by-hook
option.
(.venv)$ cliffdemo hooked -h
sample hook get_parser()
usage: cliffdemo hooked [-h] [--added-by-hook ADDED_BY_HOOK]
A command to demonstrate how the hooks work
optional arguments:
-h, --help show this help message and exit
--added-by-hook ADDED_BY_HOOK
extension epilog text
(.venv)$ cliffdemo hooked
sample hook get_parser()
before
this command has an extension
after
See also
cliff.hooks.CommandHook
– The API for command hooks.