Argumentor

Command and argument parsing and documentation for Python CLI.

_{^{Feel free to contribute if you find any issues though.}}

Install

PyPi project

Install using pip

• $ pip install argumentor-gardehal
• from Argumentor import *

Install from files locally

• $ cd [path to this folder]
• $ pip cache purge (may help if old packages are cached)
• $ pip install .

Example

Getting started

Creating a command to calculate volume for a given object we have stored somewhere with an ID.

• ExampleBasic.py
• $ python .\tests\ExampleBasic.py -help

A step further

Creating a command that takes multiple inputs, validating dimensions, and a optional argument with custom casting and validation from string to an enum.

• ExampleAdvanced.py
• $ python .\tests\ExampleAdvanced.py -help

Expected outcomes

The following list of examples explains some expected outcomes, or could be used to test Argumentor. Note: These are based on ExampleAdvanced.py.

# Note, depending on CLI, these results may vary compared to validateString version as below, or as input into CLI (using ' or " would be a main reason as CLI reads it differently)

inputA = "-dim 1 2 3" # Valid
inputB = "-d a b c" # Invalid, a b c cannot be cast to ints unless you create a custom cast function
inputC = "-d width:4 d:5 h:6" # Valid
inputD = "-d w:7 8 d:9" # Valid, note the order: width, then unnamed argument which will be resolved to height because width and depth are named with an alias, then depth
inputE = "-d w:10 11 12" # Valid
inputF = "-d w:13 d:'-14' h:-15" # Invalid, validateInt function does not allow negative values (-14), and arguments (h:-15) starting with the command prefix (default "-") must be a named alias with quotation marks
inputG = "-d w:16 d:':17' h::18" # Invalid, the default int casting (':17') will fail, and arguments with colon ":" (h::18) must be a named alias or in quotation marks
inputH = "-test 19 20 21" # Invalid, command "test" does not exist and nothing will be returned from validate
inputI = "-d 22 24 25 --updateexternal" # Valid, flag --updateexternal will return a static value
inputJ = "-d 26 27 28 --nosuchflag" # Valid, but flag does not exist and reports this through Result.messages
inputK = "-d 29 30 31 ExternalVendorUpdateList:warehouse,default" # Valid, note that the string "warehouse,default" will be cast to a list of strings with these validated items
inputL = "-d 31 32 33 evul:notvalid" # Valid, but "notvalid" is not part of pre-approved ExternalVendorUpdateList items, validated in validateFunc, and results in a message

# Input as string
argResults = argumentor.validateString(inputA)

Recommendations

1. Use another, more complete argument parser library
2. See ExampleBasic.py and ExampleAdvanced.py for examples of usage.
3. Argumentor().validate() returns a list of Result with detected commands. Parse the result with this in mind:
   1. If the list is empty, no command-like input was detected.
   2. When populated, each Result will specify what command was hit by name and have a hitValue that was specified on init.
   3. If a command is detected but has errors, isValid will be false, and messages will details.
   4. Valid commands will have a dict of cast arguments ready to use.
4. Document your Commands, Arguments, and Flags using descriptions, provide a command (HELP/MAN) for users to see this. Access a printable description of commands through Argumentor().getFormattedDescription().
5. Arguments have fields for custom casting and validation functions (castFunc, validateFunc), the usage and limitations of these should be documented in descriptions.
6. Use arguments defaultValue and useDefaultValue to set a default or fallback in case casting or validating input from user fails. In some cases, a validation function is needed for applying default.
7. Static values can be set using a Flag, if the flag is present in input, the value set in Flag init will be in Result.arguments

TODO

• for description, some way to group commands or arguments to it can be printed with some sort of title? Makes it easier for walls of text, or maybe options to put something (newlines, "---") between all commands?
  • extra optional input for argumentor, dict[str, Command] where str is the "grouping"?
  • extra optional str to command, "grouping", with separate formatted print command that orders by grouping (sort groupings and commands how exactly?), with grouping header left/right args? e.g. "---- " + command.grouping + " ----"?
• guaranteed that multiple things can be improved in validate, both efficacy and readability
• set up github pipeline for testing and publish
  • get version through github release
  • add a cool badge with build status and version

Package Publish/update pip (just notes to publish this package on PyPI)

1. Install tools
   • python3 -m pip install --user --upgrade twine
   • python3 -m pip install --user --upgrade setuptools wheel
2. Build and publish (packages and versions appear in build folder)
   • python3 setup.py sdist bdist_wheel
   • python3 -m twine upload dist/*