Skip to main content

argparse wrapper to allow hierarchically nested class based parameters

Project description

Paramparse is a lightweight argparse wrapper to allow hierarchically nested class-based parameters suitable for automatic code analysis / intellisense in advanced IDEs like Pycharm.
It also provides a unified parameter specification protocol that can be used to provide parameter values through both text files and command line.

Note that this documentation, though still valid, has not been updated for a while and paramparse now has lots of advanced text file processing capabilities involving hierarchical named sections with templating and sequencing that are not documented here.

Please refer to the included parameter skeleton of a large multi object tracking project for which the functionality included in this package was originally developed. It provides an excellent example of a highly modular project with deeply nested and shared modules.

For example, this is one of the deeper instances of module nesting in this example:

Params->Trainer->Target->Templates->Siamese->SiamFC->DesignParams

Parameter for this configuration can be provided as:

trainer.target.templates.siamese.siamfc.design.exemplar_sz=150

Specifying multiple parameters for a deeply nested module can quickly become cumbersome especially from command line. The package thus provides a way to group parameters from the same module using the @ identifier. An example is provided in example/cfg/params.cfg. Note that the indentation used in this file is only for ease of human parsing and is not needed as this system of grouping also works from command line. Example commands are in example/commands.md.

The @ identifier specifies a prefix pf to be added to all subsequent arguments so that arg_name is then treated as pf.arg_name.
Assuming pf=arg1.arg2, following flavors of @ identifier usage are supported:

usage effect pf
@arg3 reset pf to arg3 arg3
@ reset pf to empty
@@arg3 add arg3 to pf arg1.arg2.arg3
@@@arg3 remove rightmost component of pf and add arg3 arg1.arg3
@@@ remove rightmost component of pf arg1

Usage of the package is very simple and involves calling paramparse.process as demonstrated in example/main.py.

It also provides three converter functions from_parser, from_dict and from_function that can create a parameter class compatible with this package from existing parameters in argparse.ArgumentParser and dict formats or using a function's keyword arguments respectively. The generated class code is either writen to a python source file whose name can be specified as the second argument (defaults to Params.py) or copied to clipboard if to_clipboard=1 is provided (requires pyperclip).

The process function does type inference from the default value of each param but also supports extracting the type from restructuredText/pycharm type docstring (as generated by the converter functions) if it is provided.

Note : paramparse uses the reserved parameter cfg to specify paths to text files containing parameter values. If an existing argparse or dict object to be converted into paramparse class already has a cfg field used for some other purpose, it will conflict with the parser so please rename this field before or after converting but before running paramparse.process.

Usage of converter functions is demonstrated in example/utils_demo.py

Run python3 main.py --h from the example folder to see the hierarchical help documentation generated by argparse.

Apart from the hierarchical nesting and parameter grouping, an important utility of paramparse is in the class based representation that allows automated code analysis, navigation and refactoring in IDEs like Pycharm that is not possible when using vanilla argparse.ArgumentParser or dict.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for paramparse, version 1.6.6
Filename, size File type Python version Upload date Hashes
Filename, size paramparse-1.6.6-py3-none-any.whl (36.7 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size paramparse-1.6.6.tar.gz (31.6 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page