Skip to main content

Simple argument parser for documented functions

Project description

argParseFromDoc

A simple python package for creating/updating argparse ArgumentParser(s) given a type hinted and documented function.

Content

Installation

  • Option 1. Cloning this repository:
git clone https://github.com/rsanchezgarc/argParseFromDoc.git
cd argParseFromDoc
pip install .
  • Option 2. Installing with pip
pip install argParseFromDoc

Or if you want the latest update

pip install git+https://github.com/rsanchezgarc/argParseFromDoc

Quick overview

argParseFromDoc allows you to create argument parsers directly from the type hints and the docstring of a function. The most common use case of creating a parser for a main function and calling it can be implemented in 2 lines if you have previously documented your function

def add(a: int, b: int):
    '''
    @param a: first number. 
    @param b: second number.
    '''
    return a + b
    
if __name__ == "__main__":
    from argParseFromDoc import parse_function_and_call
    out = parse_function_and_call(add)
    print(out)

argParseFromDoc also support more advanced features via the class AutoArgumentParser and the function get_parser_from_function. See below for more details

Supported features

The following features are currently supported

  • Function argument types:
    • int, str, float and bool
    • (Homogeneous) Lists of any of the previous types (defined astyping.List[primitive_type])
    • Files (defined astyping.TextIO and typing.BinaryIO)
  • Ignoring/selecting a subset of the arguments of the function
    • Use myarg:typing.Optional[VALID_TYPE]=None to set it as not required parameter or args_optional=["myarg"]
  • Creating a new parser or adding new arguments to it. You can also use parser groups
  • Several docsctring formats (see docstring_parser )
  • Support for methods assuming first argument in definition is self

Assumptions

  • Positional arguments. Functions can have positional arguments, but the parser will consider all them as if they were keyword/optional (always --argname VALUE)
  • If no default value is provided for an argument in the function signature, argument will be considered as required (parser.add_argument(..., required=True)). The same applies to default=None except if the name of the argument is included in args_optional or it is declared as typing.Optional.
    E.g get_parser_from_function(..., args_optional=[name1, name2...])
  • Boolean arguments:
    • Boolean arguments must be provided with default value.
    • If a boolean argument defaults to False (name:bool=False), the parser sets the argument name=True if --name flag provided.
    • If a boolean argument defaults to True (name:bool=True), the parser sets the argument name=False if --NOT_name flag provided. Please notice that the name of the argument in the argument parser has been changed from name to --NOT_name to reflect that but the argument is stored using the original name, so no further changes in the code are required
  • Multiple arguments can be provided if using typing.List. For example: def fun(several_strings: List[str]):
  • Setting deafult values for typing.TextIO and typing.BinaryIO is not advisable, as they should be opened files. If you are only employing the function for the argument parser, you could default it to string values pointing files, but again, this is not encouraged. Instead, if you want to set a default filename, use type str. The main purpose of typing.TextIO and typing.BinaryIO in the parser is to allow pipes. For example:
    #These two commands are equivalent
    python count_lines --inputFile /etc/passwd 
    cat /etc/passwd | python count_lines --inputFile -
    
    
  • Methods, including __init__, are supported providing self is always used as the first argument in the definition
  • When defining functions, *arg and **kwargs are ignored for the parser. No other * or ** argument is supported.

Usage

You only need to document the type and possible default values for the arguments of your functions with typing and add the description of each within the docstring. Examples of documented functions are:

def add(a: int, b: int):
    '''
    @param a: first number. Mandatory
    @param b: second number. Mandatory
    '''
    return a + b
    
def printYourAge(age: int, name: str = "Unknown"):
    '''
    @param age: your age
    @param name: your name. This is optional
    '''
    return str(a) + " "+ b
    
def addList(several_nums: List[int], b: int=1):
    '''
    @param several_nums: first number
    @param b: second number
    '''
    return [a + b for a in several_nums]

Then, obtaining an ArgumentParser for any of these functions (say add) is as easy as:

if __name__ == "__main__":
    from argParseFromDoc import get_parser_from_function
    parser = get_parser_from_function(add)
    args = parser.parse_args()
    print(add(**vars(args)))

Or you can directly use the AutoArgumentParser class

if __name__ == "__main__":
    from argParseFromDoc import AutoArgumentParser
    parser = AutoArgumentParser()
    parser.add_args_from_function(add)

Finally, for convenience, you can create the parser, parse the argument and call the function in one line using

if __name__ == "__main__":
    from argParseFromDoc import parse_function_and_call
    out = parse_function_and_call(add)

If you want to add to a previously instantiated parser the arguements of the function, you just need to provide the original parser (or group) to the get_parser_from_function function.

if __name__ == "__main__":
    from argParseFromDoc import get_parser_from_function
    #standard ArgumentParser
    from argparse import ArgumentParser
    parser = ArgumentParser(prog="Add_example")
    parser.add_argument("--other_type_of_argument", type=str, default="Not provided")
    #####################################################
    # ### If you prefer a group instead of a whole parser
    # group = parser.add_argument_group()
    # get_parser_from_function(add, parser=group)
    #####################################################
    #provide the original parser to get_parser_from_function that will add the new options to the parser
    get_parser_from_function(add, parser=parser)
    args = parser.parse_args()
    print(add(**vars(args)))

Finally, if your function has some arguments that you do not want to include to the parser, you can use the args_to_ignore option. If you want to use only a subset, use the args_to_include option.

def manyArgsFun(a: int, b: int, c: int = 1, d: int = 2, e: str = "oneStr"):
    '''

    :param a: a
    :param b: b
    :param c: c
    :param d: d
    :param e: e
    :return:
    '''
    print(e)
    return sum([a, b, c, d])


if __name__ == "__main__":
    from argParseFromDoc import get_parser_from_function
    # parser = get_parser_from_function(manyArgsFun, args_to_ignore=["c", "d", "e"])
    parser = get_parser_from_function(manyArgsFun, args_to_include=["a", "b"])
    args = parser.parse_args()
    print(manyArgsFun(**vars(args)))

You can use argParseFromDoc with subparsers easily. For instance:

if __name__ == "__main__":
    from argParseFromDoc import AutoArgumentParser, get_parser_from_function
    parser = AutoArgumentParser("programName")

    subparsers = parser.add_subparsers(help='command: this is to select a command', required=True, dest='command')
    
    parser1 = subparsers.add_parser('command1_name', help='')
    get_parser_from_function(function1, parser=parser1)

    parser2 = subparsers.add_parser('command2_name', help='')
    get_parser_from_function(function2, parser=parser2)

    arguments = parser.parse_args()
    if arguments.command == "command1_name":
        del arguments.command
        function1(**vars(arguments))
    elif arguments.command == "command2_name":
        del arguments.command
        function2(**vars(arguments))
    else:
        raise ValueError(f"Command not valid {arguments.command}")

Some additional examples can be found in examples folder or in test_argParseFromDoc.py

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

argParseFromDoc-0.1.2.tar.gz (17.7 kB view details)

Uploaded Source

Built Distribution

argParseFromDoc-0.1.2-py3-none-any.whl (20.2 kB view details)

Uploaded Python 3

File details

Details for the file argParseFromDoc-0.1.2.tar.gz.

File metadata

  • Download URL: argParseFromDoc-0.1.2.tar.gz
  • Upload date:
  • Size: 17.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.18

File hashes

Hashes for argParseFromDoc-0.1.2.tar.gz
Algorithm Hash digest
SHA256 386adc080000ba8c39aa6c8417e2308946dca9566cc98b0a64c607c62f3a0c80
MD5 e7fa5df01dd9b5610cc09ba024af6dde
BLAKE2b-256 1af15f677c7274673df698041f71ea75c70a906102db96d913a51a8ce3d97738

See more details on using hashes here.

File details

Details for the file argParseFromDoc-0.1.2-py3-none-any.whl.

File metadata

File hashes

Hashes for argParseFromDoc-0.1.2-py3-none-any.whl
Algorithm Hash digest
SHA256 ca263970dd9f7a4283ee2daa923ec1b370451064bbcc20ebee63e8b4b6ffc633
MD5 6db120b25bb6808b679bfc13662423cc
BLAKE2b-256 740a5db62e9482551c0fb66fdb4bc4c7614f52581e0cb7d8e65a32944c97e13f

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