heracless 0.2.2__tar.gz → 0.3.0__tar.gz

heracless-0.3.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.1
+Name: heracless
+Version: 0.3.0
+Summary: Yaml to Dataclass parser for Config files
+Author-email: Felix Schelling <felix.schelling@protonmail.com>
+Project-URL: Repository, https://github.com/felixscode/heracless.git
+Project-URL: Homepage, https://heracless.io
+Keywords: YAML,Dataclass,Config,config,config management
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: black
+Requires-Dist: pytest
+Requires-Dist: PyYAML
+Requires-Dist: art
+Requires-Dist: streamlit
+Requires-Dist: streamlit_ace
+
+# ⚔️ Heracless ⚔️
+
+A simple and minimalistic Config Manager using YAML.
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/felixscode/heracless)
+[![PyPi](https://img.shields.io/badge/PyPi-Package-blue?logo=pypi)](https://pypi.org/project/heracless/)
+[![Documentation](https://img.shields.io/badge/Documentation-Read-green?logo=readthedocs)](https://heracless.io/docs)
+    
+
+## 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 Type, 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(frozen: bool = True) -> Config:
+    """
+    Load the configuration from the specified directory and return a Config object.
+
+    Args:
+        frozen (bool, optional): Whether the configuration should be frozen. 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()
+    yaml_config_path = CONFIG_YAML_PATH
+    return _load_config(file_path, yaml_config_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
+- [ ] Add None type support
+- [x] Web app
+
+## 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
+
+

heracless-0.3.0/README.md

@@ -0,0 +1,165 @@
+# ⚔️ Heracless ⚔️
+
+A simple and minimalistic Config Manager using YAML.
+[![GitHub](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/felixscode/heracless)
+[![PyPi](https://img.shields.io/badge/PyPi-Package-blue?logo=pypi)](https://pypi.org/project/heracless/)
+[![Documentation](https://img.shields.io/badge/Documentation-Read-green?logo=readthedocs)](https://heracless.io/docs)
+    
+
+## 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 Type, 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(frozen: bool = True) -> Config:
+    """
+    Load the configuration from the specified directory and return a Config object.
+
+    Args:
+        frozen (bool, optional): Whether the configuration should be frozen. 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()
+    yaml_config_path = CONFIG_YAML_PATH
+    return _load_config(file_path, yaml_config_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
+- [ ] Add None type support
+- [x] Web app
+
+## 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
+
+

heracless-0.3.0/heracless/__init__.py

@@ -0,0 +1,4 @@
+from heracless.cli_tool import run_cli as _run_cli
+from heracless.fight import fight as load_config
+if __name__ == "__main__":
+    _run_cli()

{heracless-0.2.2 → heracless-0.3.0}/heracless/cli_tool.py

@@ -1,12 +1,13 @@
 import argparse
-from heracless.main import main, dump_in_console, dump_in_file
-from yaml import full_load
 import os
-import yaml
-from art import text2art
 import sys
 from typing import Optional
 
+from art import text2art
+from yaml import full_load
+
+from heracless.fight import dump_in_console, dump_in_file
+
 
 def parse_args() -> argparse.Namespace:
     """

heracless-0.3.0/heracless/fight.py

@@ -0,0 +1,133 @@
+"""
+heracless YAML TO PyObject parser
+
+"""
+
+import os
+from pathlib import Path
+from typing import Callable, Optional, Any
+
+from yaml import full_load
+
+from heracless.utils.cfg_tree import (Tree, tree_parser, tree_to_config_obj,
+                                      tree_to_string_translator)
+from heracless.utils.utils import path_exists
+from heracless.utils.exceptions import YamlSyntaxError
+
+DEFAULT_DIR = Path("./config/config.yaml")
+
+
+def load_as_dict(cfg_dir: Path, yaml_load_func: Callable[[Any], dict]) -> dict:
+    """
+    Load a YAML configuration file and return it as a dictionary.
+
+    :param cfg_dir: Path to the YAML configuration file.
+    :param yaml_load_func: Function to load YAML content.
+    :return: Dictionary representation of the YAML content.
+    :raises ValueError: If the config file is empty.
+    :raises FileNotFoundError: If the config file does not exist.
+    :raises OSError: If there is an issue reading the file.
+    """
+    path_exists(cfg_dir)
+    if os.stat(cfg_dir).st_size == 0:
+        raise ValueError("Empty config file")
+    stream = open(cfg_dir, "r")
+    try:
+        return yaml_load_func(stream)
+    except Exception as e:
+        raise YamlSyntaxError(str(e))
+
+
+def dump_in_console(frozen: bool, _: Any, cfg_tree: Tree, *args: Any, **kwargs: Any) -> None:
+    """
+    Console dumper: prints generated config object type into console.
+
+    :param frozen: Whether the config object is frozen.
+    :param _: Unused parameter.
+    :param cfg_tree: Configuration tree.
+    :param args: Additional arguments.
+    :param kwargs: Additional keyword arguments.
+    """
+    print(tree_to_string_translator(frozen, cfg_tree))
+
+
+def dump_dummy(*args: Any, **kwargs: Any) -> None:
+    """
+    Dummy dumper: can be used to bypass dumping.
+
+    :param args: Additional arguments.
+    :param kwargs: Additional keyword arguments.
+    """
+
+
+def dump_in_file(frozen: bool, cfg_tree: Tree, dump_dir: Path) -> None:
+    """
+    File dumper: dumps config types into a file.
+
+    :param frozen: Whether the config object is frozen.
+    :param cfg_tree: Configuration tree.
+    :param dump_dir: Directory to dump the config file.
+    :raises FileNotFoundError: If the dump directory does not exist.
+    :raises OSError: If there is an issue writing to the file.
+    """
+    if not dump_dir.suffix == ".pyi":
+        dump_dir = dump_dir.with_suffix(".pyi")
+    path_exists(dump_dir)
+    with open(dump_dir, "w") as dd:
+        string = tree_to_string_translator(frozen, cfg_tree)
+        dd.write(string)
+
+
+def _fight_hydra(
+    cfg_dir: Path,
+    dump_dir: Path,
+    dump_func: Callable[[bool, Tree, Path], None],
+    yaml_load_func: Callable[[Any], dict],
+    frozen: bool,
+) -> Optional[Any]:
+    """
+    Internal function to parse YAML config and dump it using the specified function.
+
+    :param cfg_dir: Path to the YAML configuration file.
+    :param dump_dir: Directory to dump the config file.
+    :param dump_func: Function to dump the config.
+    :param yaml_load_func: Function to load YAML content.
+    :param frozen: Whether the config object is frozen.
+    :return: Configuration object or None if the config is empty.
+    :raises ValueError: If the config file is empty.
+    :raises FileNotFoundError: If the config file does not exist.
+    :raises OSError: If there is an issue reading the file.
+    """
+    cfg_dict = load_as_dict(cfg_dir, yaml_load_func)
+    if cfg_dict is None:  # in case dict is empty and config
+        return None
+    cfg_tree = tree_parser(cfg_dict)
+    dump_func(
+        frozen,
+        cfg_tree,
+        dump_dir,
+    )
+    config_obj = tree_to_config_obj(frozen, cfg_tree)
+    return config_obj
+
+
+def fight(cfg_dir: Path, dump_dir: Path, frozen: bool) -> Optional[Any]:
+    """
+    Parse YAML config and dump it into a file.
+
+    :param cfg_dir: Path to the YAML configuration file.
+    :param dump_dir: Directory to dump the config file.
+    :param frozen: Whether the config object is frozen.
+    :return: Configuration object or None if the config is empty.
+    :raises ValueError: If the config file is empty.
+    :raises FileNotFoundError: If the config file does not exist.
+    :raises OSError: If there is an issue reading the file.
+    """
+    dump_func = dump_in_file
+    yaml_load_func = full_load
+    return _fight_hydra(cfg_dir, dump_dir, dump_func, yaml_load_func, frozen)
+
+
+if __name__ == "__main__":
+    cfg = fight(DEFAULT_DIR, Path("./tmp/test_file.py"), True)
+    print(cfg)

heracless-0.3.0/heracless/utils/__init__.py

@@ -0,0 +1 @@
+from heracless.utils.helper import as_dict, from_dict, mutate_config