diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/requirements.txt | 2 | ||||
-rw-r--r-- | docs/source/classes.rst | 63 | ||||
-rw-r--r-- | docs/source/conf.py | 15 | ||||
-rw-r--r-- | docs/source/demoapp.rst | 258 | ||||
-rw-r--r-- | docs/source/developers.rst | 34 | ||||
-rw-r--r-- | docs/source/history.rst | 57 | ||||
-rw-r--r-- | docs/source/index.rst | 16 | ||||
-rw-r--r-- | docs/source/install.rst | 18 | ||||
-rw-r--r-- | docs/source/interactive_mode.rst | 94 | ||||
-rw-r--r-- | docs/source/introduction.rst | 60 | ||||
-rw-r--r-- | docs/source/list_commands.rst | 85 | ||||
-rw-r--r-- | docs/source/show_commands.rst | 76 |
12 files changed, 51 insertions, 727 deletions
diff --git a/docs/requirements.txt b/docs/requirements.txt deleted file mode 100644 index 6f01983..0000000 --- a/docs/requirements.txt +++ /dev/null @@ -1,2 +0,0 @@ -httplib2==0.7.4 -prettytable==0.5 diff --git a/docs/source/classes.rst b/docs/source/classes.rst deleted file mode 100644 index 14e80e9..0000000 --- a/docs/source/classes.rst +++ /dev/null @@ -1,63 +0,0 @@ -=============== - Cliff Classes -=============== - -Application -=========== - -App ---- - -.. autoclass:: cliff.app.App - :members: - -InteractiveApp --------------- - -.. autoclass:: cliff.interactive.InteractiveApp - :members: - -CommandManager --------------- - -.. autoclass:: cliff.commandmanager.CommandManager - :members: - -Command -------- - -.. autoclass:: cliff.command.Command - :members: - -ShowOne -------- - -.. autoclass:: cliff.show.ShowOne - :members: - -Lister ------- - -.. autoclass:: cliff.lister.Lister - :members: - -Formatting Output -================= - -Formatter ---------- - -.. autoclass:: cliff.formatters.base.Formatter - :members: - -ListFormatter -------------- - -.. autoclass:: cliff.formatters.base.ListFormatter - :members: - -SingleFormatter ---------------- - -.. autoclass:: cliff.formatters.base.SingleFormatter - :members: diff --git a/docs/source/conf.py b/docs/source/conf.py index 9e4b98e..e0bf72a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,6 +11,7 @@ # All configuration values have a default; values that are commented out # serve to show the default. +import datetime import sys, os # If extensions (or modules to document with autodoc) are in another directory, @@ -40,8 +41,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'cliff' -copyright = u'2012, Doug Hellmann' +project = u'cliff-tablib' +copyright = u'%s, Doug Hellmann' % datetime.date.today().year # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -164,7 +165,7 @@ html_static_path = ['_static'] #html_file_suffix = None # Output file base name for HTML help builder. -htmlhelp_basename = 'cliffdoc' +htmlhelp_basename = 'cliff-tablibdoc' # -- Options for LaTeX output -------------------------------------------------- @@ -183,7 +184,7 @@ latex_elements = { # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'cliff.tex', u'cliff Documentation', + ('index', 'cliff-tablib.tex', u'cliff-tablibDocumentation', u'Doug Hellmann', 'manual'), ] @@ -213,7 +214,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', 'cliff', u'cliff Documentation', + ('index', 'cliff-tablib', u'cliff-tablib Documentation', [u'Doug Hellmann'], 1) ] @@ -227,8 +228,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - ('index', 'cliff', u'cliff Documentation', - u'Doug Hellmann', 'cliff', 'One line description of project.', + ('index', 'cliff-tablib', u'cliff-tablib Documentation', + u'Doug Hellmann', 'cliff-tablib', 'One line description of project.', 'Miscellaneous'), ] 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/ diff --git a/docs/source/developers.rst b/docs/source/developers.rst index 46b9808..539dfb1 100644 --- a/docs/source/developers.rst +++ b/docs/source/developers.rst @@ -2,23 +2,17 @@ For Developers ================ -If you would like to contribute to cliff directly, these instructions -should help you get started. Patches, bug reports, and feature -requests are all welcome through the `GitHub project -<https://github.com/dreamhost/cliff>`_. Contributions in the form of -patches or pull requests are easier to integrate and will receive -priority attention. - -.. note:: - - Before contributing new features to clif core, please consider - whether they should be implemented as an extension instead. The - architecture is highly pluggable precisely to keep the core small. +If you would like to contribute to cliff-tablib directly, these +instructions should help you get started. Patches, bug reports, and +feature requests are all welcome through the `GitHub project +<https://github.com/dreamhost/cliff-tablib>`_. Contributions in the +form of patches or pull requests are easier to integrate and will +receive priority attention. Building Documentation ====================== -The documentation for cliff is written in reStructuredText and +The documentation for cliff-tablib is written in reStructuredText and converted to HTML using Sphinx. The build itself is driven by make. You will need the following packages in order to build the docs: @@ -36,12 +30,12 @@ documentation:: loading pickled environment... done building [html]: targets for 1 source files that are out of date updating environment: 1 added, 1 changed, 0 removed - reading sources... [100%] index + reading sources... [100%] index looking for now-outdated files... none found pickling environment... done done preparing documents... done - writing output... [100%] index + writing output... [100%] index writing additional files... genindex search copying static files... done dumping search index... done @@ -49,17 +43,15 @@ documentation:: build succeeded, 2 warnings. Build finished. The HTML pages are in build/html. - + The output version of the documentation ends up in ``./docs/build/html`` inside your sandbox. Running Tests ============= -.. image:: https://secure.travis-ci.org/dhellmann/cliff.png?branch=master - -The test suite for clif uses tox_, which must be installed separately -(``pip install tox``). +The test suite for cliff-tablib uses tox_, which must be installed +separately (``pip install tox``). To run the tests under Python 2.7 and 3.2, run ``tox`` from the top level directory of the git repository. @@ -73,5 +65,3 @@ Add new tests by modifying an existing file or creating new script in the ``tests`` directory. .. _tox: http://codespeak.net/tox - -.. _developer-templates: diff --git a/docs/source/history.rst b/docs/source/history.rst index e391488..e8a39d1 100644 --- a/docs/source/history.rst +++ b/docs/source/history.rst @@ -4,59 +4,6 @@ 1.0 - - Add trailing newlines after output from tablib-based formatters - (JSON, YAML, and HTML). Contributed by Matt Joyce. - - Some :pep:`8` fixes. - - Refactor the API in :class:`Command` to add :func:`take_action` - and make :func:`run` a concrete method. Existing users should only - need to rename :func:`run()` to :func:`take_action()` since the - function signatures have not changed. - - In :class:`Lister` and :class:`ShowOne` use :func:`take_action` - instead of :func:`get_data`. + - Initial public release, created by pulling the tablib integration + out of cliff and repackaging it. -0.7 - - - Clean up interactive mode flag settting. - - Add support for Python 2.6, contributed by heavenshell. - - Fix multi-word commands in interactive mode. - -0.6 - - - Pass the non-global argument list to :func:`initialize_app` to be - used in initialization work. - -0.5.1 - - - Remove pinned version requirement for PrettyTable until the - OpenStack clients catch up to the API change. - -0.5 - - - Asking for help about a command by prefix lists all matching - commands. - - Add formatters for HTML, JSON, and YAML. - -0.4 - - - Add shell formatter for single objects. - - Add interactive mode. - - Expand documentation. - -0.3 - - - Add ShowOne base class for commands that show details about single - objects. - - Fix a problem with Lister when there is no data to be printed. - -0.2 - - - Incorporate changes from dtroyer to replace use of optparse in App - with argparse. - - Added "help" subcommand to replace ``--help`` option handling in - subcommands. - -0.1 - - - Initial public release. - - Included App, CommandManager, Lister, csv and table formatters, a - demo application, and basic documentation. diff --git a/docs/source/index.rst b/docs/source/index.rst index 0a13664..bf0ae2b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,10 +1,11 @@ -======================================================= - cliff -- Command Line Interface Formulation Framework -======================================================= +============================================= + cliff-tablib -- tablib Formatters for cliff +============================================= -cliff is a framework for building command line programs. It uses -plugins to define sub-commands, output formatters, and other -extensions. +cliff-tablib includes formatters to be used in applications based on +the cliff_ framework. + +.. _cliff: http://pypi.python.org/pypi/cliff Contents: @@ -12,11 +13,8 @@ Contents: :maxdepth: 2 introduction - demoapp list_commands show_commands - interactive_mode - classes install developers history diff --git a/docs/source/install.rst b/docs/source/install.rst index 1bd67d0..e985a4b 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -5,33 +5,33 @@ Python Versions =============== -cliff is being developed under Python 2.7 and tested with Python 3.2. +cliff-tablib is being developed under Python 2.7 and tested with Python 3.2. .. _install-basic: Basic Installation ================== -cliff should be installed into the same site-packages area where the -application and extensions are installed (either a virtualenv or the -global site-packages). You may need administrative privileges to do -that. The easiest way to install it is using pip_:: +cliff-tablib should be installed into the same site-packages area +where the application and extensions are installed (either a +virtualenv or the global site-packages). You may need administrative +privileges to do that. The easiest way to install it is using pip_:: - $ pip install cliff + $ pip install cliff-tablib or:: - $ sudo pip install cliff + $ sudo pip install cliff-tablib .. _pip: http://pypi.python.org/pypi/pip Source Code =========== -The source is hosted on github: https://github.com/dreamhost/cliff +The source is hosted on github: https://github.com/dreamhost/cliff-tablib Reporting Bugs ============== Please report bugs through the github project: -https://github.com/dreamhost/cliff/issues +https://github.com/dreamhost/cliff-tablib/issues diff --git a/docs/source/interactive_mode.rst b/docs/source/interactive_mode.rst deleted file mode 100644 index 519e89a..0000000 --- a/docs/source/interactive_mode.rst +++ /dev/null @@ -1,94 +0,0 @@ -================== - Interactive Mode -================== - -In addition to running single commands from the command line, cliff -supports an interactive mode in which the user is presented with a -separate command shell. All of the command plugins available from the -command line are automatically configured as commands within the -shell. - -Refer to the cmd2_ documentation for more details about features of -the shell. - -.. _cmd2: http://packages.python.org/cmd2/index.html - -.. todo:: Add details about configuring and interacting with the shell (copy from cmd2 docs) - -Example -======= - -The ``cliffdemo`` application enters interactive mode if no command is -specified on the command line. - -:: - - (.venv)$ cliffdemo - (cliffdemo) help - - Shell commands (type help <topic>): - =================================== - cmdenvironment edit hi l list pause r save shell show - ed help history li load py run set shortcuts - - Undocumented commands: - ====================== - EOF eof exit q quit - - Application commands (type help <topic>): - ========================================= - files help simple file error two part - -To obtain instructions for a built-in or application command, use the -``help`` command: - -:: - - (cliffdemo) help simple - usage: simple [-h] - - A simple command that prints a message. - - optional arguments: - -h, --help show this help message and exit - -The commands can be run, including options and arguments, as on the -regular command line: - -:: - - (cliffdemo) simple - sending greeting - hi! - (cliffdemo) files - +----------------------+-------+ - | Name | Size | - +----------------------+-------+ - | .git | 578 | - | .gitignore | 268 | - | .tox | 238 | - | .venv | 204 | - | announce.rst | 1015 | - | announce.rst~ | 708 | - | cliff | 884 | - | cliff.egg-info | 340 | - | cliffdemo.log | 2193 | - | cliffdemo.log.1 | 10225 | - | demoapp | 408 | - | dist | 136 | - | distribute_setup.py | 15285 | - | distribute_setup.pyc | 15196 | - | docs | 238 | - | LICENSE | 11358 | - | Makefile | 376 | - | Makefile~ | 94 | - | MANIFEST.in | 186 | - | MANIFEST.in~ | 344 | - | README.rst | 1063 | - | setup.py | 5855 | - | setup.py~ | 8128 | - | tests | 204 | - | tox.ini | 76 | - | tox.ini~ | 421 | - +----------------------+-------+ - (cliffdemo) diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index d9312b9..def96eb 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -4,61 +4,5 @@ The cliff framework is meant to be used to create multi-level commands such as subversion and git, where the main program handles some basic -argument parsing and then invokes a sub-command to do the work. - -Command Plugins -=============== - -Cliff takes advantage of Python's ability to load code dynamically to -allow the sub-commands of a main program to be implemented, packaged, -and distributed separately from the main program. This organization -provides a unified view of the command for *users*, while giving -developers the opportunity organize source code in any way they see -fit. - -Cliff Objects -============= - -Cliff is organized around four objects that are combined to create a -useful command line program. - -The Application ---------------- - -An :class:`cliff.app.App` is the main program that you run from the shell -command prompt. It is responsible for global operations that apply to -all of the commands, such as configuring logging and setting up I/O -streams. - -The CommandManager ------------------- - -The :class:`cliff.commandmanager.CommandManager` knows how to load -individual command plugins. The default implementation uses -`setuptools entry points`_ but any mechanism for loading commands can -be used by replacing the default :class:`CommandManager` when -instantiating an :class:`App`. - -The Command ------------ - -The :class:`cliff.command.Command` class is where the real work -happens. The rest of the framework is present to help the user -discover the command plugins and invoke them, and to provide runtime -support for those plugins. Each :class:`Command` subclass is -responsible for taking action based on instructions from the user. It -defines its own local argument parser (usually using argparse_) and a -:func:`take_action` method that does the appropriate work. - -The Interactive Application ---------------------------- - -The main program uses an :class:`cliff.interactive.InteractiveApp` -instance to provide a command-shell mode in which the user can type -multiple commands before the program exits. Many cliff-based -applications will be able to use the default implementation of -:class:`InteractiveApp` without subclassing it. - -.. _setuptools entry points: http://packages.python.org/distribute/setuptools.html - -.. _argparse: http://docs.python.org/library/argparse.html +argument parsing and then invokes a sub-command to do the work. This +package adds JSON, YAML, and HTML output formatters to those commands. diff --git a/docs/source/list_commands.rst b/docs/source/list_commands.rst index f76188b..62fbebb 100644 --- a/docs/source/list_commands.rst +++ b/docs/source/list_commands.rst @@ -1,50 +1,11 @@ -=============== - List Commands -=============== +======================== + List Output Formatters +======================== -One of the most common patterns with command line programs is the need -to print lists of data. cliff provides a base class for commands of -this type so that they only need to prepare the data, and the user can -choose from one of several output formatter plugins to see the list of -data in their preferred format. - -Lister -====== - -The :class:`cliff.lister.Lister` base class API extends -:class:`Command` to allow :func:`take_action` to return data to be -formatted using a user-selectable formatter. Subclasses should provide -a :func:`take_action` implementation that returns a two member tuple -containing a tuple with the names of the columns in the dataset and an -iterable that will yield the data to be output. See the description of -:ref:`the files command in the demoapp <demoapp-list>` for details. - -List Output Formatters -====================== - -cliff is delivered with two output formatters for list -commands. :class:`Lister` adds a command line switch to let the user -specify the formatter they want, so you don't have to do any extra -work in your application. - -csv ---- - -The ``csv`` formatter produces a comma-separated-values document as -output. CSV data can be imported into a database or spreadsheet for -further manipulation. - -:: - - (.venv)$ cliffdemo files -f csv - "Name","Size" - "build",136 - "cliffdemo.log",2690 - "Makefile",5569 - "source",408 +cliff-tablib delivers several new output formatters for list commands. html ----- +==== The ``html`` formatter uses tablib_ to produce HTML output as a table. @@ -69,39 +30,19 @@ The ``html`` formatter uses tablib_ to produce HTML output as a table. </table> json ----- +==== The ``json`` formatter uses tablib_ to produce JSON output. :: - + (.venv)$ cliffdemo files -f json [{"Name": "build", "Size": 136}, {"Name": "cliffdemo.log", "Size": 3461}, {"Name": "Makefile", "Size": 5569}, {"Name": "requirements.txt", "Size": 33}, {"Name": "source", "Size": 782}] -table ------ - -The ``table`` formatter uses PrettyTable_ to produce output formatted -for human consumption. - -.. _PrettyTable: http://code.google.com/p/prettytable/ - -:: - - (.venv)$ cliffdemo files - +---------------+------+ - | Name | Size | - +---------------+------+ - | build | 136 | - | cliffdemo.log | 2546 | - | Makefile | 5569 | - | source | 408 | - +---------------+------+ - yaml ----- +==== The ``yaml`` formatter uses tablib_ to produce YAML output as a sequence of mappings. @@ -115,14 +56,4 @@ sequence of mappings. - {Name: requirements.txt, Size: 33} - {Name: source, Size: 816} - -Creating Your Own Formatter ---------------------------- - -If the standard formatters do not meet your needs, you can bundle -another formatter with your program by subclassing from -:class:`cliff.formatters.base.ListFormatter` and registering the -plugin in the ``cliff.formatter.list`` namespace. - - .. _tablib: https://github.com/kennethreitz/tablib diff --git a/docs/source/show_commands.rst b/docs/source/show_commands.rst index e848960..661acec 100644 --- a/docs/source/show_commands.rst +++ b/docs/source/show_commands.rst @@ -1,27 +1,6 @@ -=============== - Show Commands -=============== - -One of the most common patterns with command line programs is the need -to print properties of objects. cliff provides a base class for -commands of this type so that they only need to prepare the data, and -the user can choose from one of several output formatter plugins to -see the data in their preferred format. - -ShowOne -======= - -The :class:`cliff.show.ShowOne` base class API extends -:class:`Command` to allow :func:`take_action` to return data to be -formatted using a user-selectable formatter. Subclasses should provide -a :func:`take_action` implementation that returns a two member tuple -containing a tuple with the names of the columns in the dataset and an -iterable that contains the data values associated with those -names. See the description of :ref:`the file command in the demoapp -<demoapp-show>` for details. - -Show Output Formatters -====================== +======================== + Show Output Formatters +======================== cliff is delivered with output formatters for show commands. :class:`ShowOne` adds a command line switch to let the user @@ -65,47 +44,6 @@ The ``json`` formatter uses tablib_ to produce JSON output. "Value": 6373}, {"Field": "UID", "Value": 527}, {"Field": "GID", "Value": 501}, {"Field": "Modified Time", "Value": 1336353173.0}] -shell ------ - -The ``shell`` formatter produces output that can be parsed directly by -a typical UNIX shell as variable assignments. This avoids extra -parsing overhead in shell scripts. - -:: - - (.venv)$ cliffdemo file -f shell setup.py - name="setup.py" - size="5916" - uid="527" - gid="501" - modified_time="1335655655.0" - - (.venv)$ eval "$(cliffdemo file -f shell --prefix example_ setup.py)" - (.venv)$ echo $example_size - 5916 - -table ------ - -The ``table`` formatter uses PrettyTable_ to produce output -formatted for human consumption. - -.. _PrettyTable: http://code.google.com/p/prettytable/ - -:: - - (.venv)$ cliffdemo file setup.py - +---------------+--------------+ - | Field | Value | - +---------------+--------------+ - | Name | setup.py | - | Size | 5825 | - | UID | 502 | - | GID | 20 | - | Modified Time | 1335569964.0 | - +---------------+--------------+ - yaml ---- @@ -121,13 +59,5 @@ sequence of mappings. - {Field: GID, Value: 501} - {Field: Modified Time, Value: 1336353173.0} -Creating Your Own Formatter ---------------------------- - -If the standard formatters do not meet your needs, you can bundle -another formatter with your program by subclassing from -:class:`cliff.formatters.base.ShowFormatter` and registering the -plugin in the ``cliff.formatter.show`` namespace. - .. _tablib: https://github.com/kennethreitz/tablib |