# Wintersdeep Argument Parser
This is a small extension to the native Python3 `argparse.ArgumentParser`. It adds some functionality I find I always end up requiring.
## Installation
```shell
pip install wintersdeep.argparse
```
## Log level support
Often you want the user to be able to configure log levels, thats a pain in itself. Then when you select `debug` and get overwhelmed you realise you only want it on one or more loggers, and not all of them. Often this is done by tweaking the code to acheive what you need in the moment. This helps fix that by making adjusting log levels at the command line simple - take a look:
```python
from wintersdeep.argparse import ArgumentParser
argument_parser = ArgumentParser()
argument_parser.add_log_level_arguments() # there are options here, but the defaults will work fine.
arguments = argument_parser.parse_args()
if log_levels := arguments.log_level:
log_levels.apply()
```
A user can now type `-l[log-level]` to set the global/default log level, or `-l[logger]=[log-level]` to set a specific log level, or any mix of the two.
```bash
python3 -m path.to.app -lwarning -lpath.to.app.problematic=debug -lpath.to.app.suspect=info
```
## Mapping `choices` support.
It alters the behaviour of the `choices` argument on the `add_argument` method such that it supports the use of `Mapping` objects such as `dict`.
When using a `Mapping` object as a `choices` constraint the user will be able to choose only from the keys of the `Mapping` object specified. The arguments value in the resulting `Namespace` will be that which is associated with the key in the provided Mapping - e.g. if the user specified the key _"abc"_ the value in the resulting namespace would be taken from `choices_mapping["abc"]`.
As a simple example, the below code accepts any number of integer arguments and prints them to stdout using the CLI specified formatting. The formatter argument `-f` is constrained using `choices` which is provided as the `formatters` `dict` object. Users will only be able to choose one of its keys (`bin`, `hex` or `oct`) and the value in the resulting namespace is the assoicated lambda expression.
```python
from wintersdeep.argparse import ArgumentParser
formatters = {
"bin": lambda n: f"{n:b}",
"oct": lambda n: f"{n:o}",
"hex": lambda n: f"{n:x}"
}
argument_parser = ArgumentParser()
argument_parser.add_argument("N", nargs="+", type=int)
argument_parser.add_argument("-f", choices=formatters, default_key='hex')
arguments = argument_parser.parse_args()
for n in arguments.N:
print( arguments.formatter(n) )
```
### Features
- Allows usage of `Mapping` type objects as a `choices` constraint on `ArgumentParser::add_argument`. Accepted input will be constrained to key values in the given map and the value in the resulting `Namespace` will be that keys associated value.
- Added a `default_key` keyword argument; you can specify either `default` or `default_key` but not both. When using `default_key` the default value will be the value associated with the specified `default_key` in the `choices` map. `default_key` allows you to ensure documentation and behaviour remain syncronised and readable. `default` can still be used as normal if preferred and is required when the default option should not be user selectable.
## Behaviour Notes
- **The `action` process wasn't applied to the `default` value (specified or derived from `default_key`).**
This is by intention and is consistent with the native `ArgumentParser` behaviour - the default value is provided _"as-is"_ when the option is not specifed.
- **The `Action` returned by `add_argument` is not the type specified by `add_argument`s `action` parameter**
The libraries behaviours are implemented by shimming `add_argument`, and inserting a custom `action` when `choices` are a `Mapping` type.
If you have set your own `action` then `add_argument` will preserve this and invoke it after the value has been translated, so you should still get the expected behaviour. However this does mean the `Action` class return by `add_argument` will not be of the type you originally specified. Your original `action` can be found in the `[action].next_action` property.
For example, the below script extends the original sample to use an `AddPrefix` action to prefix a string to the user specified formatter. This works identically to the native behaviour, except the `values` argument will be the value from the `choices` mapping.
```python
from argparse import Action
from wintersdeep.argparse import ArgumentParser
# A custom action to add a prefix to all formatters.
class AddPrefix(Action):
def __call__(self, parser, namespace, values, option_string=None):
# by the time this action receives `values` it has been converted into its Mapping associated value (in context a lambda function from `formatters`.
prefix_fn = lambda x: f"Your number is {values(x)}"
setattr(namespace, self.dest, prefix_fn)
formatters = {
"bin": lambda n: f"{n:b}",
"oct": lambda n: f"{n:o}",
"hex": lambda n: f"{n:x}"
}
argument_parser = ArgumentParser()
argument_parser.add_argument("N", nargs="+", type=int)
argument_parser.add_argument("-f", action=AddPrefix, choices=formatters, required=True)
arguments = argument_parser.parse_args()
for n in arguments.N:
print( arguments.formatter(n) )
print(action.__class__.__name__) # "MappingChoicesAction"
print(action.next_action.__class__) # <class '__main__.AddPrefix'>
```
Raw data
{
"_id": null,
"home_page": "https://github.com/wintersdeep/wintersdeep_argparse",
"name": "wintersdeep.argparse",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "WintersDeep",
"author_email": "admin@wintersdeep.com",
"download_url": "https://files.pythonhosted.org/packages/31/25/a5fa26eb164f4c0846e2caa807179fce6209196790e8e93408b19ee201e0/wintersdeep_argparse-1.1.4.tar.gz",
"platform": null,
"description": "# Wintersdeep Argument Parser\n\nThis is a small extension to the native Python3 `argparse.ArgumentParser`. It adds some functionality I find I always end up requiring.\n\n## Installation\n\n```shell\npip install wintersdeep.argparse\n```\n\n## Log level support\n\nOften you want the user to be able to configure log levels, thats a pain in itself. Then when you select `debug` and get overwhelmed you realise you only want it on one or more loggers, and not all of them. Often this is done by tweaking the code to acheive what you need in the moment. This helps fix that by making adjusting log levels at the command line simple - take a look:\n\n```python\nfrom wintersdeep.argparse import ArgumentParser\n\nargument_parser = ArgumentParser()\nargument_parser.add_log_level_arguments() # there are options here, but the defaults will work fine.\narguments = argument_parser.parse_args()\nif log_levels := arguments.log_level:\n log_levels.apply()\n```\n\nA user can now type `-l[log-level]` to set the global/default log level, or `-l[logger]=[log-level]` to set a specific log level, or any mix of the two.\n\n```bash\npython3 -m path.to.app -lwarning -lpath.to.app.problematic=debug -lpath.to.app.suspect=info\n```\n\n## Mapping `choices` support.\n\nIt alters the behaviour of the `choices` argument on the `add_argument` method such that it supports the use of `Mapping` objects such as `dict`. \n\nWhen using a `Mapping` object as a `choices` constraint the user will be able to choose only from the keys of the `Mapping` object specified. The arguments value in the resulting `Namespace` will be that which is associated with the key in the provided Mapping - e.g. if the user specified the key _\"abc\"_ the value in the resulting namespace would be taken from `choices_mapping[\"abc\"]`.\n\nAs a simple example, the below code accepts any number of integer arguments and prints them to stdout using the CLI specified formatting. The formatter argument `-f` is constrained using `choices` which is provided as the `formatters` `dict` object. Users will only be able to choose one of its keys (`bin`, `hex` or `oct`) and the value in the resulting namespace is the assoicated lambda expression.\n\n```python\nfrom wintersdeep.argparse import ArgumentParser\n\nformatters = {\n \"bin\": lambda n: f\"{n:b}\",\n \"oct\": lambda n: f\"{n:o}\",\n \"hex\": lambda n: f\"{n:x}\"\n}\n\nargument_parser = ArgumentParser()\nargument_parser.add_argument(\"N\", nargs=\"+\", type=int)\nargument_parser.add_argument(\"-f\", choices=formatters, default_key='hex')\n\narguments = argument_parser.parse_args()\n\nfor n in arguments.N:\n print( arguments.formatter(n) )\n```\n\n### Features\n\n- Allows usage of `Mapping` type objects as a `choices` constraint on `ArgumentParser::add_argument`. Accepted input will be constrained to key values in the given map and the value in the resulting `Namespace` will be that keys associated value.\n- Added a `default_key` keyword argument; you can specify either `default` or `default_key` but not both. When using `default_key` the default value will be the value associated with the specified `default_key` in the `choices` map. `default_key` allows you to ensure documentation and behaviour remain syncronised and readable. `default` can still be used as normal if preferred and is required when the default option should not be user selectable.\n\n## Behaviour Notes\n\n- **The `action` process wasn't applied to the `default` value (specified or derived from `default_key`).**\n\n This is by intention and is consistent with the native `ArgumentParser` behaviour - the default value is provided _\"as-is\"_ when the option is not specifed.\n\n- **The `Action` returned by `add_argument` is not the type specified by `add_argument`s `action` parameter**\n\n The libraries behaviours are implemented by shimming `add_argument`, and inserting a custom `action` when `choices` are a `Mapping` type.\n\n If you have set your own `action` then `add_argument` will preserve this and invoke it after the value has been translated, so you should still get the expected behaviour. However this does mean the `Action` class return by `add_argument` will not be of the type you originally specified. Your original `action` can be found in the `[action].next_action` property.\n\n For example, the below script extends the original sample to use an `AddPrefix` action to prefix a string to the user specified formatter. This works identically to the native behaviour, except the `values` argument will be the value from the `choices` mapping.\n\n ```python\n from argparse import Action\n from wintersdeep.argparse import ArgumentParser\n\n # A custom action to add a prefix to all formatters.\n class AddPrefix(Action):\n def __call__(self, parser, namespace, values, option_string=None):\n # by the time this action receives `values` it has been converted into its Mapping associated value (in context a lambda function from `formatters`.\n prefix_fn = lambda x: f\"Your number is {values(x)}\"\n setattr(namespace, self.dest, prefix_fn)\n\n formatters = {\n \"bin\": lambda n: f\"{n:b}\",\n \"oct\": lambda n: f\"{n:o}\",\n \"hex\": lambda n: f\"{n:x}\"\n }\n\n argument_parser = ArgumentParser()\n argument_parser.add_argument(\"N\", nargs=\"+\", type=int)\n argument_parser.add_argument(\"-f\", action=AddPrefix, choices=formatters, required=True)\n\n arguments = argument_parser.parse_args()\n\n for n in arguments.N:\n print( arguments.formatter(n) )\n \n print(action.__class__.__name__) # \"MappingChoicesAction\"\n print(action.next_action.__class__) # <class '__main__.AddPrefix'>\n ```\n",
"bugtrack_url": null,
"license": null,
"summary": "Extends the native Python3 `argparse.ArgumentParser` to supports using maps as a `choices` argument type.",
"version": "1.1.4",
"project_urls": {
"Homepage": "https://github.com/wintersdeep/wintersdeep_argparse"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b993320b251f26217df20ee2be318d885ee6de76ea95d3c8bbabf25009857683",
"md5": "316e1e9471f2c836debc5274744e3c53",
"sha256": "f6ef7d643e9d35dccb609eeffc5c18af303800b5f1c22aa9752fc41a3ee55e4e"
},
"downloads": -1,
"filename": "wintersdeep.argparse-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "316e1e9471f2c836debc5274744e3c53",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 11362,
"upload_time": "2024-08-06T20:35:59",
"upload_time_iso_8601": "2024-08-06T20:35:59.133643Z",
"url": "https://files.pythonhosted.org/packages/b9/93/320b251f26217df20ee2be318d885ee6de76ea95d3c8bbabf25009857683/wintersdeep.argparse-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3125a5fa26eb164f4c0846e2caa807179fce6209196790e8e93408b19ee201e0",
"md5": "22d901062a969548e02568aeb3a46ff1",
"sha256": "846cd88487032fa782b865b0d4092f25a2c43a3cf2aa5d7106d1c1ea23c1ed5b"
},
"downloads": -1,
"filename": "wintersdeep_argparse-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "22d901062a969548e02568aeb3a46ff1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 12919,
"upload_time": "2024-08-06T20:36:00",
"upload_time_iso_8601": "2024-08-06T20:36:00.930637Z",
"url": "https://files.pythonhosted.org/packages/31/25/a5fa26eb164f4c0846e2caa807179fce6209196790e8e93408b19ee201e0/wintersdeep_argparse-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-06 20:36:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wintersdeep",
"github_project": "wintersdeep_argparse",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "wintersdeep.argparse"
}
JSON
