From c24a956a01fbbb3b60e7c32d584c1e1d2b9c4abe Mon Sep 17 00:00:00 2001 From: Lucretiel Date: Mon, 16 Mar 2015 11:49:50 -0400 Subject: [PATCH 1/3] Fixes to README Fixed incorrect example in "Testing and Library Use" Fixed some typos and spelling issues Added section for the parser kwarg --- README.rst | 60 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 8 deletions(-) diff --git a/README.rst b/README.rst index 7d40ab9..4848a6d 100644 --- a/README.rst +++ b/README.rst @@ -312,6 +312,54 @@ Autocommand automatically follows wrapper chains created by ``@functools.wraps`` Even though autocommand is being applied to the ``wrapper`` returned by ``print_yielded``, it still retreives the signature of the underlying ``seq`` function to create the argument parsing. +Custom Parser +~~~~~~~~~~~~~ + +While autocommand's automatic parser generator is a powerful convenience, it doesn't cover all of the different features that argparse provides. If you need these features, you can provide your own parser as a kwarg to `autocommand`: + +.. code:: python + + from argparse import ArgumentParser + from autocommand import autocommand + + parser = ArgumentParser() + # autocommand can't do optional positonal parameters + parser.add_argument('arg', nargs='?') + # or mutually exclusive options + group = parser.add_mutually_exclusive_group() + group.add_argument('-v', '--verbose', action='store_true') + group.add_argument('-q', '--quiet', action='store_true') + + @autocommand(__name__, parser=parser) + def main(arg, verbose, quiet): + print(arg, verbose, quiet) + +:: + + $ python parser.py -h + usage: write_file.py [-h] [-v | -q] [arg] + + positional arguments: + arg + + optional arguments: + -h, --help show this help message and exit + -v, --verbose + -q, --quiet + $ python parser.py + None False False + $ python parser.py hello + hello False False + $ python parser.py -v + None True False + $ python parser.py -q + None False True + $ python parser.py -vq + usage: parser.py [-h] [-v | -q] [arg] + parser.py: error: argument -q/--quiet: not allowed with argument -v/--verbose + +Any parser should work fine, so long as each of the parser's arguments has a corresponding parameter in the decorated main function. The order of parameters doesn't matter, as long as they are all present. Note that when using a custom parser, autocommand doesn't modify the parser or the retrieved arguments. This means that no description/epilog will be added, and the function's type annotations and defaults (if present) will be ignored. + Testing and Library use ----------------------- @@ -328,8 +376,7 @@ The decorated function is only called and exited from if the first argument to ` return 0 - # Note that argv[0] must be included. - print(test_prog('test', '-v', 'hello', '80')) + print(test_prog(['-v', 'hello', '80'])) :: @@ -338,12 +385,10 @@ The decorated function is only called and exited from if the first argument to ` LOUD NOISES 0 -If the function is called with no arguments, ``sys.argv[1:]`` is used. This is to allow the autocommand function to be used as a setuptools entry ppint. +If the function is called with no arguments, ``sys.argv[1:]`` is used. This is to allow the autocommand function to be used as a setuptools entry point. -Features, notes, and limitations --------------------------------- - -- ``autocommand`` also supports a ``parser`` kwarg. If it is given, that parser object is used instead of one being generated on from the function signature. This allows you to use a more elaborate parser, with features that aren't supported by the automation system in ``autocommand``. The parser's argument names (as returned by ``parse_args``) should match up with the function's parameter names, though the order doesn't matter. +Exceptions and limitations +-------------------------- - There are a few possible exceptions that ``autocommand`` can raise. All of them derive from ``autocommand.AutocommandError``, which is a ``TypeError``. @@ -367,4 +412,3 @@ Autocommand cannot be important from the project root; this is to enforce separa $ python setup.py develop This will create a link to the source files in the deployment directory, so that any source changes are reflected when it is imported. - From 46fcc3139fd148857c49139b1f808fe9f208df9d Mon Sep 17 00:00:00 2001 From: Lucretiel Date: Mon, 16 Mar 2015 11:54:10 -0400 Subject: [PATCH 2/3] Bump setup.py version --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index 844d9d0..4cf16e4 100644 --- a/setup.py +++ b/setup.py @@ -7,7 +7,7 @@ def getfile(filename): setup( name='autocommand', - version='2.0.0', + version='2.0.1', py_modules=['autocommand'], package_dir={'': 'src'}, platforms='any', From ebe8c900af0a2768650ff758fa71d6b689b770ff Mon Sep 17 00:00:00 2001 From: Lucretiel Date: Mon, 16 Mar 2015 11:54:32 -0400 Subject: [PATCH 3/3] Bump autocommand.py version --- src/autocommand.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/autocommand.py b/src/autocommand.py index 04d6ba0..a489da2 100644 --- a/src/autocommand.py +++ b/src/autocommand.py @@ -22,7 +22,7 @@ from io import IOBase -__version__ = '2.0.0' +__version__ = '2.0.1' _empty = Parameter.empty