diff options
Diffstat (limited to 'docs/source/demoapp.rst')
| -rw-r--r-- | docs/source/demoapp.rst | 258 |
1 files changed, 0 insertions, 258 deletions
diff --git a/docs/source/demoapp.rst b/docs/source/demoapp.rst deleted file mode 100644 index 66e66cb..0000000 --- a/docs/source/demoapp.rst +++ /dev/null @@ -1,258 +0,0 @@ -======================== - 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 - -The Source -========== - -The ``cliffdemo`` application is defined in a ``cliffdemo`` package -containing several modules. - -main.py -------- - -The main application is defined in ``main.py``: - -.. literalinclude:: ../../demoapp/cliffdemo/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. - -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:`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). - -simple.py ---------- - -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. - -:: - - (.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! - -: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 - 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 - -.. _demoapp-list: - -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. - -.. 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. - -:: - - (.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 - -.. _demoapp-show: - -show.py -------- - -``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. - -:: - - (.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 distribute_, the modern -implementation of 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. - -.. _distribute: http://packages.python.org/distribute/ |