doc: Cleanup of demoapp doc
Wrap at a sane width and remove errant whitespace. Change-Id: I31fada44126d3a55b1045990c8bcd756093a508a
This commit is contained in:
parent
3e028aa340
commit
b6f87c443b
@ -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.
|
||||
|
||||
::
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user