Merge "doc: Cleanup of demoapp doc"

This commit is contained in:
Jenkins 2017-10-13 22:19:53 +00:00 committed by Gerrit Code Review
commit fe734d00da
1 changed files with 65 additions and 91 deletions

View File

@ -2,33 +2,27 @@
Exploring the Demo App
========================
The cliff source package includes a ``demoapp`` directory containing
an example main program with several command plugins.
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.
::
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)$
(.venv)$
Next, install cliff in the same environment.
::
Next, install cliff in the same environment::
(.venv)$ python setup.py install
Finally, install the demo application into the virtual environment.
::
Finally, install the demo application into the virtual environment::
(.venv)$ cd demoapp
(.venv)$ python setup.py install
@ -36,11 +30,10 @@ Finally, install the demo application into the virtual environment.
Usage
=====
Both cliff and the demo installed, you can now run the command
``cliffdemo``.
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::
For basic command usage instructions and a list of the commands available from
the plugins, run::
(.venv)$ cliffdemo -h
@ -48,15 +41,11 @@ or::
(.venv)$ cliffdemo --help
Run the ``simple`` command by passing its name as argument to ``cliffdemo``.
::
Run the ``simple`` command by passing its name as argument to ``cliffdemo``::
(.venv)$ cliffdemo simple
The ``simple`` command prints this output to the console:
::
The ``simple`` command prints this output to the console::
sending greeting
hi!
@ -75,8 +64,8 @@ For more information, refer to the autogenerated documentation :ref:`below
The Source
==========
The ``cliffdemo`` application is defined in a ``cliffdemo`` package
containing several modules.
The ``cliffdemo`` application is defined in a ``cliffdemo`` package containing
several modules.
main.py
-------
@ -87,31 +76,28 @@ The main application is defined in ``main.py``:
:linenos:
The :class:`DemoApp` class inherits from :class:`App` and overrides
:func:`__init__` to set the program description and version number. It
also passes a :class:`CommandManager` instance configured to look for
plugins in the ``cliff.demo`` namespace.
:func:`__init__` to set the program description and version number. It also
passes a :class:`CommandManager` instance configured to look for plugins in the
``cliff.demo`` namespace.
The :func:`initialize_app` method of :class:`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 :func:`initialize_app` method of :class:`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 :func:`prepare_to_run_command` method of :class:`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
:func:`initialize_app`.
The :func:`prepare_to_run_command` method of :class:`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 :func:`initialize_app`.
The :func:`clean_up` method of :class:`DemoApp` is invoked after a
command runs. If the command raised an exception, the exception object
is passed to :func:`clean_up`. Otherwise the ``err`` argument is
``None``.
The :func:`clean_up` method of :class:`DemoApp` is invoked after a command
runs. If the command raised an exception, the exception object is passed to
:func:`clean_up`. Otherwise the ``err`` argument is ``None``.
The :func:`main` function defined in ``main.py`` is registered as a
console script entry point so that :class:`DemoApp` can be run from
the command line (see the discussion of ``setup.py`` below).
The :func:`main` function defined in ``main.py`` is registered as a console
script entry point so that :class:`DemoApp` can be run from the command line
(see the discussion of ``setup.py`` below).
simple.py
---------
@ -121,11 +107,9 @@ Two commands are defined in ``simple.py``:
.. literalinclude:: ../../../demoapp/cliffdemo/simple.py
:linenos:
:class:`Simple` demonstrates using logging to emit messages on the
console at different verbose levels.
:class:`Simple` demonstrates using logging to emit messages on the console at
different verbose levels::
::
(.venv)$ cliffdemo simple
sending greeting
hi!
@ -140,23 +124,21 @@ console at different verbose levels.
(.venv)$ cliffdemo -q simple
hi!
:class:`Error` always raises a :class:`RuntimeError` exception when it
is invoked, and can be used to experiment with the error handling
features of cliff.
:class:`Error` always raises a :class:`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
@ -188,18 +170,15 @@ features of cliff.
list.py
-------
``list.py`` includes a single command derived from
:class:`cliff.lister.Lister` which prints a list of the files in the
current directory.
``list.py`` includes a single command derived from :class:`cliff.lister.Lister`
which prints a list of the files in the current directory.
.. literalinclude:: ../../../demoapp/cliffdemo/list.py
:linenos:
:class:`Files` prepares the data, and :class:`Lister` manages the
output formatter and printing the data to the console.
:class:`Files` prepares the data, and :class:`Lister` manages the output
formatter and printing the data to the console::
::
(.venv)$ cliffdemo files
+---------------+------+
| Name | Size |
@ -209,7 +188,7 @@ output formatter and printing the data to the console.
| Makefile | 5569 |
| source | 408 |
+---------------+------+
(.venv)$ cliffdemo files -f csv
"Name","Size"
"build",136
@ -222,17 +201,14 @@ output formatter and printing the data to the console.
show.py
-------
``show.py`` includes a single command derived from
:class:`cliff.show.ShowOne` which prints the properties of the named
file.
``show.py`` includes a single command derived from :class:`cliff.show.ShowOne`
which prints the properties of the named file.
.. literalinclude:: ../../../demoapp/cliffdemo/show.py
:linenos:
:class:`File` prepares the data, and :class:`ShowOne` manages the
output formatter and printing the data to the console.
::
:class:`File` prepares the data, and :class:`ShowOne` manages the output
formatter and printing the data to the console::
(.venv)$ cliffdemo file setup.py
+---------------+--------------+
@ -253,32 +229,30 @@ The demo application is packaged using setuptools.
.. literalinclude:: ../../../demoapp/setup.py
:linenos:
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.
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.
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.
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.
.. literalinclude:: ../../../demoapp/cliffdemo/hook.py
:linenos:
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.
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.
::