| Name | arrrgs JSON |
| Version |
3.1.0
JSON |
| download |
| home_page | |
| Summary | The library for easily writing feature-rich Python scripts |
| upload_time | 2023-12-05 20:16:29 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
cli
command-line-tool
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Arrrgs [](https://pypi.org/project/arrrgs/) [](https://github.com/mishamyrt/arrrgs/actions/workflows/qa.yaml)
<img align="right" width="104px" height="176px"
alt="Logo"
src="./assets/logo@2x.png">
The library for easily writing feature-rich Python scripts. Uses the built-in `argparse` module for parsing.
* Simple API
* Automatic async support
* Small size
## Installing
```sh
pip install arrrgs
```
## Usage
### Basic
To declare a command, write a function and add the `command` decorator to it. To start command processing, call the function `run`.
```py
from arrrgs import command, run
from os import getlogin
@command()
def hello():
"""Prints hello message to current user"""
print(f"Hello, {getlogin()}")
if __name__ == "__main__":
run()
```
Arrrgs will process the command and show the user the result. The help message will be generated from the function documentation.
```sh
python examples/basic.py hello --help
# usage: basic.py hello [-h]
# Prints hello message to current user
# optional arguments:
# -h, --help show this help message and exit
```
### Custom command absence handler
Use the `root_command` decorator to set up a no-command handler. The same rules apply to this function as to normal command handlers except that it cannot have its own arguments.
```py
from arrrgs import run, root_command
@root_command()
def print_hello():
"""Prints hello message to current user"""
print("Hello, user")
if __name__ == "__main__":
run()
```
### Arguments
To add arguments for command you need to pass their description to the decorator arguments. If you need global arguments, pass them to `global_args` function. The available parameters of `arg` are the same as [for `add_argument` in `argparse`](https://docs.python.org/3/library/argparse.html#quick-links-for-add-argument).
```py
from arrrgs import command, arg, run, global_args
global_args(
arg("--rage", "-r", action='store_true', help="Rage mod")
)
@command(
arg("name", help="User name")
)
def hello(args):
"""Prints hello message to current user"""
user_name = args.name
if args.rage:
user_name = user_name.upper()
print(f"Hello, {user_name}")
if __name__ == "__main__":
run()
```
### Context
Sometimes all the teams in an application need a common entity that they interact with. Commands have a context for that. The context value is set when the function `run` is called.
```py
from arrrgs import command, run
class User:
def __init__(self, name):
self._name = name
def get_name(self):
"""Returns user name"""
return self._name
@command()
def hello(_, context):
"""Prints hello message to current user"""
print(f"Hello, {context.get_name()}")
if __name__ == "__main__":
user = User("Mikhael")
run(user)
```
### Async
To execute the command in an asynchronous context, simply add the `async` keyword in the function declaration.
```py
@command()
async def hello():
"""Prints hello message to current user"""
print("Hello, async user")
```
### Custom command name
A situation may arise where you have to name a command after a built-in function or type, e.g. `list`. To specify a command name other than the function name, use the `name` parameter.
```py
@command(name="list")
def list_numbers():
"""Prints list of numbers"""
print("1, 2, 3")
```
Raw data
{
"_id": null,
"home_page": "",
"name": "arrrgs",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "cli,command-line-tool",
"author": "",
"author_email": "Mikhael Khrustik <misha@myrt.co>",
"download_url": "https://files.pythonhosted.org/packages/ee/fb/872361c95912b9a764b238157d0c5962003b46bf7525ebebd4d0f6e5858b/arrrgs-3.1.0.tar.gz",
"platform": null,
"description": "# Arrrgs [](https://pypi.org/project/arrrgs/) [](https://github.com/mishamyrt/arrrgs/actions/workflows/qa.yaml)\n\n<img align=\"right\" width=\"104px\" height=\"176px\"\n alt=\"Logo\"\n src=\"./assets/logo@2x.png\">\n\nThe library for easily writing feature-rich Python scripts. Uses the built-in `argparse` module for parsing.\n\n* Simple API\n* Automatic async support\n* Small size\n\n## Installing\n\n```sh\npip install arrrgs\n```\n\n## Usage\n\n### Basic\n\nTo declare a command, write a function and add the `command` decorator to it. To start command processing, call the function `run`.\n\n```py\nfrom arrrgs import command, run\nfrom os import getlogin\n\n@command()\ndef hello():\n \"\"\"Prints hello message to current user\"\"\"\n print(f\"Hello, {getlogin()}\")\n\nif __name__ == \"__main__\":\n run()\n```\n\nArrrgs will process the command and show the user the result. The help message will be generated from the function documentation.\n\n```sh\npython examples/basic.py hello --help\n# usage: basic.py hello [-h]\n\n# Prints hello message to current user\n\n# optional arguments:\n# -h, --help show this help message and exit\n```\n\n### Custom command absence handler\n\nUse the `root_command` decorator to set up a no-command handler. The same rules apply to this function as to normal command handlers except that it cannot have its own arguments.\n\n```py\nfrom arrrgs import run, root_command\n\n@root_command()\ndef print_hello():\n \"\"\"Prints hello message to current user\"\"\"\n print(\"Hello, user\")\n\nif __name__ == \"__main__\":\n run()\n```\n\n\n### Arguments\n\nTo add arguments for command you need to pass their description to the decorator arguments. If you need global arguments, pass them to `global_args` function. The available parameters of `arg` are the same as [for `add_argument` in `argparse`](https://docs.python.org/3/library/argparse.html#quick-links-for-add-argument).\n\n```py\nfrom arrrgs import command, arg, run, global_args\n\nglobal_args(\n arg(\"--rage\", \"-r\", action='store_true', help=\"Rage mod\")\n)\n\n@command(\n arg(\"name\", help=\"User name\")\n)\ndef hello(args):\n \"\"\"Prints hello message to current user\"\"\"\n user_name = args.name\n if args.rage:\n user_name = user_name.upper()\n print(f\"Hello, {user_name}\")\n\nif __name__ == \"__main__\":\n run()\n```\n\n### Context\n\nSometimes all the teams in an application need a common entity that they interact with. Commands have a context for that. The context value is set when the function `run` is called.\n\n```py\nfrom arrrgs import command, run\n\nclass User:\n def __init__(self, name):\n self._name = name\n\n def get_name(self):\n \"\"\"Returns user name\"\"\"\n return self._name\n\n@command()\ndef hello(_, context):\n \"\"\"Prints hello message to current user\"\"\"\n print(f\"Hello, {context.get_name()}\")\n\nif __name__ == \"__main__\":\n user = User(\"Mikhael\")\n run(user)\n```\n\n### Async\n\nTo execute the command in an asynchronous context, simply add the `async` keyword in the function declaration.\n\n```py\n@command()\nasync def hello():\n \"\"\"Prints hello message to current user\"\"\"\n print(\"Hello, async user\")\n```\n\n### Custom command name\n\nA situation may arise where you have to name a command after a built-in function or type, e.g. `list`. To specify a command name other than the function name, use the `name` parameter.\n\n```py\n@command(name=\"list\")\ndef list_numbers():\n \"\"\"Prints list of numbers\"\"\"\n print(\"1, 2, 3\")\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "The library for easily writing feature-rich Python scripts",
"version": "3.1.0",
"project_urls": null,
"split_keywords": [
"cli",
"command-line-tool"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6263b4ae9a7c62e87f3961700bfa7bb521ed97a228816d13f9409584d2894301",
"md5": "c9e9f269b4bef05230b98bfe0ffc8bc0",
"sha256": "7a9f763654569f4c6fd8690b07680a7a5e767860c7299b3fd375faf763ba08c9"
},
"downloads": -1,
"filename": "arrrgs-3.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c9e9f269b4bef05230b98bfe0ffc8bc0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6334,
"upload_time": "2023-12-05T20:16:27",
"upload_time_iso_8601": "2023-12-05T20:16:27.525710Z",
"url": "https://files.pythonhosted.org/packages/62/63/b4ae9a7c62e87f3961700bfa7bb521ed97a228816d13f9409584d2894301/arrrgs-3.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eefb872361c95912b9a764b238157d0c5962003b46bf7525ebebd4d0f6e5858b",
"md5": "bb63f863c3f7bbb4191159aeacdc8004",
"sha256": "604c490dcc251963291356ab5f5adcf311ae299e4657a54a38ce390e721c1046"
},
"downloads": -1,
"filename": "arrrgs-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "bb63f863c3f7bbb4191159aeacdc8004",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 24868,
"upload_time": "2023-12-05T20:16:29",
"upload_time_iso_8601": "2023-12-05T20:16:29.682758Z",
"url": "https://files.pythonhosted.org/packages/ee/fb/872361c95912b9a764b238157d0c5962003b46bf7525ebebd4d0f6e5858b/arrrgs-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-05 20:16:29",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "arrrgs"
}
