--- a/docs/api.rst Tue Jul 28 23:59:08 2009 +0300
+++ b/docs/api.rst Fri Jul 31 09:37:17 2009 +0300
@@ -4,5 +4,6 @@
.. module:: finaloption
+.. _api-command:
.. autofunction:: command
.. autofunction:: dispatch
--- a/docs/changelog.rst Tue Jul 28 23:59:08 2009 +0300
+++ b/docs/changelog.rst Fri Jul 31 09:37:17 2009 +0300
@@ -1,6 +1,10 @@
Changelog
---------
+0.9.4
+~~~~~
+Ability to hide subcommands from help listing.
+
0.9.3
~~~~~
Minor fix for setup.py, to avoid troubles with installing when there is no docs
--- a/docs/index.rst Tue Jul 28 23:59:08 2009 +0300
+++ b/docs/index.rst Fri Jul 31 09:37:17 2009 +0300
@@ -31,7 +31,7 @@
- parsing arguments from sys.argv or custom strings
- converting from string to appropriate Python objects
- - generating help message
+ - help message generation
- positional and named arguments
- subcommands support
- short, clean and concise definitions
--- a/docs/overview.rst Tue Jul 28 23:59:08 2009 +0300
+++ b/docs/overview.rst Fri Jul 31 09:37:17 2009 +0300
@@ -96,8 +96,9 @@
Keys in this dictionary are subcommand names. You can add aliases for
subcommands, separating them with the ``|`` sign (of course, there can be few
-aliases). Marking command with preceding ``^`` means that this commands should
-be included in short help (more on that later).
+aliases). Marking command with preceding ``^`` means that this command should
+be included in short help, marking with preceding ``~`` means that this command
+should be removed from all command listings (more on that later).
Values here are tuples, consisting of 3 elements:
@@ -145,9 +146,9 @@
if __name__ == '__main__':
dispatch()
-Every ``@command`` stores information about decorated function in special global
-command table, which allows to call ``dispatch()`` without arguments.
-
+Every :ref:`@command <api-command>` stores information about decorated function in
+special global command table, which allows to call ``dispatch()`` without
+arguments.
Help generation
---------------
--- a/finaloption.py Tue Jul 28 23:59:08 2009 +0300
+++ b/finaloption.py Fri Jul 31 09:37:17 2009 +0300
@@ -19,7 +19,7 @@
# Public interface
# --------
-def command(options=None, usage=None, name=None, shortlist=False):
+def command(options=None, usage=None, name=None, shortlist=False, hide=False):
'''Decorator to mark function to be used for command line processing.
All arguments are optional:
@@ -32,7 +32,9 @@
- ``name``: used for multiple subcommands. Defaults to wrapped
function name
- ``shortlist``: if command should be included in shortlist. Used
- only for multiple subcommands
+ only with multiple subcommands
+ - ``hide``: if command should be hidden from help listing. Used only
+ with multiple subcommands, overrides ``shortlist``
'''
def wrapper(func):
# copy option list
@@ -44,8 +46,8 @@
name_ = name or func.__name__
usage_ = usage or guess_usage(func, options_)
- CMDTABLE[(shortlist and '^' or '') + name_] = (
- func, options_, usage_)
+ prefix = hide and '~' or (shortlist and '^' or '')
+ CMDTABLE[prefix + name_] = (func, options_, usage_)
def help_func(name=None):
return help_cmd(func, replace_name(usage_, sysname()), options_)
@@ -89,7 +91,7 @@
- ``args``: list of arguments, default: ``sys.argv[1:]``
- ``cmdtable``: dict of commands in format described below.
- If not supplied, functions decorated with ``@command`` will be used.
+ If not supplied, will use functions decorated with ``@command``.
- ``globalopts``: list of options which are applied to all
commands, if not supplied will contain ``--help`` option
@@ -97,10 +99,10 @@
{'name': (function, options, usage)}
- - ``name`` is the name used on command-line. Can containt
- aliases (separate them with ``|``) or pointer to the fact
- that this command should be displayed in short help (start
- name with ``^``)
+ - ``name`` is the name used on command-line. Can contain aliases
+ (separate them with ``|``), pointer to a fact that this command
+ should be displayed in short help (start name with ``^``), or to
+ a fact that this command should be hidden (start name with ``~``)
- ``function`` is the actual callable
- ``options`` is options list in format described in docs
- ``usage`` is the short string of usage
@@ -144,9 +146,11 @@
any(imap(lambda x: x.startswith('^'), cmdtable)))
for cmd, info in cmdtable.items():
+ if cmd.startswith('~'):
+ continue # do not display hidden commands
if shortlist and not cmd.startswith('^'):
continue # short help contains only marked commands
- cmd = cmd.lstrip('^')
+ cmd = cmd.lstrip('^~')
doc = info[0].__doc__ or '(no help text available)'
hlp[cmd] = doc.splitlines()[0].rstrip()
@@ -354,7 +358,7 @@
"""
choice = {}
for e in table.keys():
- aliases = e.lstrip("^").split("|")
+ aliases = e.lstrip("^~").split("|")
found = None
if cmd in aliases:
found = cmd
--- a/setup.py Tue Jul 28 23:59:08 2009 +0300
+++ b/setup.py Fri Jul 31 09:37:17 2009 +0300
@@ -19,6 +19,7 @@
name = 'finaloption',
description = 'command line parsing done right',
long_description = desc(),
+ license = 'BSD',
version = finaloption.__version__,
author = finaloption.__author__,
author_email = finaloption.__email__,
@@ -33,4 +34,5 @@
'Topic :: Software Development',
],
py_modules = ['finaloption'],
+ platforms='any',
)
--- a/test.py Tue Jul 28 23:59:08 2009 +0300
+++ b/test.py Fri Jul 31 09:37:17 2009 +0300
@@ -16,7 +16,7 @@
cplx_opts = [('p', 'pass', False, 'don\'t run the command'),
('', 'exit', 0, 'exit with supplied code (default: 0)')]
-@command(cplx_opts, usage='[-p] [--exit value] ...', name='complex')
+@command(cplx_opts, usage='[-p] [--exit value] ...', name='complex', hide=True)
def complex_(*args, **opts):
'''That's more complex command indented to do something