| Name | argpi JSON |
| Version |
1.2.1
JSON |
| download |
| home_page | None |
| Summary | Next Level Argument Parser |
| upload_time | 2024-11-19 11:22:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
d33pster
argpi
argpy
arguments
parser
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Overview
`argpi` revolutionizes argument parsing in python by introducing a registration based system. This allows users to implement argument parsing in one line of code. Any type of argument can be defined other than the conventional `--` and `-` prefix type arguments. For example, arguments can be of the type `argument1` or `_argument1` or any keyword you set. There is not restrictions on the short form of the argument. You can have `--argument1` as the long form while `_arg1` as the shorter form. This brings a lot of flexibility and customization to the users.
> ### For full documentation, visit [argpi.hashnode.space](https://argpi.hashnode.space)
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage and Examples](#usage-and-examples)
- [Contributing](#contributing)
- [License](#license)
## Features
* `argpi`'s one line implementation and fault finding system helps users maintain readability and reliability in their code.
* Flexibility and customization while defining arguments.
* Automatic help text generation.
* Prep and Exec based argument parsing helps users to create complex argument structures.
## Installation
```bash
pip install argpi
```
## Usage and Examples
Using `argpi` is pretty simple. `argpi` was made keeping in mind the concepts of Object Oriented Programming and therefore, it is recommended to create a class for your argument preparations and executions separately.
What the above statement means is that suppose you have an argument, say, `--install` which is the base argument for installing something. Now, there are different flag type arguments (meaning, let's say, `--install-with-pip` or `--install-with-conda` or `--install-with-git`, which are used to determine some boolean or case based code execution), or some arguments which take some value (like `--install-path` which takes a path as an argument). These are termed as `prep` arguments while `--install` is the `exec` argument. Before `--install`'s backend code execution, all `prep`s will be performed. Let us see how we can do this in code.
To begin, we need to import `Definition` and `Pathways` classes from `argpi` module.
```python
from argpi import Definition, Pathways
```
All the argument definitions are stored in the `Definition` class. Let us add the definitions from our example above.
```python
def_obj = Definition([
{
'name': 'Installation Argument',
'value': '--install',
'short': '_i',
'description': 'Install something\nSyntax: <script_name> --install'
},
{
'name': 'Install with pip',
'value': '--install-with-pip',
'short': '_ip',
'description': 'Install with pip\nSyntax: <script_name> --install-with-pip'
},
{
'name': 'Install with conda',
'value': '--install-with-conda',
'short': '_ic',
'description': 'Install with conda\nSyntax: <script_name> --install-with-conda'
},
{
'name': 'Install path',
'value': '--install-path',
'short': '_ip',
'description': 'Install path\nSyntax: <script_name> --install-path <path>'
},
])
```
Once we have our definitions ready, we can use the `Pathways` class to auto-capture the arguments and register preps and execs.
Now, for our example, `--install` is the exec argument and the rest are prep arguments. We will create a class for our preparations and executions.
For preparations, we will create a class `Configurations` and for executions, we will create a class `Drivers`.
> **Note:** You can name the classes anything you want. `Configurations` class basically contains information on how a particular method (let's say, for `--install`) will be executed.
Understand it this way, the method we will define for `--install` can go several ways. The user may want to use `pip` or `conda` or `git` to install something. This is where the `Configurations` class will be used.
`Configurations` class will have methods and attributes which will store our conditional variables such as which installer to use: `pip`, `conda`, `git` etc and the path to install the software.
```python
from typing import Union
class Configurations:
def __init__(self) -> None:
# Define your conditionals or variables here
self.pip: bool = False
self.conda: bool = False
self.git: bool = False
self.path: Union[str, None] = None
def set_pip(self) -> None:
self.pip = True
def set_conda(self) -> None:
self.conda = True
def set_git(self) -> None:
self.git = True
def set_path(self, path: str) -> None:
self.path = path
```
```python
class Drivers:
@staticmethod
def install(configurations: Configurations) -> None:
if configurations.pip:
print(f"Installing with pip to {configurations.path}")
elif configurations.conda:
print(f"Installing with conda to {configurations.path}")
elif configurations.git:
print(f"Installing with git to {configurations.path}")
# or add your own logic here.
```
Once we have our classes ready, we can use the `Pathways` class to auto-capture the arguments and register preps and execs.
```python
# lets create our configurations object
configurations = Configurations()
pathways = PathWays(definition=def_obj)
# Check docstring for more info on the parameters,
# apart from `definition`, there is one other parameter, `skip` which is set to 1 by default.
# This parameter is used to skip the first `n` arguments from sys.argv.
```
Once we have our `Pathways` object ready, we can register our preps and execs. All arguments except `--install` are prep arguments.
While registering, we can provide a function which will be called if the argument is present. The important point to note here is that the arguments that are passed to your provided functions can either be defined by you or can be captured from the command line. This is what makes `argpi` better than other argument parsing libraries.
The `pathways.register` function has 2 signatures, where the first one is where you give your own function and own arguments. The second one is where you provide your own function but let `argpi` capture the values provided to the argument by the user and pass it to the function.
There are 3 ways you can choose to capture values from the command line:
- `Single`: This is used when you know that the argument will take only one value and whatever it is, you want to pass it to the function.
- `Till Next`: This is used when you know that the argument will take multiple values but you want to stop capturing when the next argument is encountered.
- `Till Last`: This is used when you know that the argument will take multiple values and you know for sure this argument will be the last argument passed by the user.
Do not worry, If you are unsure about `Till Next` and `Till Last`, just use `Till Next` and it will automatically detect if the argument is the last argument or not and act accordingly.
```python
pathways.register(
argument='--install-with-pip',
function=configurations.set_pip,
type='PREP',
arguments=(True,), # we are passing our own arguments to the function
)
pathways.register(
argument='--install-with-conda',
function=configurations.set_conda,
type='PREP',
arguments=(True,),
)
pathways.register(
argument='--install-with-git',
function=configurations.set_git,
type='PREP',
arguments=(True,),
)
pathways.register(
argument='--install-path',
function=configurations.set_path,
type='PREP',
what_value_expected='Single', # we want one value from the command line
)
```
Now, let us define the `--install` argument.
```python
pathways.register(
argument='--install',
function=Drivers.install,
type='EXEC',
arguments=(configurations,),
)
```
Once all definitions and registrations are done, we can now orchestrate the pathway preps and executions.
```python
pathways.orchestrate
```
This will first perform all preps which will set the variables in the `Configurations` class and then it will perform the execution which will use these variables to execute the code.
Note that the executions will only be performed if the registered argument is present in the command line, else nothing will happen.
Also, the `pathways.orchestrate` method automatically validates all preparations and executions. It will raise an error if anything fails.
## Contributing
Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "argpi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "d33pster, argpi, argpy, arguments, parser",
"author": null,
"author_email": "Soumyo Deep Gupta <deep.main.ac@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cb/83/722d90abea3f9996e4e46d498ac08e09ed4648f4823e9431c941fc34146b/argpi-1.2.1.tar.gz",
"platform": null,
"description": "# Overview\n\n`argpi` revolutionizes argument parsing in python by introducing a registration based system. This allows users to implement argument parsing in one line of code. Any type of argument can be defined other than the conventional `--` and `-` prefix type arguments. For example, arguments can be of the type `argument1` or `_argument1` or any keyword you set. There is not restrictions on the short form of the argument. You can have `--argument1` as the long form while `_arg1` as the shorter form. This brings a lot of flexibility and customization to the users.\n\n> ### For full documentation, visit [argpi.hashnode.space](https://argpi.hashnode.space)\n\n## Table of Contents\n\n- [Features](#features)\n- [Installation](#installation)\n- [Usage and Examples](#usage-and-examples)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Features\n\n* `argpi`'s one line implementation and fault finding system helps users maintain readability and reliability in their code.\n* Flexibility and customization while defining arguments.\n* Automatic help text generation.\n* Prep and Exec based argument parsing helps users to create complex argument structures.\n\n## Installation\n\n```bash\npip install argpi\n```\n\n## Usage and Examples\n\nUsing `argpi` is pretty simple. `argpi` was made keeping in mind the concepts of Object Oriented Programming and therefore, it is recommended to create a class for your argument preparations and executions separately.\n\nWhat the above statement means is that suppose you have an argument, say, `--install` which is the base argument for installing something. Now, there are different flag type arguments (meaning, let's say, `--install-with-pip` or `--install-with-conda` or `--install-with-git`, which are used to determine some boolean or case based code execution), or some arguments which take some value (like `--install-path` which takes a path as an argument). These are termed as `prep` arguments while `--install` is the `exec` argument. Before `--install`'s backend code execution, all `prep`s will be performed. Let us see how we can do this in code.\n\nTo begin, we need to import `Definition` and `Pathways` classes from `argpi` module.\n\n```python\nfrom argpi import Definition, Pathways\n```\n\nAll the argument definitions are stored in the `Definition` class. Let us add the definitions from our example above.\n\n```python\ndef_obj = Definition([\n {\n 'name': 'Installation Argument',\n 'value': '--install',\n 'short': '_i',\n 'description': 'Install something\\nSyntax: <script_name> --install'\n },\n {\n 'name': 'Install with pip',\n 'value': '--install-with-pip',\n 'short': '_ip',\n 'description': 'Install with pip\\nSyntax: <script_name> --install-with-pip'\n },\n {\n 'name': 'Install with conda',\n 'value': '--install-with-conda',\n 'short': '_ic',\n 'description': 'Install with conda\\nSyntax: <script_name> --install-with-conda'\n },\n {\n 'name': 'Install path',\n 'value': '--install-path',\n 'short': '_ip',\n 'description': 'Install path\\nSyntax: <script_name> --install-path <path>'\n },\n])\n```\n\nOnce we have our definitions ready, we can use the `Pathways` class to auto-capture the arguments and register preps and execs.\n\nNow, for our example, `--install` is the exec argument and the rest are prep arguments. We will create a class for our preparations and executions.\n\nFor preparations, we will create a class `Configurations` and for executions, we will create a class `Drivers`.\n\n> **Note:** You can name the classes anything you want. `Configurations` class basically contains information on how a particular method (let's say, for `--install`) will be executed. \nUnderstand it this way, the method we will define for `--install` can go several ways. The user may want to use `pip` or `conda` or `git` to install something. This is where the `Configurations` class will be used. \n`Configurations` class will have methods and attributes which will store our conditional variables such as which installer to use: `pip`, `conda`, `git` etc and the path to install the software.\n\n```python\nfrom typing import Union\n\nclass Configurations:\n def __init__(self) -> None:\n # Define your conditionals or variables here\n self.pip: bool = False\n self.conda: bool = False\n self.git: bool = False\n self.path: Union[str, None] = None\n \n def set_pip(self) -> None:\n self.pip = True\n \n def set_conda(self) -> None:\n self.conda = True\n \n def set_git(self) -> None:\n self.git = True\n \n def set_path(self, path: str) -> None:\n self.path = path\n```\n\n```python\nclass Drivers:\n @staticmethod\n def install(configurations: Configurations) -> None:\n if configurations.pip:\n print(f\"Installing with pip to {configurations.path}\")\n elif configurations.conda:\n print(f\"Installing with conda to {configurations.path}\")\n elif configurations.git:\n print(f\"Installing with git to {configurations.path}\")\n \n # or add your own logic here.\n```\n\nOnce we have our classes ready, we can use the `Pathways` class to auto-capture the arguments and register preps and execs.\n\n```python\n# lets create our configurations object\nconfigurations = Configurations()\n\npathways = PathWays(definition=def_obj)\n# Check docstring for more info on the parameters,\n# apart from `definition`, there is one other parameter, `skip` which is set to 1 by default.\n# This parameter is used to skip the first `n` arguments from sys.argv.\n\n```\n\nOnce we have our `Pathways` object ready, we can register our preps and execs. All arguments except `--install` are prep arguments.\n\nWhile registering, we can provide a function which will be called if the argument is present. The important point to note here is that the arguments that are passed to your provided functions can either be defined by you or can be captured from the command line. This is what makes `argpi` better than other argument parsing libraries.\n\nThe `pathways.register` function has 2 signatures, where the first one is where you give your own function and own arguments. The second one is where you provide your own function but let `argpi` capture the values provided to the argument by the user and pass it to the function.\n\nThere are 3 ways you can choose to capture values from the command line:\n\n- `Single`: This is used when you know that the argument will take only one value and whatever it is, you want to pass it to the function.\n- `Till Next`: This is used when you know that the argument will take multiple values but you want to stop capturing when the next argument is encountered.\n- `Till Last`: This is used when you know that the argument will take multiple values and you know for sure this argument will be the last argument passed by the user.\n\nDo not worry, If you are unsure about `Till Next` and `Till Last`, just use `Till Next` and it will automatically detect if the argument is the last argument or not and act accordingly.\n\n```python\n\npathways.register(\n argument='--install-with-pip',\n function=configurations.set_pip,\n type='PREP',\n arguments=(True,), # we are passing our own arguments to the function\n)\n\npathways.register(\n argument='--install-with-conda',\n function=configurations.set_conda,\n type='PREP',\n arguments=(True,),\n)\n\npathways.register(\n argument='--install-with-git',\n function=configurations.set_git,\n type='PREP',\n arguments=(True,), \n)\n\npathways.register(\n argument='--install-path',\n function=configurations.set_path,\n type='PREP',\n what_value_expected='Single', # we want one value from the command line\n)\n```\n\nNow, let us define the `--install` argument.\n\n```python\npathways.register(\n argument='--install',\n function=Drivers.install,\n type='EXEC',\n arguments=(configurations,),\n)\n```\n\nOnce all definitions and registrations are done, we can now orchestrate the pathway preps and executions.\n\n```python\npathways.orchestrate\n```\n\nThis will first perform all preps which will set the variables in the `Configurations` class and then it will perform the execution which will use these variables to execute the code.\n\nNote that the executions will only be performed if the registered argument is present in the command line, else nothing will happen.\n\nAlso, the `pathways.orchestrate` method automatically validates all preparations and executions. It will raise an error if anything fails.\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Next Level Argument Parser",
"version": "1.2.1",
"project_urls": {
"Documentation": "https://argpi.hashnode.space",
"GitHub": "https://github.com/d33p0st/argpi",
"Issues": "https://github.com/d33p0st/argpi/issues",
"Pull Requests": "https://github.com/d33p0st/argpi/pulls"
},
"split_keywords": [
"d33pster",
" argpi",
" argpy",
" arguments",
" parser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8b49dedb2bba461d4abc970e01f8fc9b2a6d86a4df9b7ee367cdbdca0540245e",
"md5": "d8c288214c061d376ea4103089ae528b",
"sha256": "aa2b59c3289a19d237bd57ae26978439900082f15334f78dda01c15f5a314556"
},
"downloads": -1,
"filename": "argpi-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d8c288214c061d376ea4103089ae528b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16943,
"upload_time": "2024-11-19T11:22:12",
"upload_time_iso_8601": "2024-11-19T11:22:12.610773Z",
"url": "https://files.pythonhosted.org/packages/8b/49/dedb2bba461d4abc970e01f8fc9b2a6d86a4df9b7ee367cdbdca0540245e/argpi-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cb83722d90abea3f9996e4e46d498ac08e09ed4648f4823e9431c941fc34146b",
"md5": "be3ede633b235c96b0dc786795cc96bd",
"sha256": "89f9698aa782a6852f8ca5b24b4529d3620d2adce3ed5fbfab66f60829478a61"
},
"downloads": -1,
"filename": "argpi-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "be3ede633b235c96b0dc786795cc96bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 16123,
"upload_time": "2024-11-19T11:22:13",
"upload_time_iso_8601": "2024-11-19T11:22:13.888218Z",
"url": "https://files.pythonhosted.org/packages/cb/83/722d90abea3f9996e4e46d498ac08e09ed4648f4823e9431c941fc34146b/argpi-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-19 11:22:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "d33p0st",
"github_project": "argpi",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "argpi"
}
