Metadata-Version: 1.1
Name: ruamel.std.argparse
Version: 0.3.2
Summary: Enhancements to argparse: extra actions, subparser aliases, smart formatter, a decorator based wrapper
Home-page: https://bitbucket.org/ruamel/argparse
Author: Anthon van der Neut
Author-email: a.van.der.neut@ruamel.eu
License: MIT license
Description: argparse extensions
        ===================
        
        This package provides extensions to argparse on two levels:
        
        - basic argparse extensions: default subparser, subparser aliases in
          2.X
        - additional actions that can be specified for add_argument
        - smart formatter that allows combination of defaults help formatting
          **and** raw desciptions
        - wrapper for argparse using decorators
        
        Extensions to basic argparse
        ----------------------------
        
        Insert the following to be able to specify `aliases
        <https://docs.python.org/3/library/argparse.html#sub-commands>`_ in
        subparser definitions in 2.6 and 2.7::
        
          from __future__ import print_function
          
          import sys
          from ruamel.std.argparse import ArgumentParser, SubParsersAction
          
          parser = ArgumentParser()
          if sys.version_info < (3,):  # add aliases support
              parser.register('action', 'parsers', SubParsersAction)
          subparsers = parser.add_subparsers()
          checkout = subparsers.add_parser('checkout', aliases=['co'])
          checkout.add_argument('foo')
          args = parser.parse_args(['co', 'bar'])
          print(args)
        
        .. example code aliases.py
        
        Resulting in::
        
          Namespace(foo='bar')
        
        
        .. example output aliases.py
        
        Additional actions
        ------------------
        
        CountAction
        +++++++++++
        
        Count up and down::
        
          from __future__ import print_function
          
          from ruamel.std.argparse import CountAction
          import argparse
          
          parser = argparse.ArgumentParser()
          parser.add_argument('--verbose', '-v', action=CountAction, const=1, nargs=0)
          parser.add_argument('--quiet', '-q', action=CountAction, dest='verbose',
                              const=-1, nargs=0)
          
          print(parser.parse_args("--verbose -v -q".split()))
        
        .. example code countaction.py
        
        results in::
        
          Namespace(verbose=1)
        
        
        .. example output countaction.py
        
        
        SplitAppend
        +++++++++++
        
        Append after splitting on "``,``". Running::
        
          from __future__ import print_function
          
          from ruamel.std.argparse import SplitAppendAction
          import argparse
          
          parser = argparse.ArgumentParser()
          parser.add_argument('-d', action=SplitAppendAction)
          
          print(parser.parse_args("-d ab -d cd -d kl -d mn".split()))
          print(parser.parse_args("-d ab,cd,kl,mn".split()))
          print(parser.parse_args("-d ab,cd -d kl,mn".split()))
        
        .. example code splitaction.py
        
        results in::
        
          Namespace(d=['ab', 'cd', 'kl', 'mn'])
          Namespace(d=['ab', 'cd', 'kl', 'mn'])
          Namespace(d=['ab', 'cd', 'kl', 'mn'])
        
        
        .. example output splitaction.py
        
        CheckSingleStoreAction
        ++++++++++++++++++++++
        
        Complain if the same option is called  multiple times::
        
          from __future__ import print_function
          
          from ruamel.std.argparse import CheckSingleStoreAction
          import argparse
          
          parser = argparse.ArgumentParser()
          parser.add_argument('--check', '-c', action=CheckSingleStoreAction, const=1,
                              nargs=0)
          
          print(parser.parse_args("--check -c".split()))
        
        .. example code checksingleaction.py
        
        results in::
        
          WARNING: previous optional argument "-c []" overwritten by "-c []"
          Namespace(check=[])
        
        
        .. example output checksingleaction.py
        
        Smart formatting
        ----------------
        
        You can only specify one formatter in standard argparse, so you cannot
        both have pre-formatted description. using
        RawDescriptionHelpFormatter,as well as default arguments with
        ArgumentDefaultsHelpFormatter.
        
        The ``SmartFormatter`` is a subclass of ``argparse.HelpFormatter`` and
        has the normal formatter as default. Help text can be marked at the
        beginning for variations in formatting:
        
        - ``R|..`` format raw, i.e. don't wrap and fill out, observer newline
        - ``*|..`` format a password help, never echo password defaults
        - ``D|..`` add defaults to **all** entries (that is why having ``*|``
          is important)
        
        The version string is formatted using _split_lines and preserves any
        line breaks in the version string.
        
        ::
        
          from __future__ import print_function
          
          from ruamel.std.argparse import SmartFormatter
          import argparse
          
          
          def exit(self, *args, **kw):
              pass
          
          argparse.ArgumentParser.exit = exit
          
          # the 'D|....' in the second pass triggers generating defaults for all entries,
          # while being smart about which one already have a %(default)s
          
          for index, log_s in enumerate(['log to file', 'D|log to file']):
              parser = argparse.ArgumentParser(formatter_class=SmartFormatter)
          
              parser.add_argument('--log', default='abc.log', help=log_s)
              parser.add_argument('--username',
                                  help='username to login with (default: %(default)s)')
              parser.add_argument('--password', help='*|password to use for login')
              parser.add_argument('--recursive', '-r', action='store_true',
                                  help="R|recurse into subdirectories \nto find files")
              parser.set_defaults(username='anthon', password="test123")
          
              if index > 0:
                  print('--------------------------------------\n')
              parser.parse_args(["--help"])
        
        .. example code smartformatter.py
        
        results in::
        
          usage: smartformatter.py [-h] [--log LOG] [--username USERNAME]
                                   [--password PASSWORD] [--recursive]
          
          optional arguments:
            -h, --help           show this help message and exit
            --log LOG            log to file
            --username USERNAME  username to login with (default: anthon)
            --password PASSWORD  password to use for login
            --recursive, -r      recurse into subdirectories 
                                 to find files
          --------------------------------------
          
          usage: smartformatter.py [-h] [--log LOG] [--username USERNAME]
                                   [--password PASSWORD] [--recursive]
          
          optional arguments:
            -h, --help           show this help message and exit
            --log LOG            log to file (default: abc.log)
            --username USERNAME  username to login with (default: anthon)
            --password PASSWORD  password to use for login (default: *******)
            --recursive, -r      recurse into subdirectories 
                                 to find files (default: False)
        
        
        .. example output smartformatter.py
        
        
        Wrapping argparse
        -----------------
        
        When using argparse with subparser, each of which have their own
        function ( using ``.set_defaults(func=function``) that can be called,
        there is a lot of repetitive code.
        
        An alternative is provided by the ``ProgramBase`` class that should be
        subclassed and the ``sub_parser``, ``option`` and ``version``
        decorators that can be applied to methods of that subclass.
        
        A typical use case is::
        
          from __future__ import print_function
          
          import sys
          import os
          
          from ruamel.std.argparse import ProgramBase, option, sub_parser, version, \
              SmartFormatter
          
          
          class TestCmd(ProgramBase):
              def __init__(self):
                  super(TestCmd, self).__init__(
                      formatter_class=SmartFormatter
                  )
          
              # you can put these on __init__, but subclassing TestCmd
              # will cause that to break
              @option('--quiet', '-q', help='suppress verbosity', action='store_true',
                      global_option=True)
              @version('version: 1.2.3')
              def _pb_init(self):
                  # special name for which attribs are included in help
                  pass
          
              def run(self):
                  if self._args.func:
                      return self._args.func()
          
              def parse_args(self, *args):
                  self._parse_args(*args)
          
              @sub_parser(help='specific help for readit')
              @option('--name', default='abc')
              def readit(self):
                  print('calling readit')
          
              @sub_parser('writeit', help='help for writeit')
              @option('--target')
              def other_name(self):
                  print('calling writeit')
          
          
          n = TestCmd()
          n.parse_args(['--help'])
          n.run()
        
        .. example code testcmd.py
        
        and output::
        
          usage: testcmd.py [-h] [--quiet] [--version] {readit,writeit} ...
          
          positional arguments:
            {readit,writeit}
              readit          specific help for readit
              writeit         help for writeit
          
          optional arguments:
            -h, --help        show this help message and exit
            --quiet, -q       suppress verbosity
            --version         show program's version number and exit
        
        
        .. example output testcmd.py
        
        
        
        The method name is by default the name of the sub_parser. This can be
        overriden by providing a non-keyword argument to ``sub_parser``. The
        keyword arguments are passed to the  ``add_parser`` method.
        
        The ``option`` functions as ``add_argument``. If ``option`` is put on
        a method that is not a sub_parser, such an option will be a global
        option. These have to be specified before any sub_parser argument when
        invoking the script. Often it is handy to specify such an option with
        an ``global_option=True`` keyword argument. This makes sure that
        option is added to all the sub_parsers as well. This allows you to
        invoke both ``prog --quiet writeit`` and ``prog writeit --quiet``).
        You can assing these options to ``__init__``, but when sub classing
        ``TestCmd`` this will lead to problems. It is therefore better to pu
        them on the special handled method ``_pb_init`` if subclassing might
        happen.
        
        Care should be taken that all attributes on ``TestCmd`` are accessed
        during scanning for sub parsers. In particular any property method 
        will be accessedi and its code executed.
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
