glean-config 0.1.0__tar.gz

glean_config-0.1.0/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.3
+Name: glean-config
+Version: 0.1.0
+Summary: Add your description here
+Author: grimmdgg
+Author-email: grimmdgg <grimmdgg@gmail.com>
+Requires-Dist: tomli-w>=1.2.0
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# glean-config
+
+A flexible, thread-safe Python configuration manager using TOML files with support for environment variables, base64 encoding, and fileless operation modes.
+
+## Features
+
+- **TOML-based configuration**: Easy-to-read and write configuration files
+- **Singleton pattern**: Ensures consistent configuration across your application
+- **Thread-safe**: Built-in locking for concurrent access
+- **Environment variable integration**: Auto-load environment variables by name or regex pattern
+- **Automatic base64 encoding**: Prefix keys with `encoded_` for automatic encoding/decoding
+- **Fileless mode**: Run without a config file for testing or ephemeral configurations
+- **Context manager support**: Use with `with` statement for automatic saving
+
+## Installation
+
+```bash
+pip install glean-config
+```
+
+Or for development:
+
+```bash
+git clone <repository-url>
+cd glean-config
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from glean_config.config import Glean_config
+
+# Load or create a config file
+config = Glean_config.get_instance('config.toml')
+
+# Set values
+config['api_key'] = 'your-api-key'
+config['debug'] = 'true'
+
+# Get values
+api_key = config['api_key']
+
+# Save changes
+config.save()
+```
+
+### Using the CLI
+
+```bash
+# Create/view config with a specific file
+python -m glean_config -f config.toml
+
+# Add a key-value pair
+python -m glean_config -f config.toml -a "database_url::postgresql://localhost/mydb"
+
+# Show a specific key
+python -m glean_config -f config.toml -k database_url
+
+# Use environment variable for config file location
+export GLEAN_CONFIG_FILE=/path/to/config.toml
+python -m glean_config -k database_url
+
+# Run in fileless mode (no file or env var needed)
+python -m glean_config -a "temp_key::temp_value"
+```
+
+## Configuration Modes
+
+### 1. File-based Mode (Default)
+
+```python
+config = Glean_config.get_instance('myconfig.toml')
+```
+
+Loads configuration from the specified TOML file. Creates the file if it doesn't exist.
+
+### 2. Environment Variable Mode
+
+```python
+# Set the environment variable
+import os
+os.environ['GLEAN_CONFIG_FILE'] = '/path/to/config.toml'
+
+# No file argument needed
+config = Glean_config.get_instance()
+```
+
+### 3. Fileless Mode
+
+```python
+# No file, no environment variable
+config = Glean_config.get_instance()
+# Config exists only in memory
+config['key'] = 'value'
+```
+
+## Advanced Features
+
+### Automatic Base64 Encoding
+
+Keys starting with `encoded_` are automatically base64 encoded when set and decoded when retrieved:
+
+```python
+config['encoded_password'] = 'my-secret-password'
+# Stored as base64 in the file
+
+password = config['encoded_password']
+# Returns: 'my-secret-password' (decoded)
+```
+
+### Environment Variable Integration
+
+Configure your TOML file to automatically load environment variables:
+
+```toml
+config_name = 'myapp'
+
+[environment]
+# Regex pattern to match environment variables
+env_rex = '^MYAPP_'
+# Explicit list of environment variables to load
+env = ['DATABASE_URL', 'SECRET_KEY']
+
+[config_items]
+# Your config items here
+```
+
+Now environment variables matching the pattern or in the list are automatically loaded:
+
+```python
+import os
+os.environ['MYAPP_DEBUG'] = 'true'
+os.environ['DATABASE_URL'] = 'postgresql://localhost/db'
+
+config = Glean_config.get_instance('config.toml')
+print(config['MYAPP_DEBUG'])  # 'true'
+print(config['DATABASE_URL'])  # 'postgresql://localhost/db'
+```
+
+### Context Manager
+
+```python
+with Glean_config.get_instance('config.toml') as config:
+    config['key'] = 'value'
+    config['another_key'] = 'another_value'
+# Automatically saved on exit
+```
+
+### Bulk Configuration
+
+```python
+# Replace entire config
+new_config = {
+    'api_key': 'new-key',
+    'timeout': '30',
+    'retries': '3'
+}
+config.set_config(new_config)
+
+# Merge with existing config
+config.set_config(new_config, merge=True)
+```
+
+### Export Formats
+
+```python
+# Export as TOML string
+toml_str = config.get_toml()
+
+# Export as JSON string
+json_str = config.get_json()
+```
+
+## TOML File Structure
+
+```toml
+config_name = 'my_application'
+
+[environment]
+# Regex pattern for environment variables to auto-load
+env_rex = '^AP_'
+# Explicit environment variables to load
+env = ['DATABASE_URL', 'SECRET_KEY']
+
+[config_items]
+# Your application configuration
+api_key = "your-api-key"
+debug = "false"
+timeout = "30"
+encoded_password = "bXktc2VjcmV0LXBhc3N3b3Jk"  # base64 encoded
+```
+
+## API Reference
+
+### `Glean_config.get_instance(toml_file=None)`
+
+Get or create the singleton config instance.
+
+- **toml_file** (str, optional): Path to TOML file. If `None`, uses `GLEAN_CONFIG_FILE` env var or fileless mode.
+- **Returns**: `Glean_config` instance
+
+### Instance Methods
+
+#### `config[key]` / `config[key] = value`
+
+Get or set configuration values.
+
+#### `save(force=False)`
+
+Save configuration to file (no-op in fileless mode).
+
+- **force** (bool): Save even if not modified
+
+#### `get_config()`
+
+Get the entire config_items dictionary.
+
+- **Returns**: dict
+
+#### `set_config(config, merge=False)`
+
+Set the entire config_items dictionary.
+
+- **config** (dict): New configuration
+- **merge** (bool): Merge with existing config instead of replacing
+
+#### `get_toml()`
+
+Export configuration as TOML string.
+
+- **Returns**: str
+
+#### `get_json()`
+
+Export configuration as JSON string.
+
+- **Returns**: str
+
+#### `parameters()`
+
+Get list of top-level configuration keys.
+
+- **Returns**: list[str]
+
+#### `close()`
+
+Explicitly save and close the configuration.
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=glean_config
+
+# Run specific test
+pytest tests/test_config.py::TestGleanConfig::test_fileless_mode_no_args
+```
+
+## Thread Safety
+
+All operations are thread-safe using internal locks:
+
+- Object-level lock for singleton instance creation and config updates
+- File-level lock for concurrent file I/O operations
+
+## Error Handling
+
+### `ConfigObjectError`
+
+Raised when trying to instantiate `Glean_config` directly instead of using `get_instance()`.
+
+```python
+from glean_config.config import Glean_config, ConfigObjectError
+
+try:
+    config = Glean_config('config.toml')  # Wrong!
+except ConfigObjectError:
+    config = Glean_config.get_instance('config.toml')  # Correct
+```
+
+### `KeyError`
+
+Raised when configuration structure is invalid (missing `config_items` key).
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass: `pytest tests/`
+2. Code follows PEP 8 style guidelines
+3. New features include tests
+4. Documentation is updated

glean_config-0.1.0/README.md

@@ -0,0 +1,302 @@
+# glean-config
+
+A flexible, thread-safe Python configuration manager using TOML files with support for environment variables, base64 encoding, and fileless operation modes.
+
+## Features
+
+- **TOML-based configuration**: Easy-to-read and write configuration files
+- **Singleton pattern**: Ensures consistent configuration across your application
+- **Thread-safe**: Built-in locking for concurrent access
+- **Environment variable integration**: Auto-load environment variables by name or regex pattern
+- **Automatic base64 encoding**: Prefix keys with `encoded_` for automatic encoding/decoding
+- **Fileless mode**: Run without a config file for testing or ephemeral configurations
+- **Context manager support**: Use with `with` statement for automatic saving
+
+## Installation
+
+```bash
+pip install glean-config
+```
+
+Or for development:
+
+```bash
+git clone <repository-url>
+cd glean-config
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from glean_config.config import Glean_config
+
+# Load or create a config file
+config = Glean_config.get_instance('config.toml')
+
+# Set values
+config['api_key'] = 'your-api-key'
+config['debug'] = 'true'
+
+# Get values
+api_key = config['api_key']
+
+# Save changes
+config.save()
+```
+
+### Using the CLI
+
+```bash
+# Create/view config with a specific file
+python -m glean_config -f config.toml
+
+# Add a key-value pair
+python -m glean_config -f config.toml -a "database_url::postgresql://localhost/mydb"
+
+# Show a specific key
+python -m glean_config -f config.toml -k database_url
+
+# Use environment variable for config file location
+export GLEAN_CONFIG_FILE=/path/to/config.toml
+python -m glean_config -k database_url
+
+# Run in fileless mode (no file or env var needed)
+python -m glean_config -a "temp_key::temp_value"
+```
+
+## Configuration Modes
+
+### 1. File-based Mode (Default)
+
+```python
+config = Glean_config.get_instance('myconfig.toml')
+```
+
+Loads configuration from the specified TOML file. Creates the file if it doesn't exist.
+
+### 2. Environment Variable Mode
+
+```python
+# Set the environment variable
+import os
+os.environ['GLEAN_CONFIG_FILE'] = '/path/to/config.toml'
+
+# No file argument needed
+config = Glean_config.get_instance()
+```
+
+### 3. Fileless Mode
+
+```python
+# No file, no environment variable
+config = Glean_config.get_instance()
+# Config exists only in memory
+config['key'] = 'value'
+```
+
+## Advanced Features
+
+### Automatic Base64 Encoding
+
+Keys starting with `encoded_` are automatically base64 encoded when set and decoded when retrieved:
+
+```python
+config['encoded_password'] = 'my-secret-password'
+# Stored as base64 in the file
+
+password = config['encoded_password']
+# Returns: 'my-secret-password' (decoded)
+```
+
+### Environment Variable Integration
+
+Configure your TOML file to automatically load environment variables:
+
+```toml
+config_name = 'myapp'
+
+[environment]
+# Regex pattern to match environment variables
+env_rex = '^MYAPP_'
+# Explicit list of environment variables to load
+env = ['DATABASE_URL', 'SECRET_KEY']
+
+[config_items]
+# Your config items here
+```
+
+Now environment variables matching the pattern or in the list are automatically loaded:
+
+```python
+import os
+os.environ['MYAPP_DEBUG'] = 'true'
+os.environ['DATABASE_URL'] = 'postgresql://localhost/db'
+
+config = Glean_config.get_instance('config.toml')
+print(config['MYAPP_DEBUG'])  # 'true'
+print(config['DATABASE_URL'])  # 'postgresql://localhost/db'
+```
+
+### Context Manager
+
+```python
+with Glean_config.get_instance('config.toml') as config:
+    config['key'] = 'value'
+    config['another_key'] = 'another_value'
+# Automatically saved on exit
+```
+
+### Bulk Configuration
+
+```python
+# Replace entire config
+new_config = {
+    'api_key': 'new-key',
+    'timeout': '30',
+    'retries': '3'
+}
+config.set_config(new_config)
+
+# Merge with existing config
+config.set_config(new_config, merge=True)
+```
+
+### Export Formats
+
+```python
+# Export as TOML string
+toml_str = config.get_toml()
+
+# Export as JSON string
+json_str = config.get_json()
+```
+
+## TOML File Structure
+
+```toml
+config_name = 'my_application'
+
+[environment]
+# Regex pattern for environment variables to auto-load
+env_rex = '^AP_'
+# Explicit environment variables to load
+env = ['DATABASE_URL', 'SECRET_KEY']
+
+[config_items]
+# Your application configuration
+api_key = "your-api-key"
+debug = "false"
+timeout = "30"
+encoded_password = "bXktc2VjcmV0LXBhc3N3b3Jk"  # base64 encoded
+```
+
+## API Reference
+
+### `Glean_config.get_instance(toml_file=None)`
+
+Get or create the singleton config instance.
+
+- **toml_file** (str, optional): Path to TOML file. If `None`, uses `GLEAN_CONFIG_FILE` env var or fileless mode.
+- **Returns**: `Glean_config` instance
+
+### Instance Methods
+
+#### `config[key]` / `config[key] = value`
+
+Get or set configuration values.
+
+#### `save(force=False)`
+
+Save configuration to file (no-op in fileless mode).
+
+- **force** (bool): Save even if not modified
+
+#### `get_config()`
+
+Get the entire config_items dictionary.
+
+- **Returns**: dict
+
+#### `set_config(config, merge=False)`
+
+Set the entire config_items dictionary.
+
+- **config** (dict): New configuration
+- **merge** (bool): Merge with existing config instead of replacing
+
+#### `get_toml()`
+
+Export configuration as TOML string.
+
+- **Returns**: str
+
+#### `get_json()`
+
+Export configuration as JSON string.
+
+- **Returns**: str
+
+#### `parameters()`
+
+Get list of top-level configuration keys.
+
+- **Returns**: list[str]
+
+#### `close()`
+
+Explicitly save and close the configuration.
+
+## Testing
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run with coverage
+pytest tests/ --cov=glean_config
+
+# Run specific test
+pytest tests/test_config.py::TestGleanConfig::test_fileless_mode_no_args
+```
+
+## Thread Safety
+
+All operations are thread-safe using internal locks:
+
+- Object-level lock for singleton instance creation and config updates
+- File-level lock for concurrent file I/O operations
+
+## Error Handling
+
+### `ConfigObjectError`
+
+Raised when trying to instantiate `Glean_config` directly instead of using `get_instance()`.
+
+```python
+from glean_config.config import Glean_config, ConfigObjectError
+
+try:
+    config = Glean_config('config.toml')  # Wrong!
+except ConfigObjectError:
+    config = Glean_config.get_instance('config.toml')  # Correct
+```
+
+### `KeyError`
+
+Raised when configuration structure is invalid (missing `config_items` key).
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+
+1. All tests pass: `pytest tests/`
+2. Code follows PEP 8 style guidelines
+3. New features include tests
+4. Documentation is updated

glean_config-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "glean-config"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "grimmdgg", email = "grimmdgg@gmail.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "tomli-w>=1.2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.0,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-cov>=7.0.0",
+]

glean_config-0.1.0/src/glean_config/__init__.py

@@ -0,0 +1 @@
+# __init__.py

glean_config-0.1.0/src/glean_config/__main__.py

@@ -0,0 +1,70 @@
+import argparse
+from sys import exit
+
+from glean_config.config import Glean_config
+
+def main():
+    parser = argparse.ArgumentParser("Glean_config")
+    parser.add_argument(
+        '-f',
+        '--file',
+        dest='toml_file',
+        help='path to toml config file (optional: uses GLEAN_CONFIG_FILE env var or fileless mode if not provided)',
+        default=None
+    )
+    parser.add_argument(
+        '-a',
+        '--add',
+        dest='add_kvp',
+        help='add a kvp to file in the form "key::value"'
+    )
+
+    parser.add_argument(
+        '-k',
+        '--show_key',
+        dest='key',
+        help='display key value'
+    )
+
+    args = parser.parse_args()
+
+    # Get config instance (may use file, env var, or fileless mode)
+    config = Glean_config.get_instance(args.toml_file)
+
+
+
+    # Validate and process the add_kvp argument
+    try:
+        validate_parameters(args, config)
+    except ValueError as ve:
+        print(ve)
+        exit(1)
+
+    # Removed redundant call to config.get_toml()
+
+def validate_parameters(args, config):
+    if args.add_kvp:
+
+        if "::" not in args.add_kvp:
+
+            raise ValueError("Error: The key-value pair must be in the form 'key::value'.")
+        key, value = args.add_kvp.split('::', 1)
+        config[key] = value
+
+
+    # Validate and process the key argument
+    if args.key:
+        if args.key not in config.get_config():
+            raise ValueError(f"Error: The key '{args.key}' does not exist in the configuration.")
+
+        print(f"{args.key}: {config[args.key]}")
+        exit(0)
+
+
+    config.save(force=True)
+    print(config.get_toml())
+
+
+if __name__=="__main__":
+    main()
+

glean_config-0.1.0/src/glean_config/config.py

@@ -0,0 +1,161 @@
+import tomllib
+import json
+import re
+from base64 import b64decode, b64encode
+from os import environ
+from pathlib import Path, PurePath
+from threading import Lock
+import tomli_w
+from typing import Any, TypeVar, TypeAlias
+
+# Method-level generic for config value types.
+# Use `Config[T]` in method signatures when you want a specific value type.
+T = TypeVar('T')
+# modern TypeAlias (Python 3.10+)
+Config: TypeAlias = dict[str, T]
+
+
+class ConfigObjectError(Exception):
+    def __init__(self):
+        super(ConfigObjectError,self).__init__("Please instantiate this class with the 'get_instance(toml_file:str)' class method")
+
+class Glean_config():
+
+    _config_object: 'Glean_config | None' = None
+    _object_lock = Lock()
+    _file_lock = Lock()
+    # internal storage can hold heterogeneous values loaded from TOML
+    config: Config[Any] = {}
+
+    def __init__(self, toml_file: str | None = None, override: bool = False):
+        self.modified = True
+        self.fileless_mode = False
+        
+        # Determine the file path
+        if toml_file is None:
+            # Check environment variable
+            toml_file = environ.get('glean_config_file')
+            if toml_file is None:
+                # Fileless mode
+                self.fileless_mode = True
+                self.toml_file = None
+            else:
+                self.toml_file = toml_file
+        else:
+            self.toml_file = toml_file
+
+        if not override:
+            raise ConfigObjectError()
+        else:
+            # Prepare config text
+            if self.fileless_mode:
+                config_text = Glean_config.empty_config_toml % 'fileless_config'
+            else:
+                config_text = Glean_config.empty_config_toml % PurePath(self.toml_file).name
+                if Path(self.toml_file).exists():
+                    config_text = Path(self.toml_file).read_text(encoding='utf-8')
+                    self.modified = False
+            
+            self.config = tomllib.loads(config_text)
+            self._read_env()
+
+    def _read_env(self):
+        environment = self.config.get('environment', {})
+
+        env_vars = environment.get('env', [])
+        for var in env_vars:
+            value = environ.get(var)
+            if value is not None:
+                self.__setitem__(var, value)
+
+        env_rex = environment.get('env_rex')
+        if env_rex:
+            config_items = self.config.get('config_items', {})
+            for var in environ:
+                if var not in config_items and re.match(env_rex, var):
+                    # environ is being iterated over its keys, so indexing is safe
+                    self.__setitem__(var, environ[var])
+
+    def parameters(self) -> list[str]:
+        return list(self.config.keys())
+
+    def save(self, force: bool = False) -> None:
+        if self.fileless_mode:
+            # In fileless mode, just mark as not modified but don't save
+            self.modified = False
+            return
+        
+        if (self.modified or force) and self.config and self.toml_file:
+            with Glean_config._file_lock:
+                with open(self.toml_file, mode="wb") as fp:
+                    tomli_w.dump(self.config, fp)
+                self.modified = False
+
+    def get_toml(self)->str:
+        return tomli_w.dumps(self.config)
+
+    def get_json(self)->str:
+        return json.dumps(self.config)
+
+    @classmethod
+    def get_instance(cls, toml_file: str | None = None) -> 'Glean_config':
+        with cls._object_lock:
+            if not Glean_config._config_object:
+                Glean_config._config_object = Glean_config(toml_file=toml_file, override=True)
+        return Glean_config._config_object
+
+    def get_config(self) -> Config[Any]:
+        if 'config_items' not in self.config:
+            raise KeyError("Configuration structure invalid: 'config_items' key not found")
+        return self.config['config_items']
+
+    def set_config(self, config: Config[T], merge:bool = False) -> None:
+        with Glean_config._object_lock:
+            if 'config_items' not in self.config:
+                raise KeyError("Configuration structure invalid: 'config_items' key not found")
+            if merge:
+                self.config['config_items'].update(config)
+            else:
+                self.config['config_items'] = config
+            self.modified = True
+        self.save()
+
+    def decode(self,encoded:str)-> str:
+        return str(b64decode(encoded),'utf-8')
+
+    def __getitem__(self, key: str):
+        if 'config_items' not in self.config:
+            raise KeyError("Configuration structure invalid: 'config_items' key not found")
+        returnValue = self.config['config_items'].get(key, None)
+
+        if returnValue and key.startswith('encoded_'):
+            returnValue = self.decode(returnValue)
+        return returnValue
+
+    def __setitem__(self, key: str, value: str) -> None:
+        if 'config_items' not in self.config:
+            raise KeyError("Configuration structure invalid: 'config_items' key not found")
+        if key.startswith('encoded_'):
+            value = str(b64encode(bytes(value, 'utf-8')), 'utf-8')
+        self.config['config_items'][key] = value
+        self.modified = True
+
+    def __enter__(self) -> 'Glean_config':
+        return self
+
+    def __exit__(self, exc_type: type | None, exc_value: BaseException | None, traceback: object | None) -> None:
+        self.save()
+
+    def close(self) -> None:
+        """Explicitly save and close the config. Preferred over relying on __del__."""
+        self.save()
+
+
+    empty_config_toml=\
+"""
+config_name = '%s'
+[environment]
+env_rex='^glean_'
+env=[]
+[config_items]
+"""