config2py 0.1.41__tar.gz → 0.1.43__tar.gz

{config2py-0.1.41/config2py.egg-info → config2py-0.1.43}/PKG-INFO

@@ -1,12 +1,16 @@
-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
 Platform: any
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: dol
+Requires-Dist: i2
+Requires-Dist: importlib_resources; python_version < "3.9"
+Dynamic: license-file
 
 # config2py
 
@@ -107,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
@@ -127,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.
 
@@ -207,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.
 
@@ -335,7 +415,3 @@ s['SOME_KEY']
 
 More on that another day...
 
-
-```python
-
-```

config2py-0.1.41/PKG-INFO → config2py-0.1.43/README.md

@@ -1,13 +1,3 @@
-Metadata-Version: 2.1
-Name: config2py
-Version: 0.1.41
-Summary: Simplified reading and writing configurations from various sources and formats
-Home-page: https://github.com/i2mint/config2py
-License: apache-2.0
-Platform: any
-Description-Content-Type: text/markdown
-License-File: LICENSE
-
 # config2py
 
 Simplified reading and writing configurations from various sources and formats.
@@ -107,7 +97,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
@@ -127,7 +117,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.
 
@@ -207,12 +197,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.
 
@@ -335,7 +401,3 @@ s['SOME_KEY']
 
 More on that another day...
 
-
-```python
-
-```

{config2py-0.1.41 → config2py-0.1.43}/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-0.1.41 → config2py-0.1.43}/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-0.1.41 → config2py-0.1.43}/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',