# UltraConfiguration
A high-performance, thread-safe configuration management library for Python with async support.
## 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\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"
}
JSON
