argparse_subcommand


Nameargparse_subcommand JSON
Version 1.2 PyPI version JSON
download
home_pagehttps://github.com/prechelt/argparse_subcommand
Summarystructure and simplify subcommand handling with argparse
upload_time2024-03-07 09:37:43
maintainer
docs_urlNone
authorLutz Prechelt
requires_python>=3.7,<4.0
licenseLICENSE
keywords argparse
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # argparse_subcommand

Library to extend Python argparse stdlib with easy handling of subcommands

Extends `argparse.ArgumentParser` with a facility for configuring subcommands by convention.
Each subcommand lives in its separate Python module.  
The name of the subcommand is the module name (without superpackage names)
with underscore replaced by dash.  

To be a subcommand module, a module must have 

```
import argparse_subcommand as ap_sub

meaning = "some help text for the subcommand"
def add_arguments(parser: ap_sub.ArgumentParser): ...  # configure the subcommand's sub-argparser
def execute(args: ap_sub.Namespace): ...  # run the subcommand
```

The module can also _optionally_ have:

```
aliases = ["subcmd-alias1", "subcmd-alias2"]  # optional.
```

for making available the same subcommand under one or more 
alternative names (e.g. an abbreviation).

For use, create the parser as usual and then call the submodule scanner:

```
def main(argv: list[str]):
    parser = ap_sub.ArgumentParser(epilog=explanation)
    parser.scan("mysubcmds.subcmd1", "mysubcmds.subcmd2")  # or provide module object instead of str
    args = parser.parse_args(argv[1:])
    parser.execute_subcommand(args)  # or supply nothing, then parse_args() will be called internally

if __name__ == '__main__':
  main(sys.argv)
```

By convention, the subcommand modules (and only they) all go into a common package.
If you do that, you can scan them all at once:

```
parser.scan("mysubcmds.*", strict=True)
```


`argparse_subcommand` uses only one sub-parser group, so that
subcommands cannot be nested, there is only one level of subcommands.  
It will execute `importlib.import_module()` on all modules mentioned in a `scan()` call as strings.     
Multiple calls to `scan()` are allowed, each can have one or more arguments.  
`scan(..., strict=False)` (the default) will ignore non-subcommand modules.  
`scan(..., trace=True)` produces output helpful for debugging your subcommands setup.  


That's all.

## Version history

- 1.0, 2023-05:  
  First release
- 1.1, 2024-01:  
  Error messages and trace messages go to stderr, not stdout.  
  More informative messages when scanned modules are non-subcommand modules.
  Small improvements to documentation.  
  Added version history.
- 1.2, 2024-03:
  Better and clearer pattern for the main routine in the documentation.
- ...
            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/prechelt/argparse_subcommand",
    "name": "argparse_subcommand",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.7,<4.0",
    "maintainer_email": "",
    "keywords": "argparse",
    "author": "Lutz Prechelt",
    "author_email": "",
    "download_url": "https://files.pythonhosted.org/packages/55/da/e4bfceb9698149f8c839b2d91189dc6f95f0f1c35ee94b7eb2b09828ee4b/argparse_subcommand-1.2.tar.gz",
    "platform": null,
    "description": "# argparse_subcommand\n\nLibrary to extend Python argparse stdlib with easy handling of subcommands\n\nExtends `argparse.ArgumentParser` with a facility for configuring subcommands by convention.\nEach subcommand lives in its separate Python module.  \nThe name of the subcommand is the module name (without superpackage names)\nwith underscore replaced by dash.  \n\nTo be a subcommand module, a module must have \n\n```\nimport argparse_subcommand as ap_sub\n\nmeaning = \"some help text for the subcommand\"\ndef add_arguments(parser: ap_sub.ArgumentParser): ...  # configure the subcommand's sub-argparser\ndef execute(args: ap_sub.Namespace): ...  # run the subcommand\n```\n\nThe module can also _optionally_ have:\n\n```\naliases = [\"subcmd-alias1\", \"subcmd-alias2\"]  # optional.\n```\n\nfor making available the same subcommand under one or more \nalternative names (e.g. an abbreviation).\n\nFor use, create the parser as usual and then call the submodule scanner:\n\n```\ndef main(argv: list[str]):\n    parser = ap_sub.ArgumentParser(epilog=explanation)\n    parser.scan(\"mysubcmds.subcmd1\", \"mysubcmds.subcmd2\")  # or provide module object instead of str\n    args = parser.parse_args(argv[1:])\n    parser.execute_subcommand(args)  # or supply nothing, then parse_args() will be called internally\n\nif __name__ == '__main__':\n  main(sys.argv)\n```\n\nBy convention, the subcommand modules (and only they) all go into a common package.\nIf you do that, you can scan them all at once:\n\n```\nparser.scan(\"mysubcmds.*\", strict=True)\n```\n\n\n`argparse_subcommand` uses only one sub-parser group, so that\nsubcommands cannot be nested, there is only one level of subcommands.  \nIt will execute `importlib.import_module()` on all modules mentioned in a `scan()` call as strings.     \nMultiple calls to `scan()` are allowed, each can have one or more arguments.  \n`scan(..., strict=False)` (the default) will ignore non-subcommand modules.  \n`scan(..., trace=True)` produces output helpful for debugging your subcommands setup.  \n\n\nThat's all.\n\n## Version history\n\n- 1.0, 2023-05:  \n  First release\n- 1.1, 2024-01:  \n  Error messages and trace messages go to stderr, not stdout.  \n  More informative messages when scanned modules are non-subcommand modules.\n  Small improvements to documentation.  \n  Added version history.\n- 1.2, 2024-03:\n  Better and clearer pattern for the main routine in the documentation.\n- ...",
    "bugtrack_url": null,
    "license": "LICENSE",
    "summary": "structure and simplify subcommand handling with argparse",
    "version": "1.2",
    "project_urls": {
        "Homepage": "https://github.com/prechelt/argparse_subcommand",
        "Repository": "https://github.com/prechelt/argparse_subcommand"
    },
    "split_keywords": [
        "argparse"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "f7836a153bb8ba00c6616db04ad6a7f40f5bee152485f0d4584b63d55a79acd6",
                "md5": "f58b5bbf7175469c9a7672a043017e56",
                "sha256": "ce0718bbd51448203adb603af84d0a78bb514a1492bb6ba84bf93dd4fa82b3c5"
            },
            "downloads": -1,
            "filename": "argparse_subcommand-1.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f58b5bbf7175469c9a7672a043017e56",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7,<4.0",
            "size": 7261,
            "upload_time": "2024-03-07T09:37:41",
            "upload_time_iso_8601": "2024-03-07T09:37:41.580975Z",
            "url": "https://files.pythonhosted.org/packages/f7/83/6a153bb8ba00c6616db04ad6a7f40f5bee152485f0d4584b63d55a79acd6/argparse_subcommand-1.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "55dae4bfceb9698149f8c839b2d91189dc6f95f0f1c35ee94b7eb2b09828ee4b",
                "md5": "cb11245e3b717f794451b0c6da46b5a4",
                "sha256": "0fb3f2055fd845ba48268879d67ae0632948d379015e2853efb15c38bcc7965a"
            },
            "downloads": -1,
            "filename": "argparse_subcommand-1.2.tar.gz",
            "has_sig": false,
            "md5_digest": "cb11245e3b717f794451b0c6da46b5a4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7,<4.0",
            "size": 4193,
            "upload_time": "2024-03-07T09:37:43",
            "upload_time_iso_8601": "2024-03-07T09:37:43.319912Z",
            "url": "https://files.pythonhosted.org/packages/55/da/e4bfceb9698149f8c839b2d91189dc6f95f0f1c35ee94b7eb2b09828ee4b/argparse_subcommand-1.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-07 09:37:43",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "prechelt",
    "github_project": "argparse_subcommand",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "argparse_subcommand"
}
        
Elapsed time: 0.57359s