Skip to main content

A package to help automatically create command-line interface from configuration or code.

Project description

config-argument-parser

PyPI version Downloads Codacy Badge Maintainability codecov Documentation Status

A package to help automatically create command-line interface from configuration or code.

It contains three modules CAP🧢(ConfigArgumentParser), TAP🚰(TypeArgumentParser), and GAP🕳️(GlobalArgumentParser).

Read the documentation here.

Motivation

Configuration files are highly readable and useful for specifying options, but sometimes they are not convenient as command-line interface. However, it requires writing a lot of code to produce a CLI. This package automates the building process, by utilizing the Python standard libraries configparser and argparse.

The design is to minimize the changes to your original scripts, so as to facilitate maintenance.

Features

  • Only few extra lines are needed to build a CLI from an existing script.
  • The comments are parsed as help messages. (Most libraries do not preserve the comments.)
  • Consistent format between configuration and script provides ease of use.

Usage

Case 1: create CLI from an object

If you use class to store arguments, such as the script example.py below.

import configargparser

class Args:
    # Help message of the first argument. Help is optional.
    a_string = "abc"
    a_float = 1.23  # inline comments are omitted
    # Help can span multiple lines.
    # This is another line.
    a_boolean = False
    an_integer = 0

args = Args()

parser = configargparser.ConfigArgumentParser()
parser.parse_obj(args, shorts="sfb")

print(args.a_string)
print(args.a_float)
print(args.a_boolean)
print(args.an_integer)

In fact, only the snippet below is added to the original script. Moreover, removing this minimal modification does not affect the original script. shorts is optional. If provided, add short options for the first few arguments in order.

import configargparser
parser = configargparser.ConfigArgumentParser()
parser.parse_obj(args)

Default arguments are defined as class attributes, and parsed arguments are stored as instance attributes. The good is that auto-completion can be triggered in editors.

Show help, python example.py -h:

$ python example.py -h
usage: example.py [-h] [-s A_STRING] [-f A_FLOAT] [-b] [--an-integer AN_INTEGER]

options:
  -h, --help            show this help message and exit
  -s A_STRING, --a-string A_STRING
                        Help message of the first argument. Help is optional. (default: abc)
  -f A_FLOAT, --a-float A_FLOAT
                        a_float (default: 1.23)
  -b, --a-boolean       Help can span multiple lines. This is another line. (default: False)
  --an-integer AN_INTEGER
                        an_integer (default: 0)

Run with options, for example, python example.py -b -f 1:

$ python example.py -b -f 1
abc
1.0
True
0

Note that the values are changed.

For the best practice, see Case 4.

Case 2: create CLI from configuration

If you use configuration file, create an example script example.py:

import configargparser

parser = configargparser.ConfigArgumentParser()
parser.read("config.ini")
parser.parse_args(shorts="sfb")

print("Configs:", parser.defaults)
print("Args:   ", parser.args)

Create a configuration file config.ini in the same directory:

[DEFAULT]
# Help message of the first argument. Help is optional.
a_string = 'abc'
a_float = 1.23  # inline comments are omitted
# Help can span multiple lines.
# This is another line.
a_boolean = False
an_integer = 0

Regular run, python example.py:

$ python example.py
Configs: {'a_string': 'abc', 'a_float': 1.23, 'a_boolean': False, 'an_integer': 0}
Args:    {'a_string': 'abc', 'a_float': 1.23, 'a_boolean': False, 'an_integer': 0}

Run with options, such as python example.py -b -f 1:

$ python example.py -b -f 1
Configs: {'a_string': 'abc', 'a_float': 1.23, 'a_boolean': False, 'an_integer': 0}
Args:    {'a_string': 'abc', 'a_float': 1.0, 'a_boolean': True, 'an_integer': 0}

Case 3: create CLI from global variables

If you use global variables, define the variables at top of file as the script example.py below:

# [DEFAULT]
# Help message of the first argument. Help is optional.
a_string = "abc"
a_float = 1.23  # inline comments are omitted
# Help can span multiple lines.
# This is another line.
a_boolean = False
an_integer = 0
# [END]

import configargparser

parser = configargparser.ConfigArgumentParser()
parser.read_py("example.py")
parser.parse_args(shorts="sfb")

# update global variables
globals().update(parser.args)
print(a_string)
print(a_float)
print(a_boolean)
print(an_integer)

Use it as in case 1. For example, python example.py -b -f 1:

$ python example.py -b -f 1
abc
1.0
True
0

Case 4: create CLI from a dataclass object (preferred)

Suppose you have a script example.py below, which uses a dataclass object to store arguments:

from dataclasses import dataclass

@dataclass
class Args:
    # Help message of the first argument. Help is optional.
    a_string: str = "abc"
    a_float: float = 1.23  # inline comments are omitted
    # Help can span multiple lines.
    # This is another line.
    a_boolean: bool = False
    an_integer: int = 0

args = Args()

Add these lines to the script to create CLI:

import configargparser
parser = configargparser.TypeArgumentParser()
parser.parse_obj(args, shorts="sfb")

print(args)

Use it as in case 1. For example, python example.py -b -f 1 to change the values:

$ python example.py -b -f 1
Args(a_string='abc', a_float=1.0, a_boolean=True, an_integer=0)

Case 5: create CLI from global variables (without comments)

This requires less code than case 3, but the comments are not parsed, as the script example.py below:

a_string = "abc"
a_float = 1.23
a_boolean = False
an_integer = 0

import configargparser

parser = configargparser.GlobalArgumentParser()
parser.parse_globals(shorts="sfb")

print(a_string)
print(a_float)
print(a_boolean)
print(an_integer)

Use it as in case 1. For example, python example.py -b -f 1:

$ python example.py -b -f 1
abc
1.0
True
0

Installation

Install from PyPI:

python -m pip install --upgrade pip
pip install config-argument-parser

Alternatively, install from source:

git clone https://github.com/yuanx749/config-argument-parser.git
cd config-argument-parser

then install in development mode:

git checkout main
python -m pip install --upgrade pip
pip install -e .

or:

git checkout dev
python -m pip install --upgrade pip
pip install -e .[dev]
pre-commit install

Uninstall:

pip uninstall config-argument-parser

Notes

This package uses Semantic Versioning.

Project details


Download files

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

Source Distribution

config_argument_parser-1.5.0.tar.gz (8.2 kB view details)

Uploaded Source

Built Distribution

config_argument_parser-1.5.0-py3-none-any.whl (9.2 kB view details)

Uploaded Python 3

File details

Details for the file config_argument_parser-1.5.0.tar.gz.

File metadata

File hashes

Hashes for config_argument_parser-1.5.0.tar.gz
Algorithm Hash digest
SHA256 7e6ae74879a1150908c87a477290de65533caf8605ecb39a05f819f3c5ea582c
MD5 cf4735af3b2120478e2ebc776d2d1c61
BLAKE2b-256 ed61cd2fdc7a24eecb99a15ff0ef725428ee94e9b73ab9c6bde48f4a6e6096a0

See more details on using hashes here.

File details

Details for the file config_argument_parser-1.5.0-py3-none-any.whl.

File metadata

File hashes

Hashes for config_argument_parser-1.5.0-py3-none-any.whl
Algorithm Hash digest
SHA256 53df2580193e076c812db19792e6b96b32abd2aa67dde82c93ba2a54195e5c4f
MD5 631c693f2ac1905b3ecea44156bf1a30
BLAKE2b-256 83c9751ebae9e3c3fa46f18016505f8892058a59796d927a5e0757c79faefd7c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page