[](https://pepy.tech/project/margument)
# Margument - Settings Manager
## Table of Contents
- [Description](#description)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Support](#support)
- [License](#license)
- [Status](#status)
<a name="description"></a>
## Description
Margument can manage configurations based on given program arguments using the library 'argsparse'. It can manage two types of configuration, global and repeated. It's able to save, if defined, the configurations in an external yaml file.
Repeated settings means that, in a single yaml file, the same group of configurations can be saved multiple times. Global, or non-repeated settings, means that the same group of configurations can only be saved once.
It also allows for all settings be updated individually or at the same time.
It's also able to have certain methods (commands) associated with certain arguments, meaning that when an argument is inserted, that command will be called.
<a name="features"></a>
## Features
| Feature |
|:-------------------------------------------------|
| uses argsparse |
| save configurations in a yaml file |
| saved configurations can be updated individually |
| associate methods to specific argument |
Any new features are **_very_** welcomed.
### Future features
- Currently, there's only the option to use the argsparse library as a way to write command line interfaces. In the future, it will also be able to choose another type of command-line interface writer, such as 'click' library.
- Inserting multiple values in the main argument will update specified configurations on all main arguments in RepeatableSettings.
<a name="prerequisites"></a>
## Prerequisites
[Python 3](https://www.python.org/downloads/) must be installed.
<a name="installation"></a>
## Installation
```
pip --no-cache-dir install margument
```
or,
```
pip3 --no-cache-dir install margument
```
<a name="usage"></a>
## Usage
All examples showed below are taken from the [progscheduler](https://github.com/zaytiri/program-scheduler/tree/main/progscheduler/settings) package. For a working example please refer to this package.
This library needs an instance of argsparse. Almost all argsparse configurations will not be done by this library, it only uses its features, so the following code (or similar) is needed.
```python
import argparse
args = argparse.ArgumentParser()
args.add_argument('--version', action='version', version='%(prog)s ' + str(get_version())) # optional
```
There's two types of configurations and the program can have as much as necessary. Each configuration corresponds to a different external yaml file.
- **Repeatable settings** means defining a group of configurations that can be saved multiple times, ina yaml file, under different names (main argument).
- One of the arguments must be a main argument, meaning that this argument's value (from the user) will be the name of a specific group of configurations and can be used (by the user) to update that specific setting or delete it.
- **Non-Repeatable settings** means that all defined configurations will appear only once in the yaml file.
An Options class can also be provided containing different type of options when processing the configurations.
```python
class Manager:
def configure_arguments(self):
args = argparse.ArgumentParser()
args.add_argument('--version', action='version', version='%(prog)s ' + str(get_version())) # optional
# manage repeatable configurations
repeatable = Repeatable()
repeatable_config_file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'local.yaml') # file will be saved in the same folder as the current python file
local_settings = RepeatableSettings(path=repeatable_config_file_path,
program_arguments=repeatable,
options=Options(show_saved=True, save_main_arg_exists=True))
repeatable.are_configs_saved = local_settings.exists()
# manage generic configurations
global_config_file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'global.yaml')
global_settings = NonRepeatableSettings(path=global_config_file_path,
program_arguments=Generic(),
options=Options(show_saved=True, save_different=True))
settings_processor = SettingsProcessor([local_settings, global_settings], args) # the list of all type of configurations defined needs to be pass as argument to process all of them
return settings_processor.run()
```
The following examples applies to all type of configuration files.
It's necessary to have a separate class for each type of configuration (repeatable or non-repeatable) where it will be defined the actual arguments necessary and processed any validations necessary.
Each configuration class needs to inherit from the class 'Arguments' and then be added the configuration of the desired arguments using the 'Argument' class. The name of the variable, the name of the argument and the full name of the argument needs to be exactly the same.
```python
class Repeatable(Arguments):
def __init__(self):
self.alias = Argument(name='alias',
abbreviation_name='-a',
full_name='--alias',
help_message='A UNIQUE alias for the file to be scheduled. When creating and/or updating any configurations, '
'this alias needs to be present.',
metavar="",
to_save=True,
is_main=True) # is_main = True means 'alias' is a main argument. This will set this group of configurations under this value.
```
The following method needs to be implemented, and it will add each argument into the 'argsparse'.
```python
import argparse
class Repeatable(Arguments):
# (...)
def add_arguments(self, args_parser):
args_parser.add_argument(self.alias.abbreviation_name, self.alias.full_name,
required=not self.are_configs_saved,
help=self.alias.help_message,
metavar=self.alias.metavar,
default=argparse.SUPPRESS)
```
The following is an example of the definition of a global argument using commands.
```python
class Generic(Arguments):
def __init__(self):
self.schedules = Argument(name='schedules',
abbreviation_name='-lsch',
full_name='--schedules',
help_message='list all saved scheduled jobs. example: -lsch',
metavar="",
command=Commands.get_configs, # 'Commands' is a separate class only for defining commands needed for the arguments
default=False)
```
This method can also be implemented if any type of validation is necessary after the arguments are parsed and/or the configuration file has been read. In this method is also possible to associate the arguments for any method/command that needs to have arguments depending on arguments parsed.
```python
class Repeatable(Arguments):
# (...)
def process_arguments(self, settings):
pass
```
When calling the configure_arguments() method, th library will process configurations, save them if needed and return all updated configurations either from the external yaml file itself or the arguments given by the user.
```python
manager = Manager()
arguments = manager.configure_arguments()
```
<a name="support"></a>
## Support
If any problems occurs, feel free to open an issue.
<a name="license"></a>
## License
[MIT](https://choosealicense.com/licenses/mit/)
<a name="status"></a>
## Status
Currently maintaining it.
Raw data
{
"_id": null,
"home_page": "https://github.com/zaytiri/settings-manager",
"name": "margument",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10.6",
"maintainer_email": "",
"keywords": "manager,configurations,settings,arguments,argparse,yaml,save",
"author": "zaytiri",
"author_email": "",
"download_url": "",
"platform": null,
"description": "[](https://pepy.tech/project/margument)\n\n# Margument - Settings Manager\n\n## Table of Contents\n\n- [Description](#description)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Support](#support)\n- [License](#license)\n- [Status](#status)\n\n<a name=\"description\"></a>\n\n## Description\n\nMargument can manage configurations based on given program arguments using the library 'argsparse'. It can manage two types of configuration, global and repeated. It's able to save, if defined, the configurations in an external yaml file.\n\nRepeated settings means that, in a single yaml file, the same group of configurations can be saved multiple times. Global, or non-repeated settings, means that the same group of configurations can only be saved once.\n\nIt also allows for all settings be updated individually or at the same time.\n\nIt's also able to have certain methods (commands) associated with certain arguments, meaning that when an argument is inserted, that command will be called.\n\n<a name=\"features\"></a>\n\n## Features\n\n| Feature |\n|:-------------------------------------------------|\n| uses argsparse |\n| save configurations in a yaml file |\n| saved configurations can be updated individually |\n| associate methods to specific argument |\n\n\nAny new features are **_very_** welcomed.\n\n### Future features\n\n- Currently, there's only the option to use the argsparse library as a way to write command line interfaces. In the future, it will also be able to choose another type of command-line interface writer, such as 'click' library.\n- Inserting multiple values in the main argument will update specified configurations on all main arguments in RepeatableSettings.\n\n<a name=\"prerequisites\"></a>\n\n## Prerequisites\n\n[Python 3](https://www.python.org/downloads/) must be installed.\n\n<a name=\"installation\"></a>\n\n## Installation\n\n```\npip --no-cache-dir install margument\n```\n\nor,\n\n```\npip3 --no-cache-dir install margument\n```\n\n<a name=\"usage\"></a>\n\n## Usage\n\nAll examples showed below are taken from the [progscheduler](https://github.com/zaytiri/program-scheduler/tree/main/progscheduler/settings) package. For a working example please refer to this package.\n\nThis library needs an instance of argsparse. Almost all argsparse configurations will not be done by this library, it only uses its features, so the following code (or similar) is needed.\n```python\nimport argparse\n\nargs = argparse.ArgumentParser()\nargs.add_argument('--version', action='version', version='%(prog)s ' + str(get_version())) # optional\n```\n\nThere's two types of configurations and the program can have as much as necessary. Each configuration corresponds to a different external yaml file.\n\n- **Repeatable settings** means defining a group of configurations that can be saved multiple times, ina yaml file, under different names (main argument).\n - One of the arguments must be a main argument, meaning that this argument's value (from the user) will be the name of a specific group of configurations and can be used (by the user) to update that specific setting or delete it.\n- **Non-Repeatable settings** means that all defined configurations will appear only once in the yaml file.\n\nAn Options class can also be provided containing different type of options when processing the configurations.\n```python\nclass Manager:\n def configure_arguments(self):\n args = argparse.ArgumentParser()\n args.add_argument('--version', action='version', version='%(prog)s ' + str(get_version())) # optional\n\n # manage repeatable configurations\n repeatable = Repeatable()\n repeatable_config_file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'local.yaml') # file will be saved in the same folder as the current python file\n local_settings = RepeatableSettings(path=repeatable_config_file_path,\n program_arguments=repeatable,\n options=Options(show_saved=True, save_main_arg_exists=True))\n repeatable.are_configs_saved = local_settings.exists()\n \n # manage generic configurations\n global_config_file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'global.yaml')\n global_settings = NonRepeatableSettings(path=global_config_file_path,\n program_arguments=Generic(),\n options=Options(show_saved=True, save_different=True))\n \n settings_processor = SettingsProcessor([local_settings, global_settings], args) # the list of all type of configurations defined needs to be pass as argument to process all of them\n return settings_processor.run()\n```\n\nThe following examples applies to all type of configuration files.\nIt's necessary to have a separate class for each type of configuration (repeatable or non-repeatable) where it will be defined the actual arguments necessary and processed any validations necessary. \nEach configuration class needs to inherit from the class 'Arguments' and then be added the configuration of the desired arguments using the 'Argument' class. The name of the variable, the name of the argument and the full name of the argument needs to be exactly the same.\n```python\nclass Repeatable(Arguments):\n def __init__(self):\n self.alias = Argument(name='alias',\n abbreviation_name='-a',\n full_name='--alias',\n help_message='A UNIQUE alias for the file to be scheduled. When creating and/or updating any configurations, '\n 'this alias needs to be present.',\n metavar=\"\",\n to_save=True,\n is_main=True) # is_main = True means 'alias' is a main argument. This will set this group of configurations under this value.\n```\n\nThe following method needs to be implemented, and it will add each argument into the 'argsparse'.\n```python\nimport argparse\n\nclass Repeatable(Arguments):\n # (...)\n def add_arguments(self, args_parser):\n args_parser.add_argument(self.alias.abbreviation_name, self.alias.full_name,\n required=not self.are_configs_saved,\n help=self.alias.help_message,\n metavar=self.alias.metavar,\n default=argparse.SUPPRESS)\n```\n\nThe following is an example of the definition of a global argument using commands.\n```python\nclass Generic(Arguments):\n def __init__(self):\n self.schedules = Argument(name='schedules',\n abbreviation_name='-lsch',\n full_name='--schedules',\n help_message='list all saved scheduled jobs. example: -lsch',\n metavar=\"\",\n command=Commands.get_configs, # 'Commands' is a separate class only for defining commands needed for the arguments\n default=False)\n```\n\nThis method can also be implemented if any type of validation is necessary after the arguments are parsed and/or the configuration file has been read. In this method is also possible to associate the arguments for any method/command that needs to have arguments depending on arguments parsed.\n```python\nclass Repeatable(Arguments):\n # (...)\n def process_arguments(self, settings):\n pass\n```\n\nWhen calling the configure_arguments() method, th library will process configurations, save them if needed and return all updated configurations either from the external yaml file itself or the arguments given by the user.\n```python\nmanager = Manager()\narguments = manager.configure_arguments()\n```\n\n<a name=\"support\"></a>\n\n## Support\n\nIf any problems occurs, feel free to open an issue.\n\n<a name=\"license\"></a>\n\n## License\n\n[MIT](https://choosealicense.com/licenses/mit/)\n\n<a name=\"status\"></a>\n\n## Status\n\nCurrently maintaining it.\n",
"bugtrack_url": null,
"license": "",
"summary": "python library to manage configurations from program arguments including doing commands and saving configurations in a yaml file.",
"version": "1.1.4",
"project_urls": {
"Changelog": "https://github.com/zaytiri/settings-manager/blob/main/CHANGELOG.md",
"GitHub": "https://github.com/zaytiri/settings-manager",
"Homepage": "https://github.com/zaytiri/settings-manager"
},
"split_keywords": [
"manager",
"configurations",
"settings",
"arguments",
"argparse",
"yaml",
"save"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "46cfec4c95a68396740a676206905fca9077f1bc5cfd51fe4c56d8704ada8694",
"md5": "afb5aa5a6fe4666ee4c6b357e78684e3",
"sha256": "430b93fc413b5567dd161fc4460616e0058f7b1064853bcce5df5d038f15bbe1"
},
"downloads": -1,
"filename": "margument-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "afb5aa5a6fe4666ee4c6b357e78684e3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10.6",
"size": 12223,
"upload_time": "2023-09-13T21:56:20",
"upload_time_iso_8601": "2023-09-13T21:56:20.525315Z",
"url": "https://files.pythonhosted.org/packages/46/cf/ec4c95a68396740a676206905fca9077f1bc5cfd51fe4c56d8704ada8694/margument-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-13 21:56:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zaytiri",
"github_project": "settings-manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "margument"
}
JSON
