config2py 0.1.41__py3-none-any.whl → 0.1.43__py3-none-any.whl

config2py/__init__.py

@@ -16,8 +16,11 @@ from config2py.util import (
     envvar,  # os.environ, but with dict display override to hide secrets
     ask_user_for_input,
     get_app_config_folder,
+    get_app_data_folder,
+    get_app_folder,
     get_configs_folder_for_app,
     is_repl,
     parse_assignments_from_py_source,
     process_path,
 )
+from config2py.sync_store import SyncStore, FileStore, JsonStore, register_extension

config2py/base.py

@@ -4,26 +4,24 @@ Base for getting configs from various sources and formats
 
 from collections import ChainMap
 from typing import (
-    Callable,
     Type,
     Tuple,
     KT,
     VT,
     Any,
-    Iterable,
     Protocol,
     Union,
     runtime_checkable,
     Optional,
-    MutableMapping,
 )
+from collections.abc import Callable, Iterable, MutableMapping
 from dataclasses import dataclass
 from functools import lru_cache, partial
 
 from config2py.util import always_true, ask_user_for_input, no_default, not_found
 from config2py.errors import ConfigNotFound
 
-Exceptions = Tuple[Type[Exception], ...]
+Exceptions = tuple[type[Exception], ...]
 
 
 @runtime_checkable
@@ -104,8 +102,8 @@ def get_config(
     sources: Sources = None,
     *,
     default: VT = no_default,
-    egress: Optional[GetConfigEgress] = None,
-    val_is_valid: Optional[Callable[[VT], bool]] = always_true,
+    egress: GetConfigEgress | None = None,
+    val_is_valid: Callable[[VT], bool] | None = always_true,
     config_not_found_exceptions: Exceptions = (Exception,),
 ):
     """Get a config value from a list of sources
@@ -374,7 +372,7 @@ def ask_user_for_key(
     save_to: SaveTo = None,
     save_condition=is_not_empty,
     user_asker=ask_user_for_input,
-    egress: Optional[Callable] = None,
+    egress: Callable | None = None,
 ):
     if key is None:
         return partial(
@@ -399,7 +397,7 @@ def user_gettable(
     save_to: SaveTo = None,
     *,
     prompt_template="Enter a value for {}: ",
-    egress: Optional[Callable] = None,
+    egress: Callable | None = None,
     user_asker=ask_user_for_input,
     val_is_valid: Callable[[VT], bool] = is_not_empty,
     config_not_found_exceptions: Exceptions = (Exception,),

config2py/s_configparser.py

@@ -299,11 +299,11 @@ class ConfigStore(ConfigParserStore):
 
     @persist_after_operation
     def __setitem__(self, k, v):
-        super(ConfigStore, self).__setitem__(k, v)
+        super().__setitem__(k, v)
 
     @persist_after_operation
     def __delitem__(self, k):
-        super(ConfigStore, self).__delitem__(k)
+        super().__delitem__(k)
 
     # __setitem__ = super_and_persist(ConfigParser, '__setitem__')
     # __delitem__ = super_and_persist(ConfigParser, '__delitem__')
@@ -388,13 +388,14 @@ class ConfigReader(ConfigStore):
 #             return super()._obj_of_data(data)
 
 
-from typing import Mapping, Iterable, Generator, Union
+from typing import Union
+from collections.abc import Mapping, Iterable, Generator
 import re
 
 
 # TODO: postprocess_ini_section_items and preprocess_ini_section_items: Add comma separated possibility?
 # TODO: Find out if configparse has an option to do this processing alreadys
-def postprocess_ini_section_items(items: Union[Mapping, Iterable]) -> Generator:
+def postprocess_ini_section_items(items: Mapping | Iterable) -> Generator:
     r"""Transform newline-separated string values into actual list of strings (assuming that intent)
 
     >>> section_from_ini = {
@@ -417,7 +418,7 @@ def postprocess_ini_section_items(items: Union[Mapping, Iterable]) -> Generator:
 
 
 # TODO: Find out if configparse has an option to do this processing alreadys
-def preprocess_ini_section_items(items: Union[Mapping, Iterable]) -> Generator:
+def preprocess_ini_section_items(items: Mapping | Iterable) -> Generator:
     """Transform list values into newline-separated strings, in view of writing the value to a ini formatted section
     >>> section = {
     ...     'name': 'aspyre',

config2py/sync_store.py

@@ -0,0 +1,380 @@
+"""
+Synchronized key-value stores with automatic persistence.
+
+Provides MutableMapping interfaces that automatically sync changes to their backing
+storage. Supports deferred sync via context manager for batch operations.
+
+>>> import tempfile
+>>> import json
+>>>
+>>> # Basic usage
+>>> with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+...     _ = f.write('{"key": "value"}')
+...     temp_file = f.name
+>>>
+>>> store = FileStore(temp_file)
+>>> store['new_key'] = 'new_value'  # Auto-syncs immediately
+>>> assert 'new_key' in store
+>>>
+>>> # Batch operations with context manager
+>>> with store:
+...     store['a'] = 1
+...     store['b'] = 2
+...     store['c'] = 3
+...     # No sync until context exit
+>>>
+>>> import os
+>>> os.unlink(temp_file)
+"""
+
+from typing import Callable, Any, Iterator, Union, Tuple, Optional, Dict
+from collections.abc import MutableMapping
+from pathlib import Path
+import json
+from functools import reduce
+
+__all__ = [
+    "SyncStore",
+    "FileStore",
+    "JsonStore",
+    "register_extension",
+    "get_format_handlers",
+]
+
+# Note: Independent module. No imports from config2py, dol etc.
+# TODO: Do we want to use more stuff from config2py, dol, etc.?
+
+# Type aliases
+KeyPath = Union[str, Tuple[str, ...], None]
+Loader = Callable[[], dict]
+Dumper = Callable[[dict], None]
+
+
+# --------------------------------------------------------------------------------------
+# Extension Registry
+
+_extension_registry: Dict[str, Tuple[Callable, Callable]] = {}
+
+
+def register_extension(ext: str, loader: Callable, dumper: Callable) -> None:
+    """Register loader/dumper for a file extension."""
+    _extension_registry[ext.lower()] = (loader, dumper)
+
+
+def get_format_handlers(
+    filepath: Union[str, Path],
+) -> Optional[Tuple[Callable, Callable]]:
+    """Get loader/dumper for a file based on extension."""
+    ext = Path(filepath).suffix.lower()
+    return _extension_registry.get(ext)
+
+
+# Register standard formats
+register_extension(".json", json.loads, json.dumps)
+
+# TODO: Use register-if-available pattern (with context managers.. implemented somewhere...)
+
+# ConfigParser for .ini and .cfg
+try:
+    from configparser import ConfigParser
+    import io
+
+    def _ini_loader(content: str) -> dict:
+        parser = ConfigParser()
+        parser.read_string(content)
+        return {section: dict(parser[section]) for section in parser.sections()}
+
+    def _ini_dumper(data: dict) -> str:
+        parser = ConfigParser()
+        for section, values in data.items():
+            parser[section] = values
+        output = io.StringIO()
+        parser.write(output)
+        return output.getvalue()
+
+    register_extension(".ini", _ini_loader, _ini_dumper)
+    register_extension(".cfg", _ini_loader, _ini_dumper)
+except ImportError:
+    pass
+
+# YAML support (optional)
+try:
+    import yaml
+
+    register_extension(".yaml", yaml.safe_load, yaml.dump)
+    register_extension(".yml", yaml.safe_load, yaml.dump)
+except ImportError:
+    pass
+
+# TOML support (optional)
+try:
+    import tomllib  # Python 3.11+
+    import tomli_w
+
+    register_extension(".toml", tomllib.loads, tomli_w.dumps)
+except ImportError:
+    try:
+        import tomli
+        import tomli_w
+
+        register_extension(".toml", tomli.loads, tomli_w.dumps)
+    except ImportError:
+        pass
+
+
+# --------------------------------------------------------------------------------------
+# Helper functions for nested key paths
+
+# TODO: Consider using dol.paths
+
+
+def _normalize_key_path(key_path: KeyPath) -> Tuple[str, ...]:
+    """Normalize key_path to tuple of strings."""
+    if key_path is None or key_path == ():
+        return ()
+    if isinstance(key_path, str):
+        return tuple(key_path.split(".")) if "." in key_path else (key_path,)
+    return tuple(key_path)
+
+
+def _get_nested(data: dict, path: Tuple[str, ...]) -> Any:
+    """Get value from nested dict using path."""
+    if not path:
+        return data
+    return reduce(lambda d, key: d[key], path, data)
+
+
+def _set_nested(data: dict, path: Tuple[str, ...], value: Any) -> dict:
+    """Set value in nested dict, creating intermediate dicts as needed."""
+    if not path:
+        return value
+
+    result = data.copy() if isinstance(data, dict) else {}
+    current = result
+
+    for key in path[:-1]:
+        if key not in current or not isinstance(current[key], dict):
+            current[key] = {}
+        current = current[key]
+
+    current[path[-1]] = value
+    return result
+
+
+# --------------------------------------------------------------------------------------
+# Core Classes
+
+
+class SyncStore(MutableMapping):
+    """
+    A MutableMapping that automatically syncs changes to backing storage.
+
+    Supports deferred sync via context manager for efficient batch operations.
+
+    Args:
+        loader: Function that returns the current data as a dict
+        dumper: Function that persists the data dict to storage
+
+    Example:
+        >>> def my_loader():
+        ...     return {'x': 1}
+        >>>
+        >>> data_holder = []
+        >>> def my_dumper(data):
+        ...     data_holder.clear()
+        ...     data_holder.append(data.copy())
+        >>>
+        >>> store = SyncStore(my_loader, my_dumper)
+        >>> store['y'] = 2  # Auto-syncs
+        >>> data_holder[0]
+        {'x': 1, 'y': 2}
+        >>>
+        >>> # Batch with context manager
+        >>> with store:
+        ...     store['a'] = 1
+        ...     store['b'] = 2
+        ...     # Not synced yet
+        >>> data_holder[0]  # Now synced
+        {'x': 1, 'y': 2, 'a': 1, 'b': 2}
+    """
+
+    def __init__(self, loader: Loader, dumper: Dumper):
+        self._loader = loader
+        self._dumper = dumper
+        self._data = None
+        self._auto_sync = True
+        self._needs_flush = False
+        self._load()
+
+    def _load(self):
+        """Load data from backing storage."""
+        self._data = self._loader()
+
+    def _mark_dirty(self):
+        """Mark data as changed and sync if auto_sync is enabled."""
+        self._needs_flush = True
+        if self._auto_sync:
+            self.flush()
+
+    def flush(self):
+        """Sync data to backing storage if changes exist."""
+        if self._needs_flush:
+            self._dumper(self._data)
+            self._needs_flush = False
+
+    def __enter__(self):
+        """Enter deferred sync mode."""
+        self._auto_sync = False
+        return self
+
+    def __exit__(self, *args):
+        """Exit deferred sync mode and flush changes."""
+        self.flush()
+        self._auto_sync = True
+
+    def __getitem__(self, key):
+        return self._data[key]
+
+    def __setitem__(self, key, value):
+        self._data[key] = value
+        self._mark_dirty()
+
+    def __delitem__(self, key):
+        del self._data[key]
+        self._mark_dirty()
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __len__(self):
+        return len(self._data)
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}({len(self._data)} items)"
+
+
+class FileStore(SyncStore):
+    """
+    A SyncStore backed by a file with automatic format detection.
+
+    Supports nested key paths for working with specific sections.
+
+    Args:
+        filepath: Path to file (supports ~ expansion)
+        key_path: Optional nested path to operate on
+        loader: Optional custom loader (auto-detected from extension if not provided)
+        dumper: Optional custom dumper (auto-detected from extension if not provided)
+        mode: File read mode ('r' for text, 'rb' for binary)
+        dump_kwargs: Additional kwargs for dumper
+
+    Example:
+        >>> import tempfile
+        >>> with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+        ...     _ = f.write('{"section": {"key": "value"}}')
+        ...     temp_file = f.name
+        >>>
+        >>> # Work with nested section
+        >>> section = FileStore(temp_file, key_path='section')
+        >>> section['key']
+        'value'
+        >>> section['new'] = 'data'
+        >>>
+        >>> import os
+        >>> os.unlink(temp_file)
+    """
+
+    def __init__(
+        self,
+        filepath: Union[str, Path],
+        *,
+        key_path: KeyPath = None,
+        loader: Optional[Callable[[str], dict]] = None,
+        dumper: Optional[Callable[[dict], str]] = None,
+        mode: str = "r",
+        dump_kwargs: Optional[dict] = None,
+    ):
+        self.filepath = Path(filepath).expanduser()
+        self.key_path = _normalize_key_path(key_path)
+        self.mode = mode
+        self.dump_kwargs = dump_kwargs or {}
+
+        # Auto-detect format if not provided
+        if loader is None or dumper is None:
+            handlers = get_format_handlers(self.filepath)
+            if handlers is None:
+                raise ValueError(
+                    f"No format handler registered for {self.filepath.suffix}. "
+                    f"Provide explicit loader/dumper or register the extension."
+                )
+            auto_loader, auto_dumper = handlers
+            loader = loader or auto_loader
+            dumper = dumper or auto_dumper
+
+        self._file_loader = loader
+        self._file_dumper = dumper
+
+        # Create loader/dumper closures for SyncStore
+        super().__init__(loader=self._load_from_file, dumper=self._dump_to_file)
+
+    def _load_from_file(self) -> dict:
+        """Read and parse file, returning the section specified by key_path."""
+        with open(self.filepath, self.mode) as f:
+            content = f.read()
+        data = self._file_loader(content)
+        return _get_nested(data, self.key_path)
+
+    def _dump_to_file(self, section_data: dict) -> None:
+        """Write data to file, updating only the section specified by key_path."""
+        if not self.key_path:
+            # No key_path, write entire data
+            content = self._file_dumper(section_data, **self.dump_kwargs)
+        else:
+            # Have key_path, need to merge with full file content
+            with open(self.filepath, self.mode) as f:
+                full_data = self._file_loader(f.read())
+            full_data = _set_nested(full_data, self.key_path, section_data)
+            content = self._file_dumper(full_data, **self.dump_kwargs)
+
+        write_mode = "w" if "b" not in self.mode else "wb"
+        with open(self.filepath, write_mode) as f:
+            f.write(content)
+
+    def __repr__(self):
+        key_path_str = f", key_path={self.key_path!r}" if self.key_path else ""
+        return f"{self.__class__.__name__}({self.filepath!r}{key_path_str})"
+
+
+class JsonStore(FileStore):
+    """
+    A FileStore specialized for JSON files.
+
+    Pre-configured with json.loads/dumps and sensible defaults.
+
+    Args:
+        filepath: Path to JSON file
+        key_path: Optional nested path to operate on
+        indent: JSON indentation (default: 2)
+        ensure_ascii: Whether to escape non-ASCII (default: False)
+        **dump_kwargs: Additional kwargs for json.dumps
+    """
+
+    def __init__(
+        self,
+        filepath: Union[str, Path],
+        *,
+        key_path: KeyPath = None,
+        indent: int = 2,
+        ensure_ascii: bool = False,
+        **dump_kwargs,
+    ):
+        dump_kwargs.setdefault("indent", indent)
+        dump_kwargs.setdefault("ensure_ascii", ensure_ascii)
+
+        super().__init__(
+            filepath,
+            loader=json.loads,
+            dumper=json.dumps,
+            key_path=key_path,
+            mode="r",
+            dump_kwargs=dump_kwargs,
+        )

config2py/tests/__init__.py

@@ -1,3 +1,5 @@
+"""Init for config2py tests."""
+
 import sys
 
 try:

config2py/tests/test_sync_store.py

@@ -0,0 +1,316 @@
+"""Tests for sync_store module."""
+
+import tempfile
+import json
+from pathlib import Path
+from config2py.sync_store import SyncStore, FileStore, JsonStore, register_extension
+
+try:
+    import pytest
+
+    PYTEST_AVAILABLE = True
+except ImportError:
+    PYTEST_AVAILABLE = False
+
+
+def test_sync_store_basic_operations():
+    """Test basic MutableMapping operations."""
+    data_holder = [{}]
+
+    def loader():
+        return data_holder[0].copy()
+
+    def dumper(data):
+        data_holder[0] = data.copy()
+
+    store = SyncStore(loader, dumper)
+
+    # Set
+    store["key"] = "value"
+    assert store["key"] == "value"
+    assert data_holder[0]["key"] == "value"
+
+    # Delete
+    del store["key"]
+    assert "key" not in store
+    assert "key" not in data_holder[0]
+
+    # Iteration
+    store["a"] = 1
+    store["b"] = 2
+    assert set(store) == {"a", "b"}
+
+    # Length
+    assert len(store) == 2
+
+
+def test_sync_store_auto_sync():
+    """Test that changes auto-sync by default."""
+    data_holder = [{}]
+    sync_count = [0]
+
+    def loader():
+        return data_holder[0].copy()
+
+    def dumper(data):
+        data_holder[0] = data.copy()
+        sync_count[0] += 1
+
+    store = SyncStore(loader, dumper)
+
+    store["a"] = 1
+    assert sync_count[0] == 1
+
+    store["b"] = 2
+    assert sync_count[0] == 2
+
+    del store["a"]
+    assert sync_count[0] == 3
+
+
+def test_sync_store_context_manager():
+    """Test deferred sync with context manager."""
+    data_holder = [{}]
+    sync_count = [0]
+
+    def loader():
+        return data_holder[0].copy()
+
+    def dumper(data):
+        data_holder[0] = data.copy()
+        sync_count[0] += 1
+
+    store = SyncStore(loader, dumper)
+
+    # Batch operations
+    with store:
+        store["a"] = 1
+        store["b"] = 2
+        store["c"] = 3
+        assert sync_count[0] == 0  # Not synced yet
+
+    assert sync_count[0] == 1  # Synced once on exit
+    assert data_holder[0] == {"a": 1, "b": 2, "c": 3}
+
+
+def test_sync_store_manual_flush():
+    """Test manual flush() call."""
+    data_holder = [{}]
+    sync_count = [0]
+
+    def loader():
+        return data_holder[0].copy()
+
+    def dumper(data):
+        data_holder[0] = data.copy()
+        sync_count[0] += 1
+
+    store = SyncStore(loader, dumper)
+
+    with store:
+        store["a"] = 1
+        assert sync_count[0] == 0
+
+        store.flush()  # Manual flush
+        assert sync_count[0] == 1
+
+        store["b"] = 2
+        assert sync_count[0] == 1  # Still in context, not auto-synced
+
+    assert sync_count[0] == 2  # Final flush on exit
+
+
+def test_file_store_json():
+    """Test FileStore with JSON file."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        f.write('{"key": "value"}')
+        temp_file = f.name
+
+    try:
+        store = FileStore(temp_file)
+
+        # Read
+        assert store["key"] == "value"
+
+        # Write
+        store["new_key"] = "new_value"
+
+        # Verify persistence
+        with open(temp_file) as f:
+            data = json.load(f)
+        assert data["new_key"] == "new_value"
+
+        # Delete
+        del store["key"]
+        assert "key" not in store
+
+    finally:
+        Path(temp_file).unlink()
+
+
+def test_file_store_key_path():
+    """Test FileStore with nested key_path."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        f.write('{"section1": {"a": 1}, "section2": {"b": 2}}')
+        temp_file = f.name
+
+    try:
+        # Work with section1 only
+        section1 = FileStore(temp_file, key_path="section1")
+
+        assert section1["a"] == 1
+        section1["c"] = 3
+        assert "c" in section1
+
+        # Verify section2 untouched
+        with open(temp_file) as f:
+            data = json.load(f)
+        assert data["section2"] == {"b": 2}
+        assert data["section1"]["c"] == 3
+
+    finally:
+        Path(temp_file).unlink()
+
+
+def test_file_store_dotted_key_path():
+    """Test FileStore with dotted key_path notation."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        f.write('{"a": {"b": {"c": {}}}}')
+        temp_file = f.name
+
+    try:
+        nested = FileStore(temp_file, key_path="a.b.c")
+        nested["key"] = "value"
+
+        with open(temp_file) as f:
+            data = json.load(f)
+        assert data["a"]["b"]["c"]["key"] == "value"
+
+    finally:
+        Path(temp_file).unlink()
+
+
+def test_json_store():
+    """Test JsonStore with defaults."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        f.write('{"key": "value"}')
+        temp_file = f.name
+
+    try:
+        store = JsonStore(temp_file)
+        store["new"] = "data"
+
+        # Check formatting (indent=2 by default)
+        with open(temp_file) as f:
+            content = f.read()
+        assert "  " in content  # Should have indentation
+
+    finally:
+        Path(temp_file).unlink()
+
+
+def test_file_store_batch_operations():
+    """Test that batch operations work efficiently."""
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        f.write("{}")
+        temp_file = f.name
+
+    try:
+        store = FileStore(temp_file)
+
+        # Batch mode - only one write
+        with store:
+            for i in range(100):
+                store[f"key_{i}"] = i
+
+        # Verify all written
+        with open(temp_file) as f:
+            data = json.load(f)
+        assert len(data) == 100
+        assert data["key_42"] == 42
+
+    finally:
+        Path(temp_file).unlink()
+
+
+def test_extension_registry():
+    """Test custom extension registration."""
+
+    # Register custom format
+    def custom_loader(content):
+        return {"loaded": content}
+
+    def custom_dumper(data):
+        return str(data)
+
+    register_extension(".custom", custom_loader, custom_dumper)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".custom", delete=False) as f:
+        f.write("test content")
+        temp_file = f.name
+
+    try:
+        store = FileStore(temp_file)
+        assert store["loaded"] == "test content"
+
+    finally:
+        Path(temp_file).unlink()
+
+
+def test_store_repr():
+    """Test string representations."""
+    data_holder = [{}]
+    store = SyncStore(lambda: data_holder[0], lambda d: None)
+    assert "SyncStore" in repr(store)
+
+    with tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False) as f:
+        f.write('{"section": {}}')  # Include section key
+        temp_file = f.name
+
+    try:
+        file_store = FileStore(temp_file)
+        assert "FileStore" in repr(file_store)
+        assert temp_file in repr(file_store)
+
+        file_store_with_path = FileStore(temp_file, key_path="section")
+        assert "key_path" in repr(file_store_with_path)
+
+    finally:
+        Path(temp_file).unlink()
+
+
+if __name__ == "__main__":
+    if PYTEST_AVAILABLE:
+        pytest.main([__file__, "-v"])
+    else:
+        # Run tests manually
+        print("Running tests without pytest...")
+        tests = [
+            test_sync_store_basic_operations,
+            test_sync_store_auto_sync,
+            test_sync_store_context_manager,
+            test_sync_store_manual_flush,
+            test_file_store_json,
+            test_file_store_key_path,
+            test_file_store_dotted_key_path,
+            test_json_store,
+            test_file_store_batch_operations,
+            test_extension_registry,
+            test_store_repr,
+        ]
+
+        failed = []
+        for test in tests:
+            try:
+                test()
+                print(f"✓ {test.__name__}")
+            except Exception as e:
+                print(f"✗ {test.__name__}: {e}")
+                failed.append((test.__name__, e))
+
+        print(f"\n{len(tests) - len(failed)}/{len(tests)} tests passed")
+        if failed:
+            print("\nFailed tests:")
+            for name, error in failed:
+                print(f"  {name}: {error}")
+            exit(1)

config2py/tests/utils_for_testing.py

@@ -1,3 +1,5 @@
+"""Utils for testing config2py functionality."""
+
 from functools import partial
 
 

config2py/tools.py

@@ -1,6 +1,6 @@
 """Various tools"""
 
-from typing import Callable
+from collections.abc import Callable
 from pathlib import Path
 import re
 from dol import Pipe, TextFiles, resolve_path

config2py/util.py

@@ -1,11 +1,16 @@
-"""Utility functions for config2py."""
+"""
+Utility functions for config2py.
+
+"""
 
 import re
 import os
 import ast
 from collections import ChainMap, namedtuple
 from pathlib import Path
-from typing import Optional, Union, Any, Callable, Set, Literal, get_args
+from functools import partial
+from typing import Optional, Union, Any, Set, Literal, get_args
+from collections.abc import Callable
 from types import SimpleNamespace
 import getpass
 
@@ -115,7 +120,7 @@ def ask_user_for_input(
 
 # Note: Could be made more efficient, but this is good enough (for now)
 def extract_variable_declarations(
-    string: str, expand: Optional[Union[dict, bool]] = None
+    string: str, expand: dict | bool | None = None
 ) -> dict:
     """
     Reads the contents of a config file, extracting Unix-style environment variable
@@ -340,7 +345,16 @@ def get_app_rootdir(
     - 'runtime': %TEMP%
 
     Args:
-        folder_kind: Type of folder ('config', 'data', 'cache', 'state', or 'runtime')
+        folder_kind (str): The kind of folder to get. One of 'config', 'data', 'cache', 'state', 'runtime'.
+            Defaults to 'config'.
+            Here are concise explanations for each folder kind:
+            **config**: User preferences and settings files (e.g., API keys, theme preferences, editor settings). Files users might edit manually or that define how the app behaves.
+            **data**: Essential user-created content and application state (e.g., databases, saved games, user documents, session files). Data that should be backed up and persists across updates.
+            **cache**: Temporary, regeneratable files (e.g., downloaded images, compiled assets, web cache). Can be safely deleted to free space without losing user work.
+            **state**: Application state and logs that persist between sessions but aren't critical user data (e.g., command history, undo history, recently opened files, log files). Unlike cache, shouldn't be auto-deleted.
+            **runtime**: Temporary runtime files that only exist while the app runs (e.g., PID files, Unix sockets, lock files, named pipes). Typically cleared on logout/reboot.
+            **TL;DR**: config = settings, data = user files, cache = disposable, state = logs/history, runtime = process files.
+
         ensure_exists: Whether to create the directory if it doesn't exist
 
     Returns:
@@ -355,6 +369,7 @@ def get_app_rootdir(
     - If neither is set, uses platform defaults
 
     Examples:
+
         >>> get_app_rootdir('config')  # doctest: +SKIP
         '/Users/.../.config'
         >>> get_app_rootdir('data')  # doctest: +SKIP
@@ -388,14 +403,14 @@ def _default_folder_setup(directory_path: str) -> None:
     This is the default setup callback for directories managed by config2py.
     """
     if not os.path.isdir(directory_path):
-        os.mkdir(directory_path)
+        os.makedirs(directory_path, exist_ok=True)
         # Add a hidden file to annotate the directory as one managed by config2py.
         # This helps distinguish it from directories created by other programs
         # (this can be useful to avoid conflicts).
         (Path(directory_path) / ".config2py").write_text("Created by config2py.")
 
 
-def get_app_config_folder(
+def get_app_folder(
     app_name: str = DFLT_APP_NAME,
     *,
     setup_callback: Callable[[str], None] = _default_folder_setup,
@@ -403,63 +418,70 @@ def get_app_config_folder(
     folder_kind: AppFolderKind = DFLT_APP_FOLDER_KIND,
 ) -> str:
     """
-    Retrieve or create the app data directory specific to the given app name and folder kind.
+    Retrieve or create the app directory specific to the given app name and folder kind.
 
     The folder kind determines where the app's files are stored:
-    - 'config': For configuration/settings files
-    - 'data': For essential user data, databases, sessions
-    - 'cache': For temporary/regeneratable data
+    Here are concise explanations for each folder kind:
+        **config**: User preferences and settings files (e.g., API keys, theme preferences, editor settings). Files users might edit manually or that define how the app behaves.
+        **data**: Essential user-created content and application state (e.g., databases, saved games, user documents, session files). Data that should be backed up and persists across updates.
+        **cache**: Temporary, regeneratable files (e.g., downloaded images, compiled assets, web cache). Can be safely deleted to free space without losing user work.
+        **state**: Application state and logs that persist between sessions but aren't critical user data (e.g., command history, undo history, recently opened files, log files). Unlike cache, shouldn't be auto-deleted.
+        **runtime**: Temporary runtime files that only exist while the app runs (e.g., PID files, Unix sockets, lock files, named pipes). Typically cleared on logout/reboot.
+        **TL;DR**: config = settings, data = user files, cache = disposable, state = logs/history, runtime = process files.
 
     Args:
-        app_name: Name of the app for which the data directory is needed.
+        app_name: Name of the app for which the directory is needed.
         setup_callback: A callback function to initialize the directory.
                        Default is _default_folder_setup.
         ensure_exists: Whether to ensure the directory exists.
-        folder_kind: Type of folder ('config', 'data', or 'cache').
+        folder_kind: Type of folder ('config', 'data', 'cache', 'state', or 'runtime').
                     Default is 'config' for backward compatibility.
 
     Returns:
-        str: Path to the app data directory.
+        str: Path to the app directory.
 
     By default, the app will be "config2py" and folder_kind will be "config":
 
-    >>> get_app_config_folder()  # doctest: +ELLIPSIS
+    >>> get_app_folder()  # doctest: +ELLIPSIS
     '.../.config/config2py'
 
     You can specify a different app name and folder kind:
 
-    >>> get_app_config_folder('my_app', folder_kind='data')  # doctest: +SKIP
+    >>> get_app_folder('my_app', folder_kind='data')  # doctest: +SKIP
     '/Users/.../.local/share/my_app'
-    >>> get_app_config_folder('my_app', folder_kind='cache')  # doctest: +SKIP
+    >>> get_app_folder('my_app', folder_kind='cache')  # doctest: +SKIP
     '/Users/.../.cache/my_app'
 
     You can also specify a path relative to the app root directory:
 
-    >>> get_app_config_folder('another/app/subfolder', folder_kind='data')  # doctest: +SKIP
+    >>> get_app_folder('another/app/subfolder', folder_kind='data')  # doctest: +SKIP
     '/Users/.../.local/share/another/app/subfolder'
 
     If ensure_exists is True, the directory will be created and initialized
     with the setup_callback:
 
-    >>> path = get_app_config_folder('my_app', ensure_exists=True)  # doctest: +SKIP
+    >>> path = get_app_folder('my_app', ensure_exists=True)  # doctest: +SKIP
     >>> os.path.exists(path)  # doctest: +SKIP
     True
     """
     app_data_path = os.path.join(
         get_app_rootdir(folder_kind, ensure_exists=ensure_exists), app_name
     )
-    app_data_folder_did_not_exist = not os.path.isdir(app_data_path)
-    # process_path(app_data_path, ensure_dir_exists=True)
+    app_data_folder_does_not_exist = not os.path.isdir(app_data_path)
 
-    if app_data_folder_did_not_exist:
-        setup_callback(app_data_path)
+    if app_data_folder_does_not_exist and ensure_exists:
+        setup_callback(app_data_path, ensure_exists=ensure_exists)
     return app_data_path
 
 
+get_app_config_folder = partial(get_app_folder, folder_kind="config")
+get_app_data_folder = partial(get_app_folder, folder_kind="data")
+
 DFLT_CONFIGS_NAME = "configs"
 
 
 # TODO: is "get" the right word, since it makes the folder too?
+# TODO: Merge get_configs_folder_for_app and get_app_config_folder
 def get_configs_folder_for_app(
     app_name: str = DFLT_APP_NAME,
     *,
@@ -532,7 +554,7 @@ def is_repl():
     return False
 
 
-is_repl.repl_conditions: Set[Callable] = _repl_conditions  # type: ignore
+is_repl.repl_conditions: set[Callable] = _repl_conditions  # type: ignore
 
 
 def _value_node_is_instance_of(

{config2py-0.1.41.dist-info → config2py-0.1.43.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: config2py
-Version: 0.1.41
+Version: 0.1.43
 Summary: Simplified reading and writing configurations from various sources and formats
 Home-page: https://github.com/i2mint/config2py
 License: apache-2.0
@@ -9,7 +9,8 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: dol
 Requires-Dist: i2
-Requires-Dist: importlib-resources; python_version < "3.9"
+Requires-Dist: importlib_resources; python_version < "3.9"
+Dynamic: license-file
 
 # config2py
 
@@ -110,7 +111,7 @@ In fact, `simple_config_getter` is a function to make configuration getters that
 
 <img width="341" alt="image" src="https://github.com/i2mint/config2py/assets/1906276/09f287a8-05f9-4590-8664-10feda9ad617">
 
-But where you can control what the central store (by default "Local App Data Files" store) is, and whether to first search in environment variables or not, and whether to ask the user for the value, if not found before, or not. 
+But where you can control what the central store (by default a local configuration files store) is, and whether to first search in environment variables or not, and whether to ask the user for the value, if not found before, or not. 
 
 ```python
 from config2py import simple_config_getter, get_configs_local_store
@@ -130,7 +131,7 @@ print(*str(Sig(simple_config_getter)).split(','), sep='\n')
 `ask_user_if_key_not_found` specifies whether to ask the user if a configuration key is not found. The default is `None`, which will result in checking if you're running in an interactive environment or not. 
 When you use `config2py` in production though, you should definitely specify `ask_user_if_key_not_found=False` to make that choice explicit.
 
-The `configs_src` default is automatically set to be the `config2py/configs` folder of your systems's "App Data" folder (also configurable via a `CONFIG2PY_APP_DATA_FOLDER` environment variable). 
+The `configs_src` default is automatically set to be the `config2py/configs` folder of your system's config directory (following XDG standards on Unix/Linux/macOS). You can override this with environment variables like `CONFIG2PY_CONFIG_DIR`, `CONFIG2PY_DATA_DIR`, etc., or the standard XDG variables. 
 
 Your central store will be `config_store_factory(configs_src)`, and since you can also specify `config_store_factory`, you have total control over the store.
 
@@ -210,12 +211,88 @@ It will return the value that the user entered last time, without prompting the
 user again.
 
 
+## SyncStore: Auto-Syncing Key-Value Stores
+
+### Overview
+
+`SyncStore` provides MutableMapping interfaces that automatically persist changes to backing storage. Changes sync immediately by default, or can be deferred using a context manager for efficient batch operations.
+
+### Basic Usage
+
+```python
+from config2py.sync_store import FileStore, JsonStore
+
+# Auto-detected from .json extension
+config = FileStore('config.json')
+config['api_key'] = 'secret'  # Syncs immediately
+
+# Batch operations (deferred sync)
+with config:
+    config['a'] = 1
+    config['b'] = 2
+    config['c'] = 3
+    # Syncs once on exit
+```
+
+### Nested Sections
+
+```python
+# Work with specific section via key_path
+db_config = FileStore('config.json', key_path='database')
+db_config['host'] = 'localhost'  # Only affects database section
+
+# Dotted notation for deep nesting
+items = FileStore('config.json', key_path='app.settings.items')
+items['item1'] = 'value'
+```
+
+### Supported Formats
+
+Auto-detected by extension:
+- `.json` - JSON (stdlib)
+- `.ini`, `.cfg` - INI files (stdlib)
+- `.yaml`, `.yml` - YAML (if PyYAML installed)
+- `.toml` - TOML (if tomli/tomllib installed)
+
+Register custom formats:
+```python
+from sync_store import register_extension
+
+register_extension('.custom', my_loader, my_dumper)
+store = FileStore('data.custom')
+```
+
+### Custom Backing Storage
+
+```python
+from config2py.sync_store import SyncStore
+
+# Any backing storage via loader/dumper
+def my_loader():
+    return fetch_from_database()
+
+def my_dumper(data):
+    save_to_database(data)
+
+store = SyncStore(my_loader, my_dumper)
+store['key'] = 'value'  # Calls my_dumper
+```
+
+### Key Classes
+
+- **`SyncStore`** - Base class with loader/dumper functions
+- **`FileStore`** - File-based with extension detection and key_path
+- **`JsonStore`** - Explicit JSON with sensible defaults
+
+
 # A few notable tools you can import from config2py
 
 * `get_config`: Get a config value from a list of sources. See more below.
 * `user_gettable`: Create a ``GettableContainer`` that asks the user for a value, optionally saving it.
 * `ask_user_for_input`: Ask the user for input, optionally masking, validating and transforming the input.
-* `get_app_config_folder`: Returns the full path of a directory suitable for storing application-specific data for a given app name.
+* `get_app_folder`: Returns the full path of a directory suitable for storing application-specific data for a given app name and folder kind (config, data, cache, state, runtime).
+* `get_app_config_folder`: Specialized version of `get_app_folder` for configuration files.
+* `get_app_data_folder`: Specialized version of `get_app_folder` for application data.
 * `get_configs_local_store`: Get a local store (mapping interface of local files) of configs for a given app or package name
 * `configs`: A default store instance for configs, defaulting to a local store under a default configuration local directory.
 
@@ -338,7 +415,3 @@ s['SOME_KEY']
 
 More on that another day...
 
-
-```python
-
-```

config2py-0.1.43.dist-info/RECORD

@@ -0,0 +1,17 @@
+config2py/__init__.py,sha256=-IWX8fBXWhpcvJk0TRDemdo_l_jrVQ-g860VC4bgifE,976
+config2py/base.py,sha256=8qVfdQzfX7OABFUU_drtgQXC6gsAegRctYVyZHjidkY,15883
+config2py/errors.py,sha256=QdwGsoJhv6LHDHp-_yyz4oUg1Fgu4S-S7O2nuA0a5cw,203
+config2py/s_configparser.py,sha256=BKOIfUyw6YTk3ib8RnUtNec01jLyCeSPQT6F3gMYggo,15852
+config2py/sync_store.py,sha256=myou0hKP7bEeDp03o9bxMBWbFol_z_Uxab2tb9bkVEA,11451
+config2py/tools.py,sha256=KVQBINF6GW8sJtePmaHtgkY2Q5t-2VWaen_p5Gt217A,9208
+config2py/util.py,sha256=8Vfb40-O994r0j5AtYXcgiRtm4sKOc1ezsCKmC6lj88,23317
+config2py/scrap/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+config2py/tests/__init__.py,sha256=VI7rHivkD2Vh3z9tmEdDsq-KKLV2_YkJyj9IeW-FyLE,330
+config2py/tests/test_sync_store.py,sha256=StErw7UeIE01bROkppdyQYKWRgD4Ew5TQ_ZBw4R2wIk,7916
+config2py/tests/test_tools.py,sha256=sdiBNTavuzxW2AsqBRTO9U21iWig5DEyV38r6lmaZak,3728
+config2py/tests/utils_for_testing.py,sha256=-CB1e0l71yknCtKEn5hU3luaTRqrboZwRS4pQo7cGTU,212
+config2py-0.1.43.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+config2py-0.1.43.dist-info/METADATA,sha256=XT3QC8bnYw0jjtnS6UEhX-pZIfKe9GllzGkuRrZYRg4,16719
+config2py-0.1.43.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+config2py-0.1.43.dist-info/top_level.txt,sha256=DFnlOIKMIGWQRROr3voJFhWFViHaWgTTeWZjC5YC9QQ,10
+config2py-0.1.43.dist-info/RECORD,,

{config2py-0.1.41.dist-info → config2py-0.1.43.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.45.1)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

config2py-0.1.41.dist-info/RECORD

@@ -1,15 +0,0 @@
-config2py/__init__.py,sha256=CMW0A9HFvihk_ezZ5Jh1XPWo14hE9S-oC4eZFl0AnAo,846
-config2py/base.py,sha256=eQpRQjZYT-z6GhBemepaPUEyVVP8e_l04dghYeBBJdI,15880
-config2py/errors.py,sha256=QdwGsoJhv6LHDHp-_yyz4oUg1Fgu4S-S7O2nuA0a5cw,203
-config2py/s_configparser.py,sha256=-Sl2-J-QOLUiahwhCTiPsmjs4cKc79JuTbQ9gQcOiGY,15871
-config2py/tools.py,sha256=goDuHHXKJzdFgmHzDnLBGMZEhp0kKU-aK47c1-MpJT8,9199
-config2py/util.py,sha256=kW7C1rCNtatHajJitgrKdSXSE5hmpFTjsDyShtOS_80,20933
-config2py/scrap/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-config2py/tests/__init__.py,sha256=sk-yGJQOZES2z70M4xmZB57tsxSktX_84ybDuV8Cz5Q,297
-config2py/tests/test_tools.py,sha256=sdiBNTavuzxW2AsqBRTO9U21iWig5DEyV38r6lmaZak,3728
-config2py/tests/utils_for_testing.py,sha256=RcMiVtKK39rc8BsgIXQH3RCkd8qKo2o2MT7Rt0dJF2E,162
-config2py-0.1.41.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-config2py-0.1.41.dist-info/METADATA,sha256=9v8fwUQ7kIlWxazlPsaWUV9iWaECMxos6cqaZw36bjM,14543
-config2py-0.1.41.dist-info/WHEEL,sha256=tZoeGjtWxWRfdplE7E3d45VPlLNQnvbKiYnx7gwAy8A,92
-config2py-0.1.41.dist-info/top_level.txt,sha256=DFnlOIKMIGWQRROr3voJFhWFViHaWgTTeWZjC5YC9QQ,10
-config2py-0.1.41.dist-info/RECORD,,