Initial release 1.0.0

Author: GilbN

.gitignore

@@ -50,6 +50,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
+*config/
 
 # Translations
 *.mo
@@ -123,7 +124,7 @@ celerybeat.pid
 .env
 .venv
 env/
-venv/
+venv*/
 ENV/
 env.bak/
 venv.bak/

README.md

@@ -1,2 +1,65 @@
-# Simple-TOML-Configurator
-A versatile Python library designed to streamline the handling and organization of configuration settings across various types of applications. This library facilitates the management of configuration values through a user-friendly interface and stores these settings in TOML file format for easy readability and accessibility.
+# Simple TOML Configurator
+
+The **Simple TOML Configurator** is a versatile Python library designed to streamline the handling and organization of configuration settings across various types of applications. This library facilitates the management of configuration values through a user-friendly interface and stores these settings in TOML file format for easy readability and accessibility.
+
+## Features
+
+1. **Effortless Configuration Management:** The heart of the library is the `Configuration` class, which simplifies the management of configuration settings. It provides intuitive methods to load, update, and store configurations, ensuring a smooth experience for developers.
+
+2. **Universal Applicability:** The **Simple TOML Configurator** is designed to work seamlessly with any type of Python application, ranging from web frameworks like Flask, Django, and FastAPI to standalone scripts and command-line utilities.
+
+3. **TOML File Storage:** Configuration settings are stored in TOML files, a popular human-readable format. This enables developers to review, modify, and track configuration changes easily.
+
+4. **Attribute-Based Access:** Accessing configuration values is straightforward, thanks to the attribute-based approach. Settings can be accessed and updated as attributes, making it convenient for both reading and modifying values.
+
+5. **Updating Configurations:** The library enables the updating of configuration settings from a dictionary, ensuring that the changes are accurately reflected both in-memory and in the stored TOML file.
+
+6. **Default Values:** Developers can define default values for various configuration sections and keys. The library automatically incorporates new values and manages the removal of outdated ones.
+
+7. **Customization Capabilities:** The `Configuration` class can be extended and customized to cater to application-specific requirements. Developers can implement custom logic with getters and setters to handle unique settings or scenarios.
+
+## Usage Example
+
+```python
+from simple_toml_configurator import Configuration
+
+# Define default configuration values
+default_config = {
+    "app": {
+        "ip": "0.0.0.0",
+        "host": "",
+        "port": 5000,
+        "upload_folder": "uploads"
+    }
+    "mysql": {
+        "user": "root",
+        "password": "root"
+        "databases": {
+            "prod": "db1",
+            "dev": "db2"
+            }
+    }
+}
+
+# Initialize the Simple TOML Configurator
+settings = Configuration()
+settings.init_config("config", default_config, "app_config")
+# Stores an app_config.toml file in the `config` folder at the current working directory.
+
+# Access and update configuration values
+print(settings.app_ip)  # Output: '0.0.0.0'
+settings.update_config({"app_ip": "1.2.3.4"})
+print(settings.app_ip)  # Output: '1.2.3.4'
+
+# Access all settings as a dictionary
+all_settings = settings.get_settings()
+print(all_settings)
+# Output: {'app_ip': '1.2.3.4', 'app_host': '', 'app_port': 5000, 'app_upload_folder': 'uploads'}
+
+# Modify values directly in the config dictionary
+settings.config["mysql"]["databases"]["prod"] = "db3"
+settings.update()
+print(settings.mysql_databases["prod"])  # Output: 'db3'
+```
+
+The **Simple TOML Configurator** empowers developers to efficiently manage configuration settings across a wide range of Python applications. Whether you're building a web application, a command-line tool, or a standalone script, this library provides the tools you need to maintain and access configuration values with ease and clarity.

changelog.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog],
+and this project adheres to [Semantic Versioning].
+
+## [Unreleased]
+
+- /
+
+## [1.0.0] - 2023-08-27
+
+- initial release
+
+<!-- Links -->
+[keep a changelog]: https://keepachangelog.com/en/1.0.0/
+[semantic versioning]: https://semver.org/spec/v2.0.0.html
+
+<!-- Versions -->
+[unreleased]: https://github.com/gilbn/simple-toml-configurator/compare/v0.0.2...HEAD
+[1.0.0]: https://github.com/gilbn/simple-toml-configurator/releases/tag/v0.0.1

docs/configurator.md

@@ -0,0 +1,2 @@
+# Simple TOML Configurator Docs
+::: src.simple_toml_configurator.toml_configurator

docs/css/code_select.css

@@ -0,0 +1,4 @@
+.language-pycon .gp, .language-pycon .go { /* Generic.Prompt, Generic.Output */
+    -webkit-user-select: none;
+    user-select: none;
+}

docs/examples.md

@@ -0,0 +1,2 @@
+# Exceptions
+::: src.simple_toml_configurator.exceptions

docs/exceptions.md

@@ -0,0 +1,55 @@
+# Custom Flask Example
+
+The `Configuration` class can be extended and customized to cater to application-specific requirements. Developers can implement custom logic with getters and setters to handle unique settings or scenarios.
+
+## Folder contents
+
+```
+├── __init__.py
+├── app.py
+├── utils.py
+└── extenstions
+    └── config.py
+```
+
+This example uses a custom Configuration class in the config.py module that inherits from `Configuration`.
+
+??? example "CustomConfiguration"
+    ```python
+    class CustomConfiguration(Configuration):
+        def __init__(self):
+            super().__init__()
+
+        @property
+        def logging_debug(self):
+            return getattr(self, "_logging_debug")
+
+        @logging_debug.setter
+        def logging_debug(self, value: bool):
+            if not isinstance(value, bool):
+                raise ValueError(f"value must be of type bool not {type(value)}")
+            self._logging_debug = value
+            log_level = "DEBUG" if value else "INFO"
+            configure_logging(log_level)
+    ```
+
+The custom class uses a property with a setter that executes the `configure_logging` function from `utils.py` whenever the logging_debug attribute is updated. Thus setting the log level to "DEBUG" if the value is True.
+
+This will change the log level on you Flask app without restarting it.
+
+### Code examples
+
+??? example "extensions/config.py"
+    ```python title="config.py"
+    --8<-- "examples/custom/extensions/config.py"
+    ```
+
+??? example "utils.py"
+    ```python title="utils.py"
+    --8<-- "examples/custom/utils.py"
+    ```
+
+!!! example "app.py"
+    ```python title="app.py"
+    --8<-- "examples/custom/app.py"
+    ```

docs/flask-custom-example.md

@@ -0,0 +1,24 @@
+# Simple Flask Example
+
+## Folder contents
+
+```
+├── __init__.py
+├── app.py
+└── extenstions
+    └── config.py
+```
+
+This is a simple example using flask showing how to update the TOML configuration 
+
+### Code examples
+
+??? example "extensions/config.py"
+    ```python title="config.py"
+    --8<-- "examples/standard/extensions/config.py"
+    ```
+
+!!! example "app.py"
+    ```python title="app.py"
+    --8<-- "examples/standard/app.py"
+    ```

docs/flask-simple-example.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/index.md

@@ -0,0 +1,25 @@
+# Installation
+
+To use the Simple TOML Configurator in your Python projects, you can install it using the `pip` package manager. The package is available on PyPI (Python Package Index).
+
+## Prerequisites
+
+Before installing, make sure you have Python and `pip` installed on your system. You can check if `pip` is installed by running:
+
+```bash
+pip --version
+```
+
+If `pip` is not installed, follow the [official `pip` installation guide](https://pip.pypa.io/en/stable/installing/) to get it set up.
+
+## Installation Steps
+
+To install the Simple TOML Configurator package, open your terminal or command prompt and run the following command:
+
+```bash
+pip install simple-toml-configurator
+```
+
+This command will download and install the package along with its dependencies. After the installation is complete, you can start using the package in your Python projects.
+
+See [Usage](/usage-examples) or [Examples](flask-simple-example)or  for more information on how to use the package.

docs/installation.md

@@ -0,0 +1,13 @@
+mkdocs>=1.4.0
+mkdocstrings[python]>=0.19.0
+mkdocs-material>=8.5.6
+mkdocs-section-index>=0.3.4
+mkdocs-redirects>=1.0.1
+mkdocs-git-revision-date-localized-plugin
+mkdocs-minify-plugin
+pyspelling
+mkdocs-include-markdown-plugin>=4.0.4
+mkdocs-awesome-pages-plugin>=2.4.0
+mkdocs-macros-plugin>=0.4.18
+pymdown-extensions>=3.3.2
+mike

docs/requirements.txt

@@ -0,0 +1,89 @@
+## Usage Examples
+
+### Initializing Configuration
+
+To get started with the Simple TOML Configurator, you need to initialize the configuration settings using the `init_config` method. This sets up the default values and configuration file paths.
+
+```python
+from simple_toml_configurator import Configuration
+
+# Define default configuration values
+default_config = {
+    "app": {
+        "ip": "0.0.0.0",
+        "host": "",
+        "port": 5000,
+        "upload_folder": "uploads"
+    }
+}
+
+# Initialize the Simple TOML Configurator
+settings = Configuration()
+settings.init_config("config", default_config, "app_config")
+```
+
+### Accessing Configuration Values
+
+You can access configuration values as attributes of the `settings` instance. This attribute-based access makes it straightforward to retrieve settings.
+
+```python
+# Access configuration values
+ip_address = settings.app_ip
+port_number = settings.app_port
+upload_folder = settings.app_upload_folder
+```
+
+### Updating Configuration Settings
+
+Updating configuration settings is seamless with the Simple TOML Configurator. Use the `update_config` method to modify values while ensuring consistency across instances.
+
+```python
+# Update a configuration value
+settings.update_config({"app_ip": "1.2.3.4"})
+```
+
+### Accessing All Settings
+
+Retrieve all configuration settings as a dictionary using the `get_settings` method. This provides an overview of all configured values.
+
+```python
+# Get all configuration settings
+all_settings = settings.get_settings()
+```
+
+### Direct Configuration Modification
+
+You can directly modify configuration values within the `config` dictionary. After making changes, use the `update` method to write the updated configuration to the file.
+
+```python
+# Modify values directly and update configuration
+settings.config["app"]["ip"] = "0.0.0.0"
+settings.update()
+```
+
+### Customization with Inheritance
+
+For advanced use cases, you can create a custom configuration class by inheriting from `Configuration`. This allows you to add custom logic and properties tailored to your application.
+
+```python
+from simple_toml_configurator import Configuration
+
+class CustomConfiguration(Configuration):
+    def __init__(self):
+        super().__init__()
+
+    # Add custom properties with getters and setters
+    @property
+    def custom_setting(self):
+        return getattr(self, "_custom_setting")
+
+    @custom_setting.setter
+    def custom_setting(self, value):
+        # Custom logic for updating custom_setting
+        self._custom_setting = value
+        # Additional actions can be performed here
+
+# Initialize and use the custom configuration
+custom_settings = CustomConfiguration()
+custom_settings.init_config("config", default_config, "custom_config")
+```

docs/usage-examples.md

@@ -0,0 +1,49 @@
+
+from flask import Flask, jsonify, request, url_for,redirect
+from extensions.config import settings
+import logging
+
+logger = logging.getLogger(__name__)
+
+def create_app():
+    app = Flask(__name__)
+    app.config["SECRET_KEY"] = settings.config.get("app").get("flask_secret_key")
+    app.config['APP_PORT'] = settings.config.get("app").get("port")
+    app.config['APP_IP'] = settings.config.get("app").get("ip")
+    app.config['APP_HOST'] = settings.config.get("app").get("host")
+    app.config["DEBUG"] = settings.config.get("app").get("debug")
+    return app
+
+app = create_app()
+
+# simple route that returns the config
+@app.route("/")
+def app_settings():
+    return jsonify(
+        {
+        "response":  {
+            "data": {
+                "configuration": settings.get_settings(),
+                "toml_config": settings.config,
+            }
+        }
+        })
+
+# Update settings route
+@app.route("/update", methods=["POST"])
+def update_settings():
+    """Update settings route"""
+    data = request.get_json() # {"logging_debug": True, "app_debug": True}
+    settings.update_config(data)
+    return redirect(url_for("app_settings"))
+
+# Get settings value route
+@app.route("/logger", methods=["GET"])
+def get_settings():
+    """Sets logging_debug to True or False"""
+    value = False if settings.logging_debug else True
+    settings.update_config({"logging_debug": value})
+    return jsonify({"debug_logging": settings.logging_debug})
+
+if __name__ == "__main__":
+    app.run(port=app.config.get("APP_PORT"), host=app.config.get("APP_IP"), debug=app.config.get("APP_DEBUG"))