ultraconfiguration


Nameultraconfiguration JSON
Version 1.2.0 PyPI version JSON
download
home_pagehttps://github.com/Kawai-Senpai/UltraConfiguration
SummaryUltraConfiguration is a fast and efficient Python library for loading and managing configuration files with ease.
upload_time2025-02-03 18:39:52
maintainerNone
docs_urlNone
authorRanit Bhowmick
requires_python>=3.7
licenseMIT License with attribution requirement
keywords config configuration json yaml settings
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # UltraConfiguration

A high-performance, thread-safe configuration management library for Python with async support.

![UltraConfiguration Thumbnail](https://github.com/Kawai-Senpai/UltraConfiguration/blob/8f6cc341d9de40b0e70ae71ce2f8df9d58178746/Assets/Ultraconfiguration%20Thumbnail.png)

## Table of Contents
1. Introduction
2. Installation
3. Usage
   - Basic Example
   - Async Example
4. Advantages
5. Limitations
6. Additional Notes
7. Why UltraConfiguration?
8. Handling Multiple Configuration Formats
9. Documentation

## Introduction
UltraConfiguration is designed to provide a fast, thread-safe configuration manager for Python applications of all sizes. It supports JSON/YAML, async operations, and advanced caching to handle loads efficiently.

## Installation
Use pip:
```
pip install ultraconfiguration
```

## Usage
### Basic Example
```python
# Simple usage example
config = UltraConfig("config.json")
print(config.get("database.host", "127.0.0.1"))
config.set("app.debug", True)
config.save_config("my_config.json")
```

### Async Example
```python
import asyncio
from ultraconfiguration import UltraConfig

async def main():
    config = UltraConfig()
    await config.load_config_async("async_config.json")
    print(config.get("server.port", 8000))
    await config.save_config_async("saved_async.json")

asyncio.run(main())
```

## Features

- Thread-safe singleton configuration manager
- Support for JSON and YAML formats
- Nested configuration access using dot notation
- LRU caching for fast repeated access
- Comprehensive error handling and logging
- Type hints for better IDE support
- Optional schema validation
- Pretty-printing support
- Async/Background operations support
- Memory-efficient caching
- Context manager support

## Advantages
- Thread-safe singleton access
- Async I/O for non-blocking operations
- Schema validation with jsonschema
- Comprehensive logging and error handling

## Limitations
- Inherits file system permission constraints
- Schema validation requires additional CPU overhead
- Global singleton pattern might not suit every use case

## Additional Notes
Refer to the examples in the "Examples" folder for more complex scenarios. Logging can be customized, and caching is easily cleared with `config.clear_cache()`.

## Why UltraConfiguration?
UltraConfiguration goes beyond traditional config management libraries by:
- Offering a thread-safe, singleton architecture to avoid concurrency issues.
- Providing seamless async operations for large-scale applications.
- Supporting schema validation to ensure data integrity without manual checks.
- Integrating environment variable overrides for flexible deployments.
- Simplifying nested structure handling through dot-notation key paths.

## Handling Multiple Configuration Formats
UltraConfiguration supports various file formats, including JSON and YAML:
```python
from ultraconfiguration import UltraConfig

# Load JSON config
json_config = UltraConfig("settings.json")

# Load YAML config
yaml_config = UltraConfig("settings.yaml")

# Both are accessed similarly:
value_from_json = json_config.get("some.key", "default")
value_from_yaml = yaml_config.get("another.key", 123)
```
You can also override values using environment variables or custom logic.  
This flexibility enables you to maintain consistent config handling across different projects.

## Documentation
Below is a quick reference to commonly used methods in UltraConfig:
- **UltraConfig(config_file: Optional[str|Path])**  
  Creates or retrieves the global instance; optionally auto-loads a config file.

- **get(key: str, default: Any = None) → Any**  
  Retrieves a nested config value with LRU caching.

- **set(key: str, value: Any, validate: bool = True) → None**  
  Assigns a new value, optionally validating against a JSON schema.

- **load_config(file_path: str|Path, schema_path: Optional[str] = None) → None**  
  Loads configuration from file, optionally applying an external schema.

- **save_config(file_path: str|Path, pretty: bool = True) → None**  
  Saves current configuration to specified file with optional pretty-print.

- **load_config_async(...)** / **save_config_async(...)**  
  Async versions of load and save operations, allowing non-blocking I/O.

- **load_config_background(...)** / **save_config_background(...)**  
  Launches load/save tasks in background threads.

- **clear_cache()**  
  Clears all cached values to ensure fresh lookups.

- **reset()**  
  Discards all config data, returning to a clean state.

- **has_changes()**  
  Checks if the in-memory config differs from what’s on disk.

## Advanced Usage
Use environment variables for dynamic overrides:
```python
import os
from ultraconfiguration import UltraConfig

os.environ['database.host'] = '10.0.0.2'

config = UltraConfig('config.json')
host = config.get('database.host', '127.0.0.1')
print(f"Host overridden by environment: {host}")
```

Schema validation example:
```python
# ...existing code...
schema_path = 'config_schema.json'
config.load_config('config.json', schema_path=schema_path)
# ...existing code...
```

## Frequently Asked Questions
1. **Does UltraConfig work in multi-process environments?**  
   UltraConfig is primarily designed for single-process usage. For multi-process setups, consider shared memory or database-backed solutions.
   
2. **How do I reset configurations at runtime?**  
   Simply call `config.reset()` to clear the internal dictionaries.

3. **Is there a performance impact with validation?**  
   Yes, validation can add overhead. Disable it when performance is critical and you trust the input.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/Kawai-Senpai/UltraConfiguration",
    "name": "ultraconfiguration",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "Config, Configuration, JSON, YAML, Settings",
    "author": "Ranit Bhowmick",
    "author_email": "bhowmickranitking@duck.com",
    "download_url": "https://files.pythonhosted.org/packages/f6/d7/56c6a5d50c4b14556583711b80db0f60205407f0581b26bef7d98b179c23/ultraconfiguration-1.2.0.tar.gz",
    "platform": null,
    "description": "# UltraConfiguration\r\n\r\nA high-performance, thread-safe configuration management library for Python with async support.\r\n\r\n![UltraConfiguration Thumbnail](https://github.com/Kawai-Senpai/UltraConfiguration/blob/8f6cc341d9de40b0e70ae71ce2f8df9d58178746/Assets/Ultraconfiguration%20Thumbnail.png)\r\n\r\n## Table of Contents\r\n1. Introduction\r\n2. Installation\r\n3. Usage\r\n   - Basic Example\r\n   - Async Example\r\n4. Advantages\r\n5. Limitations\r\n6. Additional Notes\r\n7. Why UltraConfiguration?\r\n8. Handling Multiple Configuration Formats\r\n9. Documentation\r\n\r\n## Introduction\r\nUltraConfiguration is designed to provide a fast, thread-safe configuration manager for Python applications of all sizes. It supports JSON/YAML, async operations, and advanced caching to handle loads efficiently.\r\n\r\n## Installation\r\nUse pip:\r\n```\r\npip install ultraconfiguration\r\n```\r\n\r\n## Usage\r\n### Basic Example\r\n```python\r\n# Simple usage example\r\nconfig = UltraConfig(\"config.json\")\r\nprint(config.get(\"database.host\", \"127.0.0.1\"))\r\nconfig.set(\"app.debug\", True)\r\nconfig.save_config(\"my_config.json\")\r\n```\r\n\r\n### Async Example\r\n```python\r\nimport asyncio\r\nfrom ultraconfiguration import UltraConfig\r\n\r\nasync def main():\r\n    config = UltraConfig()\r\n    await config.load_config_async(\"async_config.json\")\r\n    print(config.get(\"server.port\", 8000))\r\n    await config.save_config_async(\"saved_async.json\")\r\n\r\nasyncio.run(main())\r\n```\r\n\r\n## Features\r\n\r\n- Thread-safe singleton configuration manager\r\n- Support for JSON and YAML formats\r\n- Nested configuration access using dot notation\r\n- LRU caching for fast repeated access\r\n- Comprehensive error handling and logging\r\n- Type hints for better IDE support\r\n- Optional schema validation\r\n- Pretty-printing support\r\n- Async/Background operations support\r\n- Memory-efficient caching\r\n- Context manager support\r\n\r\n## Advantages\r\n- Thread-safe singleton access\r\n- Async I/O for non-blocking operations\r\n- Schema validation with jsonschema\r\n- Comprehensive logging and error handling\r\n\r\n## Limitations\r\n- Inherits file system permission constraints\r\n- Schema validation requires additional CPU overhead\r\n- Global singleton pattern might not suit every use case\r\n\r\n## Additional Notes\r\nRefer to the examples in the \"Examples\" folder for more complex scenarios. Logging can be customized, and caching is easily cleared with `config.clear_cache()`.\r\n\r\n## Why UltraConfiguration?\r\nUltraConfiguration goes beyond traditional config management libraries by:\r\n- Offering a thread-safe, singleton architecture to avoid concurrency issues.\r\n- Providing seamless async operations for large-scale applications.\r\n- Supporting schema validation to ensure data integrity without manual checks.\r\n- Integrating environment variable overrides for flexible deployments.\r\n- Simplifying nested structure handling through dot-notation key paths.\r\n\r\n## Handling Multiple Configuration Formats\r\nUltraConfiguration supports various file formats, including JSON and YAML:\r\n```python\r\nfrom ultraconfiguration import UltraConfig\r\n\r\n# Load JSON config\r\njson_config = UltraConfig(\"settings.json\")\r\n\r\n# Load YAML config\r\nyaml_config = UltraConfig(\"settings.yaml\")\r\n\r\n# Both are accessed similarly:\r\nvalue_from_json = json_config.get(\"some.key\", \"default\")\r\nvalue_from_yaml = yaml_config.get(\"another.key\", 123)\r\n```\r\nYou can also override values using environment variables or custom logic.  \r\nThis flexibility enables you to maintain consistent config handling across different projects.\r\n\r\n## Documentation\r\nBelow is a quick reference to commonly used methods in UltraConfig:\r\n- **UltraConfig(config_file: Optional[str|Path])**  \r\n  Creates or retrieves the global instance; optionally auto-loads a config file.\r\n\r\n- **get(key: str, default: Any = None) \u00e2\u2020\u2019 Any**  \r\n  Retrieves a nested config value with LRU caching.\r\n\r\n- **set(key: str, value: Any, validate: bool = True) \u00e2\u2020\u2019 None**  \r\n  Assigns a new value, optionally validating against a JSON schema.\r\n\r\n- **load_config(file_path: str|Path, schema_path: Optional[str] = None) \u00e2\u2020\u2019 None**  \r\n  Loads configuration from file, optionally applying an external schema.\r\n\r\n- **save_config(file_path: str|Path, pretty: bool = True) \u00e2\u2020\u2019 None**  \r\n  Saves current configuration to specified file with optional pretty-print.\r\n\r\n- **load_config_async(...)** / **save_config_async(...)**  \r\n  Async versions of load and save operations, allowing non-blocking I/O.\r\n\r\n- **load_config_background(...)** / **save_config_background(...)**  \r\n  Launches load/save tasks in background threads.\r\n\r\n- **clear_cache()**  \r\n  Clears all cached values to ensure fresh lookups.\r\n\r\n- **reset()**  \r\n  Discards all config data, returning to a clean state.\r\n\r\n- **has_changes()**  \r\n  Checks if the in-memory config differs from what\u00e2\u20ac\u2122s on disk.\r\n\r\n## Advanced Usage\r\nUse environment variables for dynamic overrides:\r\n```python\r\nimport os\r\nfrom ultraconfiguration import UltraConfig\r\n\r\nos.environ['database.host'] = '10.0.0.2'\r\n\r\nconfig = UltraConfig('config.json')\r\nhost = config.get('database.host', '127.0.0.1')\r\nprint(f\"Host overridden by environment: {host}\")\r\n```\r\n\r\nSchema validation example:\r\n```python\r\n# ...existing code...\r\nschema_path = 'config_schema.json'\r\nconfig.load_config('config.json', schema_path=schema_path)\r\n# ...existing code...\r\n```\r\n\r\n## Frequently Asked Questions\r\n1. **Does UltraConfig work in multi-process environments?**  \r\n   UltraConfig is primarily designed for single-process usage. For multi-process setups, consider shared memory or database-backed solutions.\r\n   \r\n2. **How do I reset configurations at runtime?**  \r\n   Simply call `config.reset()` to clear the internal dictionaries.\r\n\r\n3. **Is there a performance impact with validation?**  \r\n   Yes, validation can add overhead. Disable it when performance is critical and you trust the input.\r\n",
    "bugtrack_url": null,
    "license": "MIT License with attribution requirement",
    "summary": "UltraConfiguration is a fast and efficient Python library for loading and managing configuration files with ease.",
    "version": "1.2.0",
    "project_urls": {
        "Download": "https://github.com/Kawai-Senpai/UltraConfiguration",
        "Homepage": "https://github.com/Kawai-Senpai/UltraConfiguration"
    },
    "split_keywords": [
        "config",
        " configuration",
        " json",
        " yaml",
        " settings"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "0803bf80446473dc378a233d509d2146a5286e8144f3ad513c4fd2294f5667a1",
                "md5": "ddba764d020640f537686e9c0b65f4e3",
                "sha256": "54fe4017dd1d4ee7da7e63d1cbd033e2cd8d57feb1116f253e92d5f889696849"
            },
            "downloads": -1,
            "filename": "ultraconfiguration-1.2.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "ddba764d020640f537686e9c0b65f4e3",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 7951,
            "upload_time": "2025-02-03T18:39:50",
            "upload_time_iso_8601": "2025-02-03T18:39:50.638137Z",
            "url": "https://files.pythonhosted.org/packages/08/03/bf80446473dc378a233d509d2146a5286e8144f3ad513c4fd2294f5667a1/ultraconfiguration-1.2.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "f6d756c6a5d50c4b14556583711b80db0f60205407f0581b26bef7d98b179c23",
                "md5": "427a8332fd85c6c72314909cbc26a5cc",
                "sha256": "c0ca7631725e69d2c527c6d505bcbd9420f143d01cce8282f69d753f3ea3f105"
            },
            "downloads": -1,
            "filename": "ultraconfiguration-1.2.0.tar.gz",
            "has_sig": false,
            "md5_digest": "427a8332fd85c6c72314909cbc26a5cc",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 11015,
            "upload_time": "2025-02-03T18:39:52",
            "upload_time_iso_8601": "2025-02-03T18:39:52.545372Z",
            "url": "https://files.pythonhosted.org/packages/f6/d7/56c6a5d50c4b14556583711b80db0f60205407f0581b26bef7d98b179c23/ultraconfiguration-1.2.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-02-03 18:39:52",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "Kawai-Senpai",
    "github_project": "UltraConfiguration",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "ultraconfiguration"
}
        
Elapsed time: 1.27899s