# ⚔️ Heracless ⚔️
A simple and minimalistic Config Manager using YAML.
[](https://github.com/felixscode/heracless)
[](https://pypi.org/project/heracless/)
[](https://heracless.io/Documentation)
## Table of Contents
- [Description](#description)
- [Installation](#installation)
- [Setup](#setup)
- [CLI Tool](#cli-tool)
- [Helper Functions in Heracless](#helper-functions-in-heracless)
- [mutate_config](#mutate_config)
- [as_dict](#as_dict)
- [from_dict](#from_dict)
- [Version](#version)
- [Future](#future)
- [Author](#author)
## Description
Heracless aims to make working with config files in Python easy. It parses a config file into a dataclass and creates types as a Python stub file (.pyi) which can be used for type hints. Generated types also make autocompletion dreamy!
## Installation
Heracless is available as a pip package:
```bash
pip install heracless
```
If you want to build from source, run:
```bash
git clone https://github.com/felixscode/heracless.git
cd heracless
pip install -e .
```
## Setup
First, create a `config.yaml` file in a desired location and add desired configs. Make a new Python file called `load_config.py` and put it somewhere into your project.
Here is an example project structure:
```
├── src
│ └── your_module
│ ├── main.py
│ └──utils
│ └── load_config.py
├── data
│ └── config.yaml
├── README.md
├── pyproject.toml
└── .gitignore
```
Paste the following code into your `load_config.py`:
```python
from pathlib import Path
from typing import TypeVar
from heracless import load_config as _load_config
# CONFIG_YAML_PATH is a global variable that sets the path of your yaml config file
# Edit this to your config file path
CONFIG_YAML_PATH = None
Config = TypeVar("Config")
def load_config(config_path : Path|str = CONFIG_YAML_PATH,frozen: bool = True,stub_dump:bool = True) -> Config:
"""
Load the configuration from the specified directory and return a Config object.
Args:
config_path (Path|str, optional): The path to the configuration file. Defaults to CONFIG_YAML_PATH.
frozen (bool, optional): Whether the configuration should be frozen. Defaults to True.
stub_dump (bool, optional): Whether to dump a stub file for typing support or not. Defaults to True.
Returns:
Config: The loaded configuration object.
Raises:
FileNotFoundError: If the configuration file does not exist.
yaml.YAMLError: If there is an error parsing the YAML configuration file.
Note:
CONFIG_YAML_PATH is a global variable that sets the path of your YAML config file.
"""
file_path = Path(__file__).resolve() if stub_dump else None
return _load_config(config_path, file_path, frozen=frozen)
```
After creating the `load_config.py` file, set the `CONFIG_YAML_PATH` variable to the path of your `config.yaml` file. For example:
```python
CONFIG_YAML_PATH = "/path/to/your/config.yaml"
```
## Helper Functions in Heracless
This document describes the helper functions in the `helper.py` module of the Heracless project.
### `mutate_config`
This function takes a `Config` object, a name, and a value, and returns a new `Config` object with the value at the name updated.
```python
from your_project import load_config
from heracless.utils.helper import mutate_config
config = load_config()
new_config = mutate_config(config, "name", "new_value")
```
### `as_dict`
This function converts a `Config` object to a dictionary.
```python
from your_project import load_config
from heracless.utils.helper import as_dict
config = load_config()
config_dict = as_dict(config)
```
### `from_dict`
This function creates a `Config` object from a dictionary. You can specify whether the `Config` object should be frozen.
```python
from heracless.utils.helper import from_dict
config_dict = {...} # A dictionary representing the configuration
config = from_dict(config_dict, frozen=True)
```
## Version
Heracless 0.4 <br>
Written in Python 3.11
## Future
- [ ] Add config variants
- [x] Add None type support
- [x] Web app
# Development Environment
in Order to install all dependcies install the optinal [dev] dependcies.
```bash
git clone ...
cd heracless
pip install -e .[dev]
```
## Author
Felix Schelling<br>
GitHub: [felixscode](https://github.com/felixscode)<br>
Website: [heracless.io](https://heracless.io)<br>
Personal website: [felixschelling.de](https://felixschelling.de)<br>
Written with ❤️ in Mexico
Raw data
{
"_id": null,
"home_page": null,
"name": "heracless",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "YAML, Dataclass, Config, config, config management",
"author": null,
"author_email": "Felix Schelling <felix.schelling@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/eb/2e/a7d90b7ad912b8a36c7f799fcf710a288aac7420785ba3d7046b60604104/heracless-0.3.3.tar.gz",
"platform": null,
"description": "# \u2694\ufe0f Heracless \u2694\ufe0f\n\nA simple and minimalistic Config Manager using YAML. \n[](https://github.com/felixscode/heracless)\n[](https://pypi.org/project/heracless/)\n[](https://heracless.io/Documentation)\n \n\n## Table of Contents\n- [Description](#description)\n- [Installation](#installation)\n- [Setup](#setup)\n- [CLI Tool](#cli-tool)\n- [Helper Functions in Heracless](#helper-functions-in-heracless)\n - [mutate_config](#mutate_config)\n - [as_dict](#as_dict)\n - [from_dict](#from_dict)\n- [Version](#version)\n- [Future](#future)\n- [Author](#author)\n\n## Description\n\nHeracless aims to make working with config files in Python easy. It parses a config file into a dataclass and creates types as a Python stub file (.pyi) which can be used for type hints. Generated types also make autocompletion dreamy!\n\n## Installation\n\nHeracless is available as a pip package:\n\n```bash\npip install heracless\n```\n\nIf you want to build from source, run:\n\n```bash\ngit clone https://github.com/felixscode/heracless.git\ncd heracless\npip install -e .\n```\n\n## Setup\n\nFirst, create a `config.yaml` file in a desired location and add desired configs. Make a new Python file called `load_config.py` and put it somewhere into your project.\nHere is an example project structure:\n```\n\u251c\u2500\u2500 src\n\u2502 \u2514\u2500\u2500 your_module\n\u2502 \u251c\u2500\u2500 main.py\n\u2502 \u2514\u2500\u2500utils\n\u2502 \u2514\u2500\u2500 load_config.py\n\u251c\u2500\u2500 data\n\u2502 \u2514\u2500\u2500 config.yaml\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 .gitignore\n\n```\n\n\nPaste the following code into your `load_config.py`:\n\n```python\nfrom pathlib import Path\nfrom typing import TypeVar\n\nfrom heracless import load_config as _load_config\n\n# CONFIG_YAML_PATH is a global variable that sets the path of your yaml config file\n# Edit this to your config file path\nCONFIG_YAML_PATH = None\n\nConfig = TypeVar(\"Config\")\n\n\ndef load_config(config_path : Path|str = CONFIG_YAML_PATH,frozen: bool = True,stub_dump:bool = True) -> Config:\n \"\"\"\n Load the configuration from the specified directory and return a Config object.\n\n Args:\n config_path (Path|str, optional): The path to the configuration file. Defaults to CONFIG_YAML_PATH.\n frozen (bool, optional): Whether the configuration should be frozen. Defaults to True.\n stub_dump (bool, optional): Whether to dump a stub file for typing support or not. Defaults to True.\n\n Returns:\n Config: The loaded configuration object.\n\n Raises:\n FileNotFoundError: If the configuration file does not exist.\n yaml.YAMLError: If there is an error parsing the YAML configuration file.\n\n Note:\n CONFIG_YAML_PATH is a global variable that sets the path of your YAML config file.\n \"\"\"\n\n file_path = Path(__file__).resolve() if stub_dump else None\n return _load_config(config_path, file_path, frozen=frozen)\n```\n\nAfter creating the `load_config.py` file, set the `CONFIG_YAML_PATH` variable to the path of your `config.yaml` file. For example:\n\n```python\nCONFIG_YAML_PATH = \"/path/to/your/config.yaml\"\n```\n\n\n## Helper Functions in Heracless\n\nThis document describes the helper functions in the `helper.py` module of the Heracless project.\n\n### `mutate_config`\n\nThis function takes a `Config` object, a name, and a value, and returns a new `Config` object with the value at the name updated.\n\n```python\nfrom your_project import load_config\n\nfrom heracless.utils.helper import mutate_config\n\nconfig = load_config()\nnew_config = mutate_config(config, \"name\", \"new_value\")\n```\n\n### `as_dict`\n\nThis function converts a `Config` object to a dictionary.\n\n```python\nfrom your_project import load_config\n\nfrom heracless.utils.helper import as_dict\n\nconfig = load_config()\nconfig_dict = as_dict(config)\n```\n\n### `from_dict`\n\nThis function creates a `Config` object from a dictionary. You can specify whether the `Config` object should be frozen.\n\n```python\nfrom heracless.utils.helper import from_dict\n\nconfig_dict = {...} # A dictionary representing the configuration\nconfig = from_dict(config_dict, frozen=True)\n```\n\n## Version\n\nHeracless 0.4 <br>\nWritten in Python 3.11\n\n## Future\n\n- [ ] Add config variants\n- [x] Add None type support\n- [x] Web app\n\n\n# Development Environment\n\nin Order to install all dependcies install the optinal [dev] dependcies.\n```bash\ngit clone ...\ncd heracless\npip install -e .[dev]\n```\n\n## Author\n\nFelix Schelling<br>\nGitHub: [felixscode](https://github.com/felixscode)<br>\nWebsite: [heracless.io](https://heracless.io)<br>\nPersonal website: [felixschelling.de](https://felixschelling.de)<br>\nWritten with \u2764\ufe0f in Mexico\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Yaml to Dataclass parser for Config files",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://heracless.io",
"Repository": "https://github.com/felixscode/heracless.git"
},
"split_keywords": [
"yaml",
" dataclass",
" config",
" config",
" config management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4f7530eee91a1a1c70dca2c3239c69b3d2652b418d6c638caa3f07c82c57c7ab",
"md5": "6f03048b5e0cdb31bd13d5f3f7420b4c",
"sha256": "36fa61d7cadb30b8f34b90fa4e837f233dfa7ac765fbc0c939822cd8e5480940"
},
"downloads": -1,
"filename": "heracless-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6f03048b5e0cdb31bd13d5f3f7420b4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 21698,
"upload_time": "2025-02-23T11:10:41",
"upload_time_iso_8601": "2025-02-23T11:10:41.625464Z",
"url": "https://files.pythonhosted.org/packages/4f/75/30eee91a1a1c70dca2c3239c69b3d2652b418d6c638caa3f07c82c57c7ab/heracless-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "eb2ea7d90b7ad912b8a36c7f799fcf710a288aac7420785ba3d7046b60604104",
"md5": "dcf5518f60b7baf1f90aa87a9408bdf9",
"sha256": "b3e8811dff42ea597037b0966386e221b33dedc27c2bd1af7821ac9b687778de"
},
"downloads": -1,
"filename": "heracless-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "dcf5518f60b7baf1f90aa87a9408bdf9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16575,
"upload_time": "2025-02-23T11:10:43",
"upload_time_iso_8601": "2025-02-23T11:10:43.656375Z",
"url": "https://files.pythonhosted.org/packages/eb/2e/a7d90b7ad912b8a36c7f799fcf710a288aac7420785ba3d7046b60604104/heracless-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 11:10:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "felixscode",
"github_project": "heracless",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "heracless"
}
JSON
