diff options
Diffstat (limited to 'docs')
24 files changed, 36 insertions, 735 deletions
diff --git a/docs/conf.py b/docs/conf.py index f79d5b3c..1212a6e2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -62,7 +62,7 @@ author = 'Catherine Devlin and Todd Leonhardt' # The short X.Y version. version = '0.7' # The full version, including alpha/beta/rc tags. -release = '0.7.7' +release = '0.7.8' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/index.rst b/docs/index.rst index ae7ea300..8e8817b2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,10 +46,8 @@ Resources * cmd_ * `cmd2 project page`_ * `project bug tracker`_ -* `PyCon 2010 presentation <https://github.com/python-cmd2/cmd2/blob/master/docs/pycon2010/pycon2010.rst>`_, - *Easy Command-Line Applications with cmd and cmd2*: - :doc:`slides <pycon2010/pycon2010>`, - `video <http://pyvideo.org/pycon-us-2010/pycon-2010--easy-command-line-applications-with-c.html>`_ +* Florida PyCon 2017: `slides <https://docs.google.com/presentation/d/1LRmpfBt3V-pYQfgQHdczf16F3hcXmhK83tl77R6IJtE>`_ +* PyOhio 2011: `video <https://archive.org/details/pyvideo_541___pyohio-2011-interactive-command-line-interpreters-with-cmd-and-cmd2>`_ These docs will refer to ``App`` as your ``cmd2.Cmd`` subclass, and ``app`` as an instance of ``App``. Of diff --git a/docs/install.rst b/docs/install.rst index 1edba409..9e330c3c 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -107,6 +107,10 @@ the following Python packages are installed: * pyparsing * pyperclip +On Windows, there is an additional dependency: + + * pyreadline + Upgrading cmd2 -------------- diff --git a/docs/integrating.rst b/docs/integrating.rst index 32ab37e0..bcb9301c 100644 --- a/docs/integrating.rst +++ b/docs/integrating.rst @@ -46,10 +46,14 @@ code like the following:: # Do this within whatever event loop mechanism you wish to run a single command cmd_line_text = "help history" - app.onecmd_plus_hooks(cmd_line_text) + app.runcmds_plus_hooks([cmd_line_text]) app.postloop() +The **runcmds_plus_hooks()** method is a convenience method to run multiple commands via **onecmd_plus_hooks()**. It +properly deals with ``load`` commands which under the hood put commands in a FIFO queue as it reads them in from a +script file. + The **onecmd_plus_hooks()** method will do the following to execute a single ``cmd2`` command in a normal fashion: #. Parse the command line text @@ -70,4 +74,10 @@ several disadvantages, including: * Does not support transcript testing * Does not allow commands at invocation via command-line arguments +Here is a little more info on ``runcmds_plus_hooks``: + +.. automethod:: cmd2.Cmd.runcmds_plus_hooks + + + diff --git a/docs/pycon2010/akkad.png b/docs/pycon2010/akkad.png Binary files differdeleted file mode 100644 index 57799e97..00000000 --- a/docs/pycon2010/akkad.png +++ /dev/null diff --git a/docs/pycon2010/apple.jpg b/docs/pycon2010/apple.jpg Binary files differdeleted file mode 100644 index 2148af3b..00000000 --- a/docs/pycon2010/apple.jpg +++ /dev/null diff --git a/docs/pycon2010/hook.jpg b/docs/pycon2010/hook.jpg Binary files differdeleted file mode 100644 index 819370d0..00000000 --- a/docs/pycon2010/hook.jpg +++ /dev/null diff --git a/docs/pycon2010/pirate.py b/docs/pycon2010/pirate.py deleted file mode 100644 index bd8b5170..00000000 --- a/docs/pycon2010/pirate.py +++ /dev/null @@ -1,10 +0,0 @@ -# coding=utf-8 -from cmd import Cmd - - -class Pirate(Cmd): - pass - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate2.py b/docs/pycon2010/pirate2.py deleted file mode 100644 index 343f94ff..00000000 --- a/docs/pycon2010/pirate2.py +++ /dev/null @@ -1,24 +0,0 @@ -# coding=utf-8 -from cmd import Cmd - - -# using ``do_`` methods - -class Pirate(Cmd): - gold = 3 - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - print('Now we gots {0} doubloons' - .format(self.gold)) - - def do_drink(self, arg): - 'Drown your sorrrows in rrrum.' - self.gold -= 1 - print('Now we gots {0} doubloons' - .format(self.gold)) - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate3.py b/docs/pycon2010/pirate3.py deleted file mode 100644 index 46f26501..00000000 --- a/docs/pycon2010/pirate3.py +++ /dev/null @@ -1,30 +0,0 @@ -# coding=utf-8 -from cmd import Cmd - - -# using hook - -class Pirate(Cmd): - gold = 3 - initial_gold = gold - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - - def do_drink(self, arg): - 'Drown your sorrrows in rrrum.' - self.gold -= 1 - - def precmd(self, line): - self.initial_gold = self.gold - return line - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate4.py b/docs/pycon2010/pirate4.py deleted file mode 100644 index ae1e1f4b..00000000 --- a/docs/pycon2010/pirate4.py +++ /dev/null @@ -1,36 +0,0 @@ -# coding=utf-8 -from cmd import Cmd - - -# using arguments - -class Pirate(Cmd): - gold = 3 - initial_gold = gold - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - - def do_drink(self, arg): - '''Drown your sorrrows in rrrum. - - drink [n] - drink [n] barrel[s] o' rum.''' - try: - self.gold -= int(arg) - except: - if arg: - print('''What's "{0}"? I'll take rrrum.'''.format(arg)) - self.gold -= 1 - - def precmd(self, line): - self.initial_gold = self.gold - return line - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons'.format(self.gold)) - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate5.py b/docs/pycon2010/pirate5.py deleted file mode 100644 index 68da88a5..00000000 --- a/docs/pycon2010/pirate5.py +++ /dev/null @@ -1,45 +0,0 @@ -# coding=utf-8 -from cmd import Cmd - - -# quitting - -class Pirate(Cmd): - gold = 3 - initial_gold = gold - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - - def do_drink(self, arg): - '''Drown your sorrrows in rrrum. - - drink [n] - drink [n] barrel[s] o' rum.''' - try: - self.gold -= int(arg) - except: - if arg: - print('''What's "{0}"? I'll take rrrum.'''.format(arg)) - self.gold -= 1 - - def precmd(self, line): - self.initial_gold = self.gold - return line - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - if self.gold < 0: - print("Off to debtorrr's prison.") - stop = True - return stop - - def do_quit(self, arg): - print("Quiterrr!") - return True - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate6.py b/docs/pycon2010/pirate6.py deleted file mode 100644 index bd5f5fe2..00000000 --- a/docs/pycon2010/pirate6.py +++ /dev/null @@ -1,50 +0,0 @@ -# coding=utf-8 -from cmd2 import Cmd - - -# prompts and defaults - -class Pirate(Cmd): - gold = 3 - initial_gold = gold - prompt = 'arrr> ' - - def default(self, line): - print('What mean ye by "{0}"?' - .format(line)) - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - - def do_drink(self, arg): - '''Drown your sorrrows in rrrum. - - drink [n] - drink [n] barrel[s] o' rum.''' - try: - self.gold -= int(arg) - except: - if arg: - print('''What's "{0}"? I'll take rrrum.'''.format(arg)) - self.gold -= 1 - - def precmd(self, line): - self.initial_gold = self.gold - return line - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - if self.gold < 0: - print("Off to debtorrr's prison.") - stop = True - return stop - - def do_quit(self, arg): - print("Quiterrr!") - return True - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate7.py b/docs/pycon2010/pirate7.py deleted file mode 100644 index 799f73ed..00000000 --- a/docs/pycon2010/pirate7.py +++ /dev/null @@ -1,59 +0,0 @@ -# coding=utf-8 -from cmd2 import Cmd - - -# prompts and defaults - -class Pirate(Cmd): - gold = 3 - initial_gold = gold - prompt = 'arrr> ' - - def default(self, line): - print('What mean ye by "{0}"?'.format(line)) - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - - def do_drink(self, arg): - '''Drown your sorrrows in rrrum. - - drink [n] - drink [n] barrel[s] o' rum.''' - try: - self.gold -= int(arg) - except: - if arg: - print('''What's "{0}"? I'll take rrrum.'''.format(arg)) - self.gold -= 1 - - def precmd(self, line): - self.initial_gold = self.gold - return line - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - if self.gold < 0: - print("Off to debtorrr's prison.") - stop = True - return stop - - def do_quit(self, arg): - print("Quiterrr!") - return True - - default_to_shell = True - multilineCommands = ['sing'] - terminators = Cmd.terminators + ['...'] - songcolor = 'blue' - settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)' - Cmd.shortcuts.update({'~': 'sing'}) - - def do_sing(self, arg): - print(self.colorize(arg, self.songcolor)) - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pirate8.py b/docs/pycon2010/pirate8.py deleted file mode 100644 index 58b56208..00000000 --- a/docs/pycon2010/pirate8.py +++ /dev/null @@ -1,71 +0,0 @@ -# coding=utf-8 -from cmd2 import Cmd, options, make_option - - -# prompts and defaults - -class Pirate(Cmd): - gold = 3 - initial_gold = gold - prompt = 'arrr> ' - - def default(self, line): - print('What mean ye by "{0}"?'.format(line)) - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - - def do_drink(self, arg): - '''Drown your sorrrows in rrrum. - - drink [n] - drink [n] barrel[s] o' rum.''' - try: - self.gold -= int(arg) - except: - if arg: - print('''What's "{0}"? I'll take rrrum.'''.format(arg)) - self.gold -= 1 - - def precmd(self, line): - self.initial_gold = self.gold - return line - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - if self.gold < 0: - print("Off to debtorrr's prison.") - stop = True - return stop - - def do_quit(self, arg): - print("Quiterrr!") - return True - - default_to_shell = True - multilineCommands = ['sing'] - terminators = Cmd.terminators + ['...'] - songcolor = 'blue' - settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)' - Cmd.shortcuts.update({'~': 'sing'}) - - def do_sing(self, arg): - print(self.colorize(arg, self.songcolor)) - - @options([make_option('--ho', type='int', default=2, - help="How often to chant 'ho'"), - make_option('-c', '--commas', - action="store_true", - help="Intersperse commas")]) - def do_yo(self, arg, opts): - chant = ['yo'] + ['ho'] * opts.ho - separator = ', ' if opts.commas else ' ' - chant = separator.join(chant) - print('{0} and a bottle of {1}' - .format(chant, arg)) - - -pirate = Pirate() -pirate.cmdloop() diff --git a/docs/pycon2010/pycon2010.rst b/docs/pycon2010/pycon2010.rst deleted file mode 100644 index 6c3af676..00000000 --- a/docs/pycon2010/pycon2010.rst +++ /dev/null @@ -1,382 +0,0 @@ -================================================ -Easy command-line interpreters with cmd and cmd2 -================================================ - -:author: Catherine Devlin -:date: 2010-02-20 -:slides: http://pypi.python.org/pypi/cmd2 - -Web 2.0 -======= - -.. image:: web-2-0-logos.gif - :height: 350px - -But first... -============ - -.. image:: sargon.jpg - :height: 250px - -.. image:: akkad.png - :height: 250px - -Sargon the Great - Founder of Akkadian Empire - -.. twenty-third century BC - -In between -========== - -.. image:: apple.jpg - :height: 250px - -Command-Line Interface - Unlike the Akkadian Empire, - the CLI will never die. - -Defining CLI -============ - -Also known as - -- "Line-oriented command interpreter" -- "Command-line interface" -- "Shell" - -1. Accepts free text input at prompt -2. Outputs lines of text -3. (repeat) - -Examples -======== - -.. class:: big - - * Bash, Korn, zsh - * Python shell - * screen - * Zork - * SQL clients: psql, SQL*\Plus, mysql... - * ed - -.. ``ed`` proves that CLI is sometimes the wrong answer. - -!= Command Line Utilities -========================= - -.. class:: big - - (``ls``, ``grep``, ``ping``, etc.) - - 1. Accept arguments at invocation - 2. execute - 3. terminate - - Use ``sys.argv``, ``optparse`` - -!="Text User Interface" -======================= - -* Use entire (session) screen -* I/O is *not* line-by-line -* See ``curses``, ``urwid`` - -.. image:: urwid.png - :height: 250px - - -Decide your priorities -====================== - -.. image:: strategy.png - :height: 350px - -A ``cmd`` app: pirate.py -======================== - -:: - - from cmd import Cmd - - class Pirate(Cmd): - pass - - pirate = Pirate() - pirate.cmdloop() - -.. Nothing here... but history and help - -.. ctrl-r for bash-style history - -Fundamental prrrinciple -======================= - -.. class:: huge - - ``(Cmd) foo a b c`` - - becomes - - ``self.do_foo('a b c')`` - -``do_``-methods: pirate2.py -=========================== - -:: - - class Pirate(Cmd): - gold = 3 - def do_loot(self, arg): - 'Seize booty frrrom a passing ship.' - self.gold += 1 - print('Now we gots {0} doubloons' - .format(self.gold)) - def do_drink(self, arg): - 'Drown your sorrrows in rrrum.' - self.gold -= 1 - print('Now we gots {0} doubloons' - .format(self.gold)) - -.. do_methods; more help - -Hooks -===== - -.. image:: hook.jpg - :height: 250px - -:: - - self.preloop() - self.postloop() - self.precmd(line) - self.postcmd(stop, line) - -Hooks: pirate3.py -================= - -:: - - def do_loot(self, arg): - 'Seize booty from a passing ship.' - self.gold += 1 - def do_drink(self, arg): - 'Drown your sorrrows in rrrum.' - self.gold -= 1 - def precmd(self, line): - self.initial_gold = self.gold - return line - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - -Arguments: pirate4.py -===================== - -:: - - def do_drink(self, arg): - '''Drown your sorrrows in rrrum. - - drink [n] - drink [n] barrel[s] o' rum.''' - try: - self.gold -= int(arg) - except: - if arg: - print('''What's "{0}"? I'll take rrrum.''' - .format(arg)) - self.gold -= 1 - -quitting: pirate5.py -==================== - -:: - - def postcmd(self, stop, line): - if self.gold != self.initial_gold: - print('Now we gots {0} doubloons' - .format(self.gold)) - if self.gold < 0: - print("Off to debtorrr's prison.") - stop = True - return stop - def do_quit(self, arg): - print("Quiterrr!") - return True - -prompts, defaults: pirate6.py -============================= - -:: - - prompt = 'arrr> ' - def default(self, line): - print('What mean ye by "{0}"?' - .format(line)) - -Other CLI packages -================== - -.. class:: big - - * CmdLoop - * cly - * CMdO - * pycopia - * cmdlin - * cmd2 - -Demo -==== - -.. class:: huge - - Convert ``cmd`` app to ``cmd2`` - -cmd2 -==== - -.. image:: schematic.png - :height: 350px - -As you wish, Guido -================== - -.. class:: huge - - Python 3 compatible - -(um, mostly) - -Absolutely free -=============== - -Script files - -Commands at invocation - -Output redirection - -Python - -Transcript testing - -But wait, there's more -====================== - - * Abbreviated commands - * Shell commands - * Quitting - * Timing - * Echo - * Debug - -Minor changes: pirate7.py -========================= - -:: - - default_to_shell = True - multilineCommands = ['sing'] - terminators = Cmd.terminators + ['...'] - songcolor = 'blue' - settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)' - Cmd.shortcuts.update({'~': 'sing'}) - def do_sing(self, arg): - print(self.colorize(arg, self.songcolor)) - -Now how much would you pay? -=========================== - -options / flags - -Quiet (suppress feedback) - -BASH-style ``select`` - -Parsing: terminators, suffixes - -Options: pirate8.py -=================== - -:: - - @options([make_option('--ho', type='int', default=2, - help="How often to chant 'ho'"), - make_option('-c', '--commas', - action="store_true", - help="Intersperse commas")]) - def do_yo(self, arg, opts): - chant = ['yo'] + ['ho'] * opts.ho - separator = ', ' if opts.commas else ' ' - chant = separator.join(chant) - print('{0} and a bottle of {1}' - .format(chant, arg)) - -Serious example: sqlpython -========================== - -.. class:: big - - ``cmd``-based app by Luca Canali @ CERN - - Replacement for Oracle SQL\*Plus - - Now ``cmd2``-based; postgreSQL; MySQL - -File reporter -============= - -.. class:: huge - - Gather info: Python - - Store: postgresql - - Report: html - -fileutil.py -=========== - -:: - - import glob - import os.path - - for fullfilename in glob.glob('/home/cat/proj/cmd2/*.py'): - (dirpath, fname) = os.path.split(fullfilename) - stats = os.stat(fullfilename) - binds['path'] = dirpath - binds['name'] = fname - binds['bytes'] = stats.st_size - cmd("""INSERT INTO cat.files (path, name, bytes) - VALUES (%(path)s, %(name)s, %(bytes)s)""") - quit() - -sqlpython features -================== - -.. class:: big - - * from ``cmd2``: scripts, redirection, - py, etc. - * multiple connections - * UNIX: ls, cat, grep - * Special output - - -Thank you -========= - -.. class:: big - - http://pypi.python.org/pypi/cmd2 - - http://catherinedevlin.blogspot.com - - http://catherinedevlin.pythoneers.com - - diff --git a/docs/pycon2010/sargon.jpg b/docs/pycon2010/sargon.jpg Binary files differdeleted file mode 100644 index 5960f1e0..00000000 --- a/docs/pycon2010/sargon.jpg +++ /dev/null diff --git a/docs/pycon2010/schematic.png b/docs/pycon2010/schematic.png Binary files differdeleted file mode 100644 index d4b39092..00000000 --- a/docs/pycon2010/schematic.png +++ /dev/null diff --git a/docs/pycon2010/script.txt b/docs/pycon2010/script.txt deleted file mode 100644 index c638b1a7..00000000 --- a/docs/pycon2010/script.txt +++ /dev/null @@ -1,5 +0,0 @@ -loot -loot -drink /* arrr */ 2 # matey -drink chardonnay - diff --git a/docs/pycon2010/strategy.png b/docs/pycon2010/strategy.png Binary files differdeleted file mode 100644 index 7d6afdcd..00000000 --- a/docs/pycon2010/strategy.png +++ /dev/null diff --git a/docs/pycon2010/transcript.txt b/docs/pycon2010/transcript.txt deleted file mode 100644 index d00e44fc..00000000 --- a/docs/pycon2010/transcript.txt +++ /dev/null @@ -1,12 +0,0 @@ -arrr> loot -Now we gots 4 doubloons -arrr> loot -Now we gots 5 doubloons -arrr> drink 3 -Now we gots 2 doubloons -arrr> drink chardonnay -What's "chardonnay"? I'll take rrrum. -Now we gots 1 doubloons -arrr> quit -Quiterrr! - diff --git a/docs/pycon2010/urwid.png b/docs/pycon2010/urwid.png Binary files differdeleted file mode 100644 index c2b5a9bf..00000000 --- a/docs/pycon2010/urwid.png +++ /dev/null diff --git a/docs/pycon2010/web-2-0-logos.gif b/docs/pycon2010/web-2-0-logos.gif Binary files differdeleted file mode 100644 index 9d48e37d..00000000 --- a/docs/pycon2010/web-2-0-logos.gif +++ /dev/null diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst index 326db3f5..0a24651b 100644 --- a/docs/settingchanges.rst +++ b/docs/settingchanges.rst @@ -19,11 +19,11 @@ Whether or not you set ``case_insensitive``, *please do not* define command method names with any uppercase letters. ``cmd2`` expects all command methods to be lowercase. -Shortcuts -========= +Shortcuts (command aliases) +=========================== -Special-character shortcuts for common commands can make life more convenient for your -users. Shortcuts are used without a space separating them from their arguments, +Command aliases for long command names such as special-character shortcuts for common commands can make life more +convenient for your users. Shortcuts are used without a space separating them from their arguments, like ``!ls``. By default, the following shortcuts are defined: ``?`` @@ -42,7 +42,20 @@ To define more shortcuts, update the dict ``App.shortcuts`` with the {'shortcut': 'command_name'} (omit ``do_``):: class App(Cmd2): - Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'}) + def __init__(self): + # Make sure you update the shortcuts attribute before calling the super class __init__ + self.shortcuts.update({'*': 'sneeze', '~': 'squirm'}) + + # Make sure to call this super class __init__ after updating shortcuts + cmd2.Cmd.__init__(self) + +.. warning:: + + Command aliases needed to be created by updating the ``shortcuts`` dictionary attribute prior to calling the + ``cmd2.Cmd`` super class ``__init__()`` method. Moreover, that super class init method needs to be called after + updating the ``shortcuts`` attribute This warning applies in general to many other attributes which are not + settable at runtime such as ``commentGrammars``, ``multilineCommands``, etc. + Default to shell ================ |
