Metadata-Version: 1.1
Name: subparse
Version: 0.5.1
Summary: A command line helper library for extensible subcommands
Home-page: https://github.com/mmerickel/subparse
Author: Michael Merickel
Author-email: oss@m.merickel.org
License: MIT
Description: ========
        subparse
        ========
        
        A wrapper for argparse that provides decorator-based subcommand support.
        
        Commands can be defined separately from their actual main functions,
        enabling faster import times.
        
        Basic Usage
        ===========
        
        ::
        
            from subparse import CLI
        
            class MyApp(object):
                def __init__(self, args):
                    self.args = args
        
                def info(self, *msg):
                    if not self.args.quiet:
                        print('[info]', *msg)
        
            def context_factory(cli, args):
                return MyApp(args)
        
            def generic_options(parser):
                parser.add_argument('--quiet', action='store_true',
                                    help='turn of debugging')
        
            cli = CLI(version='0.0', context_factory=context_factory)
            cli.add_generic_options(generic_options)
        
            @cli.command(__name__ + ':foo_main')
            def foo(parser):
                """
                a short description ending in a period.
        
                a longer description
                """
                parser.add_argument('--bar', action='store_true',
                                    help='turn on bar')
        
            def foo_main(app, args):
                app.info('Hello World!')
        
            result = cli.run()
            sys.exit(result)
        
        Lazy Decorators
        ===============
        
        Commands can be defined lazily and picked up later. This removes ordering
        restrictions between the commands and the cli object.
        
        A module containing commands can be defined irrespective of the actual
        ``CLI`` instance:
        
        ::
        
            # myapp/info.py
        
            from subparse import command
        
            @command('myapp.info:foo_main')
            def foo(parser):
                """perform foo"""
        
        Later, when an instance of a ``CLI`` is created, the commands can be loaded
        and registered:
        
        ::
        
            cli = CLI()
            cli.load_commands('myapp.info')
        
        Entry Points
        ============
        
        Commands may also be defined in external modules and loaded via entry
        points.
        
        ::
        
            from subparse import cli
        
            cli = CLI()
            cli.load_commands_from_entry_point('myapp.commands')
        
        An extension application would then define the external module that should
        be searched for commands. Again this allows the commands themselves to be
        defined independently of the main functions, improving import speed.
        
        An extension package should define a module containing the supported
        commands:
        
        ::
        
            # barpkg/commands.py
        
            from subparse import command
        
            @command('barpkg.bar')
            def bar(parser):
                """perform bar"""
        
        The package should also define the function to be called for each command.
        Optionally in a separate module to avoid importing run-time dependencies
        during parsing:
        
        ::
        
            # barpkg/bar.py
        
            def main(app, args):
                pass
        
        The package can then broadcast the module ``barpkg.commands``
        containing the supported commands:
        
        ::
        
            [myapp.commands]
            barpkg = barpkg.commands
        
        Now when your extension package is installed the commands will automatically
        become available.
        
        Context Factory
        ===============
        
        The ``context_factory`` argument to the ``subparse.CLI`` allows for defining
        an object that is passed to all commands. This factory can also be a
        generator, allowing it to ``yield`` the context object and then cleanup
        after the command is complete. For example:
        
        ::
        
            import transaction
        
            def context_factory(cli, args):
                tm = transaction.TransactionManager(explicit=True)
                with tm:
                  yield tm
        
        In the above example the transaction manager is available to all subcommands
        and it can commit/abort based on whether the command raises an exception.
        
        
        0.5.1 (2019-03-08)
        ==================
        
        - Use the ``argparse.RawTextHelpFormatter`` formatter class.
        
        0.5 (2019-03-08)
        ================
        
        - Add Python 3.7 support.
        
        - Fix a deprecation warning coming from setuptools.
        
        - Conform more closely to PEP-257 for docstring parsing.
        
        - Modify how the help text is displayed using the
          ``argparse.RawDescriptionHelpFormatter`` formatter class.
        
        0.4 (2018-05-03)
        ================
        
        - Drop Python 2.6, 3.2 and 3.3 support.
        
        - Add Python 3.4, 3.5, 3.6 support.
        
        - Allow the ``context_factory`` to be a generator which yields the context.
          This allows the context to wrap the full lifecycle of the CLI.
        
        0.3.3 (2013-08-12)
        ==================
        
        No functional changes from 0.3.2.
        
        - Improve documentation.
        
        0.3.2 (2013-08-06)
        ==================
        
        - Add `CLI.run` API for simply executing the command line.
        
        0.3.1 (2013-08-06)
        ==================
        
        - Improve the help output.
        
        0.3 (2013-08-06)
        ================
        
        - Rename subcommands to commands in the API.
        
        0.2 (2013-08-06)
        ================
        
        - Underscores in function names are converted to dashes in their respective
          subcommand names.
        - Add `CLI.add_generic_options` API.
        - Add a new `help` subcommand, allowing for `myapp help foo`.
        - Allow relative imports in the subcommand specification.
        
        0.1 (2013-08-05)
        ================
        
        - Initial Commits
        
Keywords: argparse cli commandline subcommand
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
