Metadata-Version: 2.1
Name: argparseware
Version: 0.9.8
Summary: argparseware middleware library
Home-page: https://github.com/relevance-io/argparseware
Author: Francis Lacroix
Author-email: f@relevance.io
Maintainer: Francis Lacroix
Maintainer-email: f@relevance.io
License: MIT
Description: # argparseware
        
        The **argparseware** library is a simple to use, extensible library that complements the
        `argparse` package from the standard library. It provides the same interfaces - with
        some additions - allowing developers to work quickly with tools they already know and
        are well documented, while promoting code reusability.
        
        More specifically, **argparseware** extends the default argument parser of `argparse`
        by providing a quick and clean interface to define and use middleware components for
        command-line applications, for such things as logging, loading configurations or
        serving WSGI applications.
        
        Its interface is reliant on `argparse` with only some minor additions to improve
        code reusability.
        
        ## Getting started
        
        ### Requirements
        
        These are the general requirements for using this package:
        
        - Python 3.6 or higher
        
        No other dependencies are required for the base package and interfaces to work.
        
        #### Optional dependencies
        
        Some bundled middleware require optional dependencies:
        
        - `ConfigMiddleware` requires `anyconfig`
        - `FlaskServerMiddleware` requires `flask`
        - `GunicornServerMiddleware` requires `gunicorn`
        - `GeventServerMiddleware` requires `gevent`
        
        ### Installation
        
        Since this is a standard Python package, install with:
        
        ```shell
        pip install argparseware
        ```
        
        #### Development mode
        
        Again, as this is a standard Python package, install in development (editable) mode with:
        
        ```shell
        pip install -e .
        ```
        
        ## Usage
        
        This package can be used the same way as you would `argparse`:
        
        ```python
        import argparseware
        
        parser = argparseware.ArgumentParser(
            prog='myprog',
            description='Some test program',
        )
        parser.add_argument('--arg', help='some arg')
        
        namespace = parser.parse_args()
        ```
        
        ...then run with:
        
        ```python
        python3 your-script.py --arg foo
        ```
        
        ### What is middleware?
        
        Where `argparseware` really shines is by using the bundled or custom middleware. Middleware
        have two phases: execution and configuration.
        
        Execution is the step that is executed after all arguments have been parsed. It is essentially
        a function that accepts the `Namespace` object from argparse as its first argument and does
        something with it:
        
        ```python
        parser = argparseware.ArgumentParser()
        parser.add_argument('--some-arg', 'some generic argument')
        
        @parser.middleware
        def my_middleware(args):
            print('some_arg value is:', args.some_arg)
        
        parser.run()
        ```
        
        It's useful for executing and reusing code that is run *after* the arguments are parsed.
        
        While it's pretty useful in itself, this is an argparse extension, so you probably will want
        to be able to define your own arguments:
        
        ```python
        parser = argparseware.ArgumentParser()
        
        @parser.middleware
        def my_middleware(args):
            print('some_arg value is:', args.some_arg)
        
        @my_middleware.configure
        def config_my_middleware(parser):
            parser.add_argument('--some-arg', help='some arg as a string')
        
        parser.run()
        ```
        
        The `configure` step is executed *before* the arguments are parsed, so this is where you'll
        want to add your custom arguments or perform validation on other defined arguments.
        
        This is the easiest form of middleware definition, but it doesn't stop there! Keep reading
        for more useful ways of using **argparseware**.
        
        ### Loading middleware
        
        If you already have existing middleware in a common library, or if you want to use
        some of the bundled middleware, for example, the logging middleware:
        
        ```python
        import argparseware
        from argparseware.common import LoggingMiddleware
        
        parser = argparseware.ArgumentParser()
        parser.add_middleware(LoggingMiddleware())
        parser.run()
        ```
        
        ...then run with:
        
        ```shell
        python3 your-script.py --verbose
        ```
        
        The above will automatically configure logging after the arguments are parsed.
        
        ### Defining middleware
        
        The easiest way to define your own reusable middleware component is to use the
        `middleware` decorator:
        
        ```python
        import argparseware
        
        @argparseware.middleware
        def my_middleware(args):
            print('some_arg value is "foo":', args.some_arg == 'foo')
        
        @my_middleware.configure
        def config_my_middleware(parser):
            parser.add_argument('--some-arg', 'some argument, try value: foo')
        
        parser = argparseware.ArgumentParser(prog='testprog')
        parser.add_middleware(my_middleware)
        parser.run()
        ```
        
        ### Complex middleware
        
        With some middleware, you'll want to be able to customize it and pass arguments
        to it. This can be done with the `IMiddleware` abstract class:
        
        ```
        from argparseware.core import IMiddleware
        
        class MyMiddleware(IMiddleware):
            def __init__(self, default_value):
                self.default_value = default_value
        
            def configure(self, parser):
                parser.add_argument('--some-arg', default=self.default, help='some arg')
        
            def run(self, args):
                print('you passed', args.some_arg, 'default was', self.default_value)
        
        parser = argparseware.ArgumentParser()
        parser.add_middleware(MyMiddleware(42))
        parser.run()
        ```
        
        ### Adapting existing codebases
        
        While it's great to have code reuse, sometimes you want the best of both worlds. In
        **argparseware**, the parser's `run` method returns the same thing as the argparse
        `parse_args` method would, so you can easily adapt existing code:
        
        ```python
        import argparseware
        from argparseware.common import LoggingMiddleware
        
        parser = argparseware.ArgumentParser()
        parser.add_argument('--test')
        parser.add_middleware(LoggingMiddleware())
        args = parser.run()
        
        if args.test == 'hello world':
            print('hello world')
        ```
        
        ## License
        
        This code and its documentation is provided under the MIT License, bundled as the `LICENSE`
        file. All original rights are reserved to Relevance.io 2020-.
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
Provides-Extra: config
Provides-Extra: wsgi
Provides-Extra: all
