Declarative Parser

Modern, declarative argument parser for Python 3.6+. Powerful like click, integrated like argparse, declarative as sqlalchemy. MIT licenced. Documented on RTD. Install with:

python3 -m pip install declarative_parser

As simple as argparse

It's built on top of argparse - everything you already know stays valid!

from declarative_parser import Parser, Argument

class MyParser(Parser):
    square = Argument(help='display a square of a given number')

parser = MyParser()
args = parser.parse_args()
print(args.square**2)

Nested and Parallel

Everyone knows about nested args. What about parallel groups?

supported_formats = ['png', 'jpeg', 'gif']

class InputOptions(Parser):
    path = Argument(type=argparse.FileType('rb'), optional=False)
    format = Argument(default='png', choices=supported_formats)

class OutputOptions(Parser):
    format = Argument(default='jpeg', choices=supported_formats)
    scale = Argument(type=int, default=100, help='Rescale image to %% of original size')

class ImageConverter(Parser):
    description = 'This app converts images'

    verbose = Argument(action='store_true')
    input = InputOptions()
    output = OutputOptions()

parser = ImageConverter()

commands = '--verbose input image.png output --format gif --scale 50'.split()

namespace = parser.parse_args(commands)

assert namespace.input.format == 'png'
assert namespace.output.format == 'gif'

Intelligent

Make use of Python 3 type hints to reduce tedious task of parsers writing to two or three lines. Positional, keyword arguments, type hints, docstrings - everything can be meaningfully transformed into a parser. And if you decide to take control, just overwrite the automatically deduced arguments with an Argument() defined as a class variable.

import argparse
from declarative_parser import Argument
from declarative_parser.constructor_parser import ConstructorParser

class MyProgram:

    database = Argument(
        type=argparse.FileType('r'),
        help='Path to file with the database'
    )

    def __init__(self, text: str, threshold: float=0.05, database=None):
        """My program does XYZ.

        Arguments:
          threshold: a floating-point value defining threshold, default 0.05
          database: file object to the database if any
        """
        print(text, threshold, None)

parser = ConstructorParser(MyProgram)

options = parser.parse_args()
program = parser.constructor(**vars(options))

And it works quite intuitively:

$ ./my_program.py test --threshold 0.6
test 0.6 None
$ ./my_program.py test --threshold f
usage: my_program.py [-h] [--database DATABASE] [--threshold THRESHOLD] text {} ...
my_program.py: error: argument --threshold: invalid float value: 'f'
$ ./my_program.py --threshold 0.6
usage: my_program.py [-h] [--database DATABASE] [--threshold THRESHOLD] text {} ...
my_program.py: error: the following arguments are required: text

Three docstring formats are supported: Google, NumPy and reStructuredText, with the default being Google.

PS. It works with functions too; see the documentation of FunctionParser.

Practical

What if you only want to show licence of your program? or version? Is there a need to write a separate logic? DeclarativeParser gives you utility decorator: @action which utilizes the power of argparse.Action, leaving behind the otherwise necessary boilerplate code.

__version__ = 2.0

import argparse
from declarative_parser import action
from declarative_parser.constructor_parser import ConstructorParser

class MyProgram:

    def __init__(self, threshold: float=0.05):
        """My program does XYZ.

        Arguments:
          threshold: a floating-point value, default 0.05
        """
        pass

    @action
    def version(options):
       print(__version__)

parser = ConstructorParser(MyProgram)

options = parser.parse_args()
program = parser.constructor(**vars(options))

The execution of an action will (by default) cause the program to exit immediately when finished.

See following run as example:

$ ./my_program.py --version
2.0

See more examples in the documentation.

Alternative ClassParsers

First of all, great project.

I would like to understand if it's possible to specify a "either this or that" for parsers.
That is, something similar to the choices argument parameter, but for parsers instead.

Here is my attempt at doing that:

from declarative_parser import Parser
from declarative_parser.constructor_parser import ClassParser


class A:
    def __init__(self, a='a'):
        self.a = a


class B:
    def __init__(self, b='b'):
        self.b = b


class MainParser(Parser):
    a = ClassParser(A)
    b = ClassParser(B)


if __name__ == '__main__':
    parser = MainParser()
    namespace = parser.parse_args()
    print(namespace)

I am aware this doesn't implement exclusion (you could specify a and b), but doing it in this way would be good enough for me (trust the user).

I expected this to happen:

$ python run.py a
Namespace(a=Namespace(a='a'), b=None)

and then I could check if a or b existed and figure out which the user chose.

However, this is the output I get:

$ python run.py a
Namespace(a=None, b=None)

So, the arguments aren't being loaded.
When an argument is mandatory, it actually works as intended, but I wanted that for some classes all the arguments were optional.

Is this something that can be done?

krassowski / declarative-parser Goto Github PK