jk_argparsing
=============
Introduction
------------
This module provides an API for processing command line arguments. There is ``argparse`` of course, but this API is better. Better means: Simpler, more easy to use.
Information about this module can be found here:
* [github.org](https://github.com/jkpubsrc/python-module-jk-argparsing)
* [pypi.python.org](https://pypi.python.org/pypi/jk_argparsing)
History
----------------------
Not every piece of software has a history. This module has.
Work on this module began over a decade ago in a complete different programming language: C#. As I required some command line tools in C# I implemented a .Net library for that purpose as there was nothing like that I could use. This library was so convenient that a) I prepared it for release under the Apache Open Source license and b) ported it to Python some years later.
So this python module here is based on that .Net library. It is basically a port of that library. However, year after year I improved that Python module bit by bit, so this Python module became a very convenient tool, way beyond the original capabilities of that .Net library.
The next sections provide detailed information about how to use `jk_argparsing`.
How to use this module
----------------------
## Import
To import this module use the following statement:
```python
import jk_argparsing
```
## Concept
First some short information about terminology used by this module:
* An *option* is something like `-h` or `-l` or `--help`. (e.g.: `ls -la`)
* A *command* is something like `update` or `install` or whatever. (e.g.: `apt update`)
NOTE: Command line parsing will follow these conceps (and only these concepts) listed above.
Using `jk_argparsing` is very simple:
* You first instantiate an object of `ArgsParser`.
* Then you define defaults in a data dictionary for your options.
* Then you configure this object by invoking methods on this object. By doing this you define ...
* the author(s) of your program
* the license your program will be using
* options, your program might require (together with expectations for arguments to provide)
* commands, your program might provide (together with expectations for arguments to provide)
* exit codes, your program might use
* various other information useful for a user
* After configuration is complete, you invoke `parse()` to initiate parsing of the command line specified by the user. In doing so ...
* program options are parsed and entries in your data dictionary will be modified in the process.
* An object of type `ParsedArgs` will now be returned.
* You can now use this returnes object to process the commands provided on the command line.
## Example
First, let's create an instance of `ArgsParser`:
```python
ap = ArgsParser(appName="myapp", shortAppDescription="My short description")
```
Then let's configure this object. The following is just an example of what you might want to do:
```python
ap.createSynopsis("myapp -x foo")
ap.createSynopsis("myapp -y bar")
ap.optionDataDefaults.set("help", False)
ap.createOption(None, "enabled", "Something is enabled.").expectString("OPT1", minLength = 2).onOption = \
lambda argOption, argOptionArguments, parsedArgs: \
parsedArgs.optionData.set("my", argOptionArguments[0])
ap.createOption("h", "help", "Display this help text.").onOption = \
lambda argOption, argOptionArguments, parsedArgs: \
parsedArgs.optionData.set("help", True)
ap.createOption("n", "nothing", LOREM_IPSUM)
ap.createAuthor("Jürgen Knauth", "jk@binary-overflow.de")
ap.setLicense("apache", YEAR = 2017, COPYRIGHTHOLDER = "Jürgen Knauth")
ap.createReturnCode(0, "Everything is okay.")
ap.createReturnCode(1, "An I/O error occurred.")
ap.createReturnCode(-1, "Invalid configuration.")
ap.createCommand("foo", "Lorem ipsum dolor sid amet.")
ap.createCommand("bar", "The quick brown fox jumps over the lazy dog.")
```
Now if you would generate a help text by invoking `ap.showHelp()` you would get this result:
```
myapp - My short description
SYNOPSIS
myapp -x foo
myapp -y bar
OPTIONS
--enabled OPT1 Something is enabled.
-h --help Display this help text.
-n --nothing Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse congue, orci vel interdum bibendum, nisi mauris
porttitor tortor, non tincidunt neque quam eget est. Vivamus sollicitudin urna ut elit lobortis, eget pretium est
sollicitudin. Vivamus venenatis ut erat quis gravida. Praesent vel purus finibus velit pretium eleifend.
COMMANDS
bar The quick brown fox jumps over the lazy dog.
foo Lorem ipsum dolor sid amet.
PROGRAM EXIT CODES
0 Everything is okay.
1 An I/O error occurred.
-1 Invalid configuration.
AUTHORS
Jürgen Knauth <jk@binary-overflow.de>
LICENSE
This program is free software: you can redistribute it and/or modify it under the terms of the Apache Software License as published by
Apache Software Foundation in version 2. For more details see the Apache Software License, which should be vailable at:
https://www.apache.org/licenses/LICENSE-2.0
```
## Adding a description
You might want to add a description. For better readability this description could have chapters:
```python
ap.addDescriptionChapter("Introduction", "Lorem ipsum dolor sid amet ...")
ap.addDescriptionChapter("Usage", "Lorem ipsum dolor sid amet ...")
ap.addDescriptionChapter("Whatever", "Lorem ipsum dolor sid amet ...")
```
A description is placed **after** the synopsis and **before** the options.
Additional methods are provided to insert text at some other position in the help text `jk_argparsing` will create for yoou:
* `addExtraChapterHead(..)`
* `addExtraChapterMiddle(..)`
* `addExtraChapterEnd(..)`
The full help text created will then have the following structure:
| Position | Description
| --- | ---
| A title | In this example here: "`myapp - My short description`"
| Synposis | Multiple lines defined by `createSynopsis(..)`
| A head text section | Defined by `addExtraChapterHead(..)`
| The standard description | Defined by `addDescriptionChapter(..)`
| A middle text section | Defined by `addExtraChapterMiddle(..)`
| Options | A formatted table with all options provided by `createOption(..)`
| Commands | A formatted table with all commands provided by `createCommand(..)`
| Program exit codes | A formatted table with all exit codes provided by `createReturnCode(..)`
| A final text section | Defined by `addExtraChapterEnd(..)`
| Authors | A list of all authors defined by `createAuthor(..)`
| License | A short license information defined by `setLicense(..)`
## Program options
For your program to support options your first step should be to provide default value(s) that can get modified later during parsing. Here we use `help` for demonstration purposes:
```python
ap.optionDataDefaults.set("help", False)
```
Then define the option so that the parser later will be able to process it:
```python
ap.createOption("h", "help", "Display this help text.").onOption = \
lambda argOption, argOptionArguments, parsedArgs: \
parsedArgs.optionData.set("help", True)
```
In this particular case the option will have no argument.
However, the option will have a lambda function that can be assigned to `onOption`. This lambda function will be executed if the parser encounteres this option.
The lambda function will receive three arguments:
* `argOption` - The option that is currently being parsed. (You typically have no use for this parameter as by attaching a lambda function you already know the option that is going to be parsed.)
* `argOptionArguments` - A list of arguments the option might have. (This list is empty in our case as `--help` does not have any additional arguments.)
* `parsedArgs` - The `ParsedArgs` object the parser is creating by parsing the command line on `ap.parse()`. (This `ParsedArgs` object will be returned later to the caller of `ap.parse()`.)
Within this lambda functions you should access `parsedArgs.optionData`. This is a dictionary you can modify. For simplicity invoke `set(..)` to modify a values.
In this example here the original value for `help` will be overwritten.
## Program commands
For your program to support commands you just define your command. Example:
```python
ap.createCommand("update", "Perform some kind of update.")
```
Of course you could have a command with an argument:
```python
ap.createCommand("process-file", "Load a settings file.") \
.expectFile("<settingsFile>", minLength=1, mustExist=True, toAbsolutePath=True)
```
Now if the user runs your program with arguments such as these ...
> `yourprogram process-file some/path/to/a/file`
... the parsing engine will check that a file path follows `process-file` that refers to an existing file. In addition this argument will converted to an absolute path automatically during parsing.
Processing such kind of program arguments in your program is simple. Here is an example:
```python
# parse the command line using our predefined object `ArgsParser` in `ap`
# NOTE: all options get processed automatically during this parsing step
parsedArgs = ap.parse()
if parsedArgs.optionData["help"]:
# `help` is true, so let's exit here
ap.showHelp()
sys.exit(1)
if not parsedArgs.programArgs:
# no program arguments specified, so let's exit here
ap.showHelp()
sys.exit(1)
for cmdName, cmdArgs in parsedArgs.parseCommands():
if cmdName == 'update':
# do somethig
...
elif cmdName == 'process-file':
# do somethig
...
else:
# fallback if - by accident - we have an error in our implementation here
raise Exception("Implementation error!")
```
## Expectations for options and commands
Options and commands can have "expections". An expectation is an argument a user must append to the option. Example:
> `yourprogram --output-file some/path/to/a/file do-something`
Or:
> `yourprogram process-file some/path/to/a/file`
Here ...
* `--output-file` would be an option that expects one argument,
* `do-something` would be a command that has no arguments and
* `process-file` would be a command that expects one argument.
Here is how you could define such a command:
```python
ap.createCommand("process-file", "Load a settings file.") \
.expectFile("<settingsFile>", minLength=1, mustExist=True, toAbsolutePath=True)
```
The following expectations for arguments to options and commands are available:
| Method to invoke | Description |
| --- | --- |
| `expectFileOrDirectory(..)` | Provided argument must be a file or directory |
| `expectFile(..)` | Provided argument must be a file |
| `expectDirectory(..)` | Provided argument must be a directory |
| `expectString(..)` | Provided argument must be a text string |
| `expectInt32(..)` | Provided argument must be an integer number |
NOTE: By definition `expectString(..)`, `expectFileOrDirectory(..)`, `expectFile(..)` and `expectDirectory(..)` are quite similar: They all specify that a string is expected. However, each method will support constraints. While `expectString(..)` only supports standard string constraints, the other methods will assume that the specified string denotes a file or directory.
Author(s)
-------------------
* Jürgen Knauth: pubsrc@binary-overflow.de
License
-------
This software is provided under the following license:
* Apache Software License 2.0
Raw data
{
"_id": null,
"home_page": "",
"name": "jk-argparsing",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "program,arguments,commands,options,args",
"author": "J\u00fcrgen Knauth",
"author_email": "pubsrc@binary-overflow.de",
"download_url": "https://files.pythonhosted.org/packages/48/c3/2bf46348846ca60fe144a187bf50b8e82b1341cdfe0e108334de01850906/jk_argparsing-0.2023.6.28.tar.gz",
"platform": null,
"description": "jk_argparsing\n=============\n\nIntroduction\n------------\n\nThis module provides an API for processing command line arguments. There is ``argparse`` of course, but this API is better. Better means: Simpler, more easy to use.\n\nInformation about this module can be found here:\n\n* [github.org](https://github.com/jkpubsrc/python-module-jk-argparsing)\n* [pypi.python.org](https://pypi.python.org/pypi/jk_argparsing)\n\nHistory\n----------------------\n\nNot every piece of software has a history. This module has.\n\nWork on this module began over a decade ago in a complete different programming language: C#. As I required some command line tools in C# I implemented a .Net library for that purpose as there was nothing like that I could use. This library was so convenient that a) I prepared it for release under the Apache Open Source license and b) ported it to Python some years later.\n\nSo this python module here is based on that .Net library. It is basically a port of that library. However, year after year I improved that Python module bit by bit, so this Python module became a very convenient tool, way beyond the original capabilities of that .Net library.\n\nThe next sections provide detailed information about how to use `jk_argparsing`.\n\nHow to use this module\n----------------------\n\n## Import\n\nTo import this module use the following statement:\n\n```python\nimport jk_argparsing\n```\n\n## Concept\n\nFirst some short information about terminology used by this module:\n\n* An *option* is something like `-h` or `-l` or `--help`. (e.g.: `ls -la`)\n* A *command* is something like `update` or `install` or whatever. (e.g.: `apt update`)\n\nNOTE: Command line parsing will follow these conceps (and only these concepts) listed above.\n\nUsing `jk_argparsing` is very simple:\n\n* You first instantiate an object of `ArgsParser`.\n* Then you define defaults in a data dictionary for your options.\n* Then you configure this object by invoking methods on this object. By doing this you define ...\n\t* the author(s) of your program\n\t* the license your program will be using\n\t* options, your program might require (together with expectations for arguments to provide)\n\t* commands, your program might provide (together with expectations for arguments to provide)\n\t* exit codes, your program might use\n\t* various other information useful for a user\n* After configuration is complete, you invoke `parse()` to initiate parsing of the command line specified by the user. In doing so ...\n\t* program options are parsed and entries in your data dictionary will be modified in the process.\n\t* An object of type `ParsedArgs` will now be returned.\n* You can now use this returnes object to process the commands provided on the command line.\n\n## Example\n\nFirst, let's create an instance of `ArgsParser`:\n\n```python\nap = ArgsParser(appName=\"myapp\", shortAppDescription=\"My short description\")\n```\n\nThen let's configure this object. The following is just an example of what you might want to do:\n\n```python\nap.createSynopsis(\"myapp -x foo\")\nap.createSynopsis(\"myapp -y bar\")\n\nap.optionDataDefaults.set(\"help\", False)\n\nap.createOption(None, \"enabled\", \"Something is enabled.\").expectString(\"OPT1\", minLength = 2).onOption = \\\n\tlambda argOption, argOptionArguments, parsedArgs: \\\n\t\tparsedArgs.optionData.set(\"my\", argOptionArguments[0])\nap.createOption(\"h\", \"help\", \"Display this help text.\").onOption = \\\n\tlambda argOption, argOptionArguments, parsedArgs: \\\n\t\tparsedArgs.optionData.set(\"help\", True)\nap.createOption(\"n\", \"nothing\", LOREM_IPSUM)\n\nap.createAuthor(\"J\u00fcrgen Knauth\", \"jk@binary-overflow.de\")\nap.setLicense(\"apache\", YEAR = 2017, COPYRIGHTHOLDER = \"J\u00fcrgen Knauth\")\n\nap.createReturnCode(0, \"Everything is okay.\")\nap.createReturnCode(1, \"An I/O error occurred.\")\nap.createReturnCode(-1, \"Invalid configuration.\")\n\nap.createCommand(\"foo\", \"Lorem ipsum dolor sid amet.\")\nap.createCommand(\"bar\", \"The quick brown fox jumps over the lazy dog.\")\n```\n\nNow if you would generate a help text by invoking `ap.showHelp()` you would get this result:\n\n```\nmyapp - My short description\n\nSYNOPSIS\n\n myapp -x foo\n myapp -y bar\n\nOPTIONS\n\n --enabled OPT1 Something is enabled.\n -h --help Display this help text.\n -n --nothing Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse congue, orci vel interdum bibendum, nisi mauris\n porttitor tortor, non tincidunt neque quam eget est. Vivamus sollicitudin urna ut elit lobortis, eget pretium est\n sollicitudin. Vivamus venenatis ut erat quis gravida. Praesent vel purus finibus velit pretium eleifend.\n\nCOMMANDS\n\n bar The quick brown fox jumps over the lazy dog.\n foo Lorem ipsum dolor sid amet.\n\nPROGRAM EXIT CODES\n\n 0 Everything is okay.\n 1 An I/O error occurred.\n -1 Invalid configuration.\n\nAUTHORS\n\n J\u00fcrgen Knauth <jk@binary-overflow.de>\n\nLICENSE\n\n This program is free software: you can redistribute it and/or modify it under the terms of the Apache Software License as published by\n Apache Software Foundation in version 2. For more details see the Apache Software License, which should be vailable at:\n https://www.apache.org/licenses/LICENSE-2.0\n```\n\n## Adding a description\n\nYou might want to add a description. For better readability this description could have chapters:\n\n```python\nap.addDescriptionChapter(\"Introduction\", \"Lorem ipsum dolor sid amet ...\")\nap.addDescriptionChapter(\"Usage\", \"Lorem ipsum dolor sid amet ...\")\nap.addDescriptionChapter(\"Whatever\", \"Lorem ipsum dolor sid amet ...\")\n```\n\nA description is placed **after** the synopsis and **before** the options.\n\nAdditional methods are provided to insert text at some other position in the help text `jk_argparsing` will create for yoou:\n\n* `addExtraChapterHead(..)`\n* `addExtraChapterMiddle(..)`\n* `addExtraChapterEnd(..)`\n\nThe full help text created will then have the following structure:\n\n| Position\t\t\t\t\t\t| Description\n| ---\t\t\t\t\t\t\t| ---\n| A title\t\t\t\t\t\t| In this example here: \"`myapp - My short description`\"\n| Synposis\t\t\t\t\t\t| Multiple lines defined by `createSynopsis(..)`\n| A head text section\t\t\t| Defined by `addExtraChapterHead(..)`\n| The standard description\t\t| Defined by `addDescriptionChapter(..)`\n| A middle text section\t\t\t| Defined by `addExtraChapterMiddle(..)`\n| Options\t\t\t\t\t\t| A formatted table with all options provided by `createOption(..)`\n| Commands\t\t\t\t\t\t| A formatted table with all commands provided by `createCommand(..)`\n| Program exit codes\t\t\t| A formatted table with all exit codes provided by `createReturnCode(..)`\n| A final text section\t\t\t| Defined by `addExtraChapterEnd(..)`\n| Authors\t\t\t\t\t\t| A list of all authors defined by `createAuthor(..)`\n| License\t\t\t\t\t\t| A short license information defined by `setLicense(..)`\n\n## Program options\n\nFor your program to support options your first step should be to provide default value(s) that can get modified later during parsing. Here we use `help` for demonstration purposes:\n\n```python\nap.optionDataDefaults.set(\"help\", False)\n```\n\nThen define the option so that the parser later will be able to process it:\n\n```python\nap.createOption(\"h\", \"help\", \"Display this help text.\").onOption = \\\n\tlambda argOption, argOptionArguments, parsedArgs: \\\n\t\tparsedArgs.optionData.set(\"help\", True)\n```\n\nIn this particular case the option will have no argument.\nHowever, the option will have a lambda function that can be assigned to `onOption`. This lambda function will be executed if the parser encounteres this option.\n\nThe lambda function will receive three arguments:\n* `argOption` - The option that is currently being parsed. (You typically have no use for this parameter as by attaching a lambda function you already know the option that is going to be parsed.)\n* `argOptionArguments` - A list of arguments the option might have. (This list is empty in our case as `--help` does not have any additional arguments.)\n* `parsedArgs` - The `ParsedArgs` object the parser is creating by parsing the command line on `ap.parse()`. (This `ParsedArgs` object will be returned later to the caller of `ap.parse()`.)\n\nWithin this lambda functions you should access `parsedArgs.optionData`. This is a dictionary you can modify. For simplicity invoke `set(..)` to modify a values.\nIn this example here the original value for `help` will be overwritten.\n\n## Program commands\n\nFor your program to support commands you just define your command. Example:\n\n```python\nap.createCommand(\"update\", \"Perform some kind of update.\")\n```\n\nOf course you could have a command with an argument:\n\n```python\nap.createCommand(\"process-file\", \"Load a settings file.\") \\\n\t.expectFile(\"<settingsFile>\", minLength=1, mustExist=True, toAbsolutePath=True)\n```\n\nNow if the user runs your program with arguments such as these ...\n\n> `yourprogram process-file some/path/to/a/file`\n\n... the parsing engine will check that a file path follows `process-file` that refers to an existing file. In addition this argument will converted to an absolute path automatically during parsing.\n\nProcessing such kind of program arguments in your program is simple. Here is an example:\n\n```python\n# parse the command line using our predefined object `ArgsParser` in `ap`\n# NOTE: all options get processed automatically during this parsing step\nparsedArgs = ap.parse()\n\nif parsedArgs.optionData[\"help\"]:\n\t# `help` is true, so let's exit here\n\tap.showHelp()\n\tsys.exit(1)\n\nif not parsedArgs.programArgs:\n\t# no program arguments specified, so let's exit here\n\tap.showHelp()\n\tsys.exit(1)\n\nfor cmdName, cmdArgs in parsedArgs.parseCommands():\n\tif cmdName == 'update':\n\t\t# do somethig\n\t\t...\n\telif cmdName == 'process-file':\n\t\t# do somethig\n\t\t...\n\telse:\n\t\t# fallback if - by accident - we have an error in our implementation here\n\t\traise Exception(\"Implementation error!\")\n```\n\n## Expectations for options and commands\n\nOptions and commands can have \"expections\". An expectation is an argument a user must append to the option. Example:\n\n> `yourprogram --output-file some/path/to/a/file do-something`\n\nOr:\n\n> `yourprogram process-file some/path/to/a/file`\n\nHere ...\n* `--output-file` would be an option that expects one argument,\n* `do-something` would be a command that has no arguments and\n* `process-file` would be a command that expects one argument.\n\nHere is how you could define such a command:\n\n```python\nap.createCommand(\"process-file\", \"Load a settings file.\") \\\n\t.expectFile(\"<settingsFile>\", minLength=1, mustExist=True, toAbsolutePath=True)\n```\n\nThe following expectations for arguments to options and commands are available:\n\n| Method to invoke\t\t\t\t| Description\t\t\t\t\t\t\t\t\t\t\t|\n| ---\t\t\t\t\t\t\t| ---\t\t\t\t\t\t\t\t\t\t\t\t\t|\n| `expectFileOrDirectory(..)`\t| Provided argument must be a file or directory\t\t\t|\n| `expectFile(..)`\t\t\t\t| Provided argument must be a file\t\t\t\t\t\t|\n| `expectDirectory(..)`\t\t\t| Provided argument must be a directory\t\t\t\t\t|\n| `expectString(..)`\t\t\t| Provided argument must be a text string\t\t\t\t|\n| `expectInt32(..)`\t\t\t\t| Provided argument must be an integer number\t\t\t|\n\nNOTE: By definition `expectString(..)`, `expectFileOrDirectory(..)`, `expectFile(..)` and `expectDirectory(..)` are quite similar: They all specify that a string is expected. However, each method will support constraints. While `expectString(..)` only supports standard string constraints, the other methods will assume that the specified string denotes a file or directory.\n\nAuthor(s)\n-------------------\n\n* J\u00fcrgen Knauth: pubsrc@binary-overflow.de\n\nLicense\n-------\n\nThis software is provided under the following license:\n\n* Apache Software License 2.0",
"bugtrack_url": null,
"license": "Apache2",
"summary": "A python module for parsing of program arguments.",
"version": "0.2023.6.28",
"project_urls": null,
"split_keywords": [
"program",
"arguments",
"commands",
"options",
"args"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "48c32bf46348846ca60fe144a187bf50b8e82b1341cdfe0e108334de01850906",
"md5": "491d6fd3031148f8f1cc7949376ebc6b",
"sha256": "b5751d0a95c55221446834e0ee4776a4da2dbc0f5656f876f8bda13d5c3cafec"
},
"downloads": -1,
"filename": "jk_argparsing-0.2023.6.28.tar.gz",
"has_sig": false,
"md5_digest": "491d6fd3031148f8f1cc7949376ebc6b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 34357,
"upload_time": "2023-06-28T11:02:30",
"upload_time_iso_8601": "2023-06-28T11:02:30.980516Z",
"url": "https://files.pythonhosted.org/packages/48/c3/2bf46348846ca60fe144a187bf50b8e82b1341cdfe0e108334de01850906/jk_argparsing-0.2023.6.28.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-28 11:02:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "jk-argparsing"
}
JSON