appsettings2 2.0.14__tar.gz → 2.1.0__tar.gz

{appsettings2-2.0.14/src/appsettings2.egg-info → appsettings2-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appsettings2
-Version: 2.0.14
+Version: 2.1.0
 Summary: Unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT
@@ -14,14 +14,14 @@ Classifier: Programming Language :: Python
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: dev
 Requires-Dist: coverage; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pep8-naming; extra == "dev"
-Requires-Dist: punit>=1.10.8; extra == "dev"
+Requires-Dist: punit>=1.12.5; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Dynamic: license-file

{appsettings2-2.0.14 → appsettings2-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "appsettings2"
-version = "2.0.14"
+version = "2.1.0"
 description = "Unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data."
 keywords = ["appsettings", "configuration"]
 authors = [
@@ -15,7 +15,7 @@ classifiers = [
 ]
 requires-python = ">=3.11"
 dependencies = [
-  "pyyaml>=6.0.2"
+  "pyyaml>=6.0.3"
 ]
 
 [project.optional-dependencies]
@@ -25,7 +25,7 @@ dev = [
     "flake8-pyproject",
     "mypy",
     "pep8-naming",
-    "punit (>=1.10.8)",
+    "punit (>=1.12.5)",
     "twine",
     "types-PyYAML"
 ]
@@ -53,6 +53,6 @@ exclude = [
 [tool.flake8]
 max-line-length = 120
 ignore = ["D100","E501"]
-per-file-ignore = [
-    "tests/*.py:D012",
+per-file-ignores = [
+    "tests/*.py:D012,E306",
 ]

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/Configuration.py

@@ -7,26 +7,42 @@ import json
 import logging
 import re
 import types
-from types import NoneType
-from typing import Any, Iterator, Union, TYPE_CHECKING, get_args, get_origin, get_type_hints
 import unicodedata
+from enum import Enum
+from types import NoneType
+from typing import Any, Callable, Iterator, Union, TYPE_CHECKING, get_args, get_origin, get_type_hints
 
 from .ConfigurationException import ConfigurationException
 
+if TYPE_CHECKING:
+    from .ConfigurationWatcher import ConfigurationWatcher
+
+
+class ChangeType(str, Enum):
+    CHANGING = 'changing'
+    CHANGED = 'changed'
+    CLOSED = 'closed'
+
 
 class Configuration:
     """The :py:class:`~appsettings2.Configuration` class is how applications access configuration data populated by :py:class:`~appsettings2.providers.ConfigurationProvider` objects. It exposes configuration data through dynamic object attributes as well as a dictionary-like interface."""
 
+    __handlers: list[Callable[[Configuration, ChangeType, str | None], None]]
     __key_scrub_re: re.Pattern[str] | None
     __keys: dict[str, str]
     __normalize: bool
+    __watcher: ConfigurationWatcher | None
 
-    def __init__(self, normalize: bool = False, scrubkeys: bool = False) -> None:
+    disable_events: bool
+
+    def __init__(self, normalize: bool = False, scrubkeys: bool = False, disable_events: bool | None = None, watcher: ConfigurationWatcher | None = None) -> None:
         """
         Initialize *Configuration* instance.
 
         :param normalize: Option indicating whether or not attribute names should be normalized to upper-case on the resulting :py:class:`~appsettings2.Configuration` object, defaults to False.
         :param scrubkeys: Option indicating whether or not attribute names should be scrubbed to be compatible with the Python lexer, defaults to False.
+        :param disable_events: Option indicating whether change events should be emitted, defaults to False.
+        :param watcher: Optional :py:class:`~appsettings2.ConfigurationWatcher` to associate with this configuration.
         """
         self.__keys = {}
         self.__logger = logging.getLogger('appsettings2')
@@ -36,6 +52,11 @@ class Configuration:
             if not scrubkeys
             else re.compile(r'[^A-Za-z0-9_]', re.IGNORECASE | re.UNICODE)
         )
+        self.disable_events = disable_events is True
+        self.__handlers = []
+        self.__watcher = watcher
+        if self.__watcher is not None:
+            self.__watcher.watch_handler = self.__on_watch_event
 
     if TYPE_CHECKING:
 
@@ -47,13 +68,76 @@ class Configuration:
             """Tell type checkers that setting any attribute to any value is allowed."""
             ...
 
+    def __del__(self) -> None:
+        self.close()
+
+    def __on_changing(self, key: str | None) -> None:
+        if self.disable_events:
+            return
+        key = self.__normalize_key(key)
+        for entry in self.__handlers:
+            entry(self, ChangeType.CHANGING, key)
+
+    def __on_changed(self, key: str | None) -> None:
+        if self.disable_events:
+            return
+        key = self.__normalize_key(key)
+        for entry in self.__handlers:
+            entry(self, ChangeType.CHANGED, key)
+
+    def __on_close(self, key: str | None) -> None:
+        if self.disable_events:
+            return
+        key = self.__normalize_key(key)
+        for entry in self.__handlers:
+            entry(self, ChangeType.CLOSED, None)
+        self.__handlers.clear()
+
+    def __on_watch_event(self, filepath: str, watch_event_type: str, configuration: Configuration | None = None) -> None:
+        if watch_event_type in ('c', 'm') and configuration is not None:
+            self.merge(configuration)
+
+    def __add_child_change_handler(self, child_key: str) -> None:
+        if self.disable_events:
+            return
+
+        def child_change_handler(configuration: Configuration, change_type: ChangeType, key: str | None) -> None:
+            if change_type is ChangeType.CHANGING:
+                self.__on_changing(f'{child_key}.{key}')
+            elif change_type is ChangeType.CHANGED:
+                self.__on_changed(f'{child_key}.{key}')
+        child_change_handler.__dict__['_auto_wired'] = True
+        child_change_handler.__dict__['_auto_wired_child_key'] = child_key
+        child_change_handler.__dict__['_auto_wired_parent'] = self
+        self[child_key].add_change_handler(child_change_handler)
+
+    def __remove_child_change_handler(self, child_key: str) -> None:
+        child = getattr(self, child_key, None)
+        if child is None:
+            return
+        child_handlers = child.__handlers
+        for i in range(len(child_handlers) - 1, -1, -1):
+            handler = child_handlers[i]
+            d = getattr(handler, '__dict__', {})
+            if d.get('_auto_wired') and d.get('_auto_wired_child_key') == child_key:
+                child_handlers.pop(i)
+                break
+
+    def __normalize_key(self, key: str | None) -> str | None:
+        return None if key is None else key.replace('__', '.').replace(':', '.')
+
     def __delitem__(self, key: str) -> None:
         """Delete the specified configuration key."""
         key = key.upper()
         k = self.__keys.get(key)
         if k is not None:
+            value = getattr(self, k)
+            self.__on_changing(key)
+            if isinstance(value, Configuration):
+                self.__remove_child_change_handler(k)
             delattr(self, k)
             self.__keys.pop(key)
+            self.__on_changed(key)
 
     def __getitem__(self, key: str) -> Any:
         """
@@ -320,34 +404,6 @@ class Configuration:
         """Render the configuration as a JSON string."""
         return json.dumps(self.to_dict(), indent=None, ensure_ascii=False)
 
-    def bind(self, target: object, key: str | None = None) -> Any:
-        """
-        Binds the configuration values into the target object.
-
-        Can optionally specify a configuration key to bind from.
-
-        :param target: The object to bind configuration data into.
-        :param key: An optional confguration key to bind to, defaults to None which binds to the configuration root.
-        :return: The original `target` object, modified in-place.
-        """
-        if target is None:
-            raise ConfigurationException('Missing required argument: target')
-        if key is None:
-            return self.__recursive_bind(target, self)
-        else:
-            source = self.get(key)
-            if source is not None:
-                source_type = type(source)
-                if source_type in (Configuration, dict):
-                    return self.__recursive_bind(target, source)
-                elif source_type is list:
-                    return self.__bind_list_source(target, key, source)
-                else:
-                    # Scalar source: convert to matching typed attribute(s) on target
-                    return self.__bind_scalar_to_target(target, key, source)
-            else:
-                return target
-
     def __bind_list_source(self, target: object, key: str, source: list[Any]) -> Any:
         """Bind a Configuration- or dict-wrapped list source to *target*."""
         if not hasattr(target, '__class__'):
@@ -399,29 +455,70 @@ class Configuration:
             # Complex type or Any — nothing we can do for a scalar source
             return value
 
+    def bind(self, target: object, key: str | None = None) -> Any:
+        """
+        Binds the configuration values into the target object.
+
+        Can optionally specify a configuration key to bind from.
+
+        :param target: The object to bind configuration data into.
+        :param key: An optional confguration key to bind to, defaults to None which binds to the configuration root.
+        :return: The original `target` object, modified in-place.
+        """
+        if target is None:
+            raise ConfigurationException('Missing required argument: target')
+        if key is None:
+            return self.__recursive_bind(target, self)
+        else:
+            source = self.get(key)
+            if source is not None:
+                source_type = type(source)
+                if source_type in (Configuration, dict):
+                    return self.__recursive_bind(target, source)
+                elif source_type is list:
+                    return self.__bind_list_source(target, key, source)
+                else:
+                    # Scalar source: convert to matching typed attribute(s) on target
+                    return self.__bind_scalar_to_target(target, key, source)
+            else:
+                return target
+
+    def close(self) -> None:
+        self.__on_close(None)
+
+    def add_change_handler(self, handler: Callable[["Configuration", ChangeType, str | None], None]) -> None:
+        self.__handlers.append(handler)
+
+    def remove_change_handler(self, handler: Callable[["Configuration", ChangeType, str | None], None]) -> None:
+        for i in range(len(self.__handlers)):
+            if self.__handlers[i] is handler:
+                self.__handlers.pop(i)
+                break
+
     def clear(self) -> None:
         """Clear all configuration data."""
-        while len(self.__keys) > 0:
-            t = self.__keys.popitem()
-            delattr(self, t[1])
+        keys = list(self.__keys.keys())
+        for uk in keys:
+            del self[uk]
 
     @staticmethod
-    def from_dict(source: dict[str, Any], normalize: bool = False, scrubkeys: bool = False) -> 'Configuration':
+    def from_dict(source: dict[str, Any], normalize: bool = False, scrubkeys: bool = False, disable_events: bool | None = None) -> Configuration:
         """
         Construct a :py:class:`~appsettings2.Configuration` instance from the supplied dictionary `source`.
 
         :param source: The dictionary object to populate from.
         :param normalize: Option indicating whether or not attribute names should be normalized to upper-case on the resulting :py:class:`~appsettings2.Configuration` object, defaults to False.
         :param scrubkeys: Option indicating whether or not attribute names should be scrubbed to be compatible with the Python lexer, defaults to False.
+        :param disable_events: Option indicating whether change events should be emitted, defaults to False.
         :return: A :py:class:`~appsettings2.Configuration` object derived from the `source` parameter.
         """
         config: Configuration = Configuration(
-            normalize=normalize, scrubkeys=scrubkeys)
+            normalize=normalize, scrubkeys=scrubkeys, disable_events=disable_events)
         for kvp in source.items():
             v = kvp[1]
             if issubclass(type(v), dict):
                 v = Configuration.from_dict(
-                    v, normalize=normalize, scrubkeys=scrubkeys)
+                    v, normalize=normalize, scrubkeys=scrubkeys, disable_events=disable_events)
             config.set(kvp[0], v)
         return config
 
@@ -465,6 +562,19 @@ class Configuration:
         """Get a list of all configuration keys."""
         return list(self.__keys.values())
 
+    def merge(self, configuration: Configuration) -> None:
+        """
+        Performs a shallow merge of the provided configuration object.
+
+        Keys present in ``configuration`` that do not already exist in ``self`` (or have differing values) are written to ``self``.
+
+        :param configuration: The object to merge.
+        """
+        _sentinel = object()
+        for key in configuration.keys():
+            if self.get(key, _sentinel) != configuration[key]:
+                self[key] = configuration[key]
+
     def pop(self, key: str) -> Any:
         """Delete a specific configuration key."""
         value = self[key]
@@ -481,7 +591,11 @@ class Configuration:
         if self.__normalize:
             key = key.upper()
         parts = key.replace(':', '__').split('__')
+        full_key_for_events = key.replace('__', '.').replace(':', '.')
+        self.__on_changing(full_key_for_events)
         o = self
+
+        # Build intermediate hierarchy without emitting events
         for i in range(len(parts) - 1):
             if o == self:
                 k = self.__keys.get(parts[i].upper())
@@ -490,6 +604,7 @@ class Configuration:
                         self.__key_scrub_re is None))
                     setattr(o, self.__scrub_key(parts[i]), c)
                     self.__keys[parts[i].upper()] = parts[i]
+                    o.__add_child_change_handler(parts[i])
                     o = c
                 else:
                     o = getattr(self, self.__scrub_key(k))
@@ -501,6 +616,8 @@ class Configuration:
                     o = c
                 else:
                     o = o.get(parts[i])
+
+        # Convert dict/list values
         vtype = type(value)
         if issubclass(vtype, dict):
             value = Configuration.from_dict(
@@ -514,6 +631,7 @@ class Configuration:
                 else:
                     l.append(e)
             value = l
+
         key = parts[-1]
         if o == self:
             k = self.__keys.get(key.upper())
@@ -522,9 +640,14 @@ class Configuration:
             else:
                 self.__keys[key.upper()] = key
                 setattr(self, self.__scrub_key(key), value)
+            if isinstance(value, Configuration):
+                self.__add_child_change_handler(key)
         else:
             o.set(key, value)
 
+        self.__on_changed(full_key_for_events)
+
+
     def to_dict(self) -> dict[str, Any]:
         """
         Create a dictionary from the `Configuration` object.

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/ConfigurationBuilder.py

@@ -1,6 +1,8 @@
 # SPDX-FileCopyrightText: © 2025 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+from typing import Any, Optional, TypeAlias
+
 from .Configuration import Configuration
 from .ConfigurationException import ConfigurationException
 from .providers import (
@@ -11,7 +13,6 @@ from .providers import (
     TomlConfigurationProvider,
     YamlConfigurationProvider,
 )
-from typing import Optional, TypeAlias
 
 
 FileDescriptor: TypeAlias = int
@@ -22,19 +23,25 @@ class ConfigurationBuilder:
     Build a :py:class:`~appsettings2.Configuration` object from one or more :py:class:`~appsettings2.providers.ConfigurationProvider` instances.
     """
 
+    __disable_events: bool | None
     __normalize: bool
     __providers: list[ConfigurationProvider]
+    __watcher: Any
 
-    def __init__(self, normalize: bool = False, scrubkeys: bool = False) -> None:
+    def __init__(self, normalize: bool = False, scrubkeys: bool = False, disable_events: bool | None = None, watcher: Any = None) -> None:
         """
         Initialize *ConfigurationBuilder* instance.
 
         :param normalize: Option indicating whether or not attribute names should be normalized to upper-case on the resulting :py:class:`~appsettings2.Configuration` object, defaults to False.
         :param scrubkeys: Option indicating whether or not attribute names should be scrubbed to be compatible with the Python lexer, defaults to False.
+        :param disable_events: Option indicating whether change events should be emitted, defaults to None.
+        :param watcher: Optional :py:class:`~appsettings2.ConfigurationWatcher` to associate with the built configuration.
         """
+        self.__disable_events = disable_events
         self.__normalize = normalize
         self.__scrubkeys = scrubkeys
         self.__providers = []
+        self.__watcher = watcher
 
     def add_provider(self, provider: ConfigurationProvider) -> 'ConfigurationBuilder':
         """
@@ -128,16 +135,53 @@ class ConfigurationBuilder:
     addYaml = add_yaml
     """⚠️ DEPRECATED: use ``add_yaml(...)`` instead."""
 
-    def build(self) -> Configuration:
+    def disable_events(self) -> 'ConfigurationBuilder':
+        """
+        Disable change events for the built :py:class:`~appsettings2.Configuration`.
+
+        :return: Returns :py:class:`~appsettings2.ConfigurationBuilder` for method chaining.
+        """
+        self.__disable_events = True
+        return self
+
+    def disableEvents(self) -> 'ConfigurationBuilder':
+        """⚠️ DEPRECATED: use ``disable_events(...)`` instead."""
+        return self.disable_events()
+
+    def enable_watcher(self) -> 'ConfigurationBuilder':
+        """
+        Create and assign a :py:class:`~appsettings2.ConfigurationWatcher` instance to the builder.
+
+        Only creates a new watcher if ``self.__watcher`` is ``None``.
+
+        :return: Returns :py:class:`~appsettings2.ConfigurationBuilder` for method chaining.
+        """
+        if self.__watcher is None:
+            from .ConfigurationWatcher import ConfigurationWatcher
+            self.__watcher = ConfigurationWatcher()
+        return self
+
+    def build(self, disable_events: bool | None = None, watcher: Any = None) -> Configuration:
         """
         Builds a `Configuration` object using the providers which have been added to the builder.
 
+        :param disable_events: Option indicating whether change events should be emitted, defaults to None (uses value from ``__init__``).
+        :param watcher: Optional :py:class:`~appsettings2.ConfigurationWatcher`, defaults to None (uses value from ``__init__``).
         :return: A `Configuration` object, populated with configuration data.
         """
+        effective_watcher = watcher if watcher is not None else self.__watcher
         configuration = Configuration(
-            normalize=self.__normalize, scrubkeys=self.__scrubkeys)
+            normalize=self.__normalize,
+            scrubkeys=self.__scrubkeys,
+            disable_events=disable_events if disable_events is not None else self.__disable_events,
+            watcher=effective_watcher)
         for provider in self.__providers:
             provider.populate_configuration(configuration)
+        if effective_watcher is not None:
+            for provider in self.__providers:
+                fp = getattr(provider, 'filepath', None)
+                if fp is not None:
+                    effective_watcher.add_watch(fp)
         return configuration
 
 

appsettings2-2.1.0/src/appsettings2/ConfigurationWatcher.py

@@ -0,0 +1,375 @@
+# SPDX-FileCopyrightText: © 2026 Shaun Wilson
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import logging
+import os
+import threading
+import time
+from enum import Enum
+from typing import Callable, TypeAlias, TypedDict
+
+from .Configuration import Configuration
+from .providers import (
+    JsonConfigurationProvider,
+    TomlConfigurationProvider,
+    YamlConfigurationProvider,
+)
+
+
+class WatchEventType(str, Enum):
+    """The type of file system event detected during polling.
+
+    A ``str``-backed ``Enum`` with compact single-character values.
+    """
+
+    CREATED = 'c'
+    """The file was created or appeared after being deleted."""
+
+    MODIFIED = 'm'
+    """The file was modified (mtime or file size changed)."""
+
+    DELETED = 'd'
+    """The file was deleted or disappeared."""
+
+
+class WatchState(TypedDict):
+    """Internal state dictionary for a single watched file.
+
+    Attributes:
+        path: The fully resolved (canonical) file path.
+        size: Last known file size in bytes, or ``None`` if not yet polled.
+        mtime: Last known modification time, or ``None`` if not yet polled.
+        state: One of ``'active'``, ``'deleted'``, or ``'pending'``.
+    """
+
+    path: str
+    size: int | None
+    mtime: float | None
+    state: str
+
+
+WatchEventHandler: TypeAlias = (
+    Callable[[str, WatchEventType, Configuration | None], None] | None
+)
+
+
+class ConfigurationWatcher:
+    """Monitors configuration files on disk for file system changes.
+
+    Uses periodic polling with metadata comparison (mtime + file size) rather than
+    OS-specific file system APIs. A background daemon thread manages the polling
+    loop and spawns/terminates automatically based on active watches.
+    """
+
+    __interval: float
+    __handler: WatchEventHandler
+    __handler_lock: threading.Lock
+    __lock: threading.Lock
+    __logger: logging.Logger
+    __running: bool
+    __thread: threading.Thread | None
+    __watches: dict[str, WatchState]
+
+    def __init__(self, interval_seconds: float | None = None) -> None:
+        """Initialize the configuration file watcher.
+
+        Args:
+            interval_seconds: Polling interval in seconds. Defaults to ``60.0``.
+        """
+        self.__interval = interval_seconds if interval_seconds is not None else 60.0
+        self.__watches = {}
+        self.__thread = None
+        self.__running = False
+        self.__lock = threading.Lock()
+        self.__handler = None
+        self.__handler_lock = threading.Lock()
+        self.__logger = logging.getLogger(__name__)
+
+    def add_watch(self, filepath: str) -> None:
+        """Add a file path to be watched for changes.
+
+        The path is normalised to a fully-qualified (canonical) path via
+        ``os.path.realpath``. Duplicate resolved paths are silently ignored.
+        The polling thread is started on the first ``add_watch`` call.
+
+        Args:
+            filepath: The file system path to watch.
+        """
+        resolved = os.path.realpath(filepath)
+        with self.__lock:
+            is_first_watch = len(self.__watches) == 0
+            if resolved in self.__watches:
+                return
+            self.__watches[resolved] = {
+                'path': resolved,
+                'size': None,
+                'mtime': None,
+                'state': 'pending',
+            }
+            if is_first_watch:
+                self.__start_thread()
+
+    def remove_watch(self, filepath: str) -> None:
+        """Remove a previously added watch.
+
+        Silently does nothing if the watch does not exist. The polling thread
+        drains and exits when the last watch is removed.
+
+        Args:
+            filepath: The file system path whose watch should be removed.
+        """
+        resolved = os.path.realpath(filepath)
+        with self.__lock:
+            if resolved not in self.__watches:
+                return
+            del self.__watches[resolved]
+            if len(self.__watches) == 0 and self.__thread is not None:
+                self.__drain_thread()
+
+    def list_watches(self) -> list[str]:
+        """Return a fresh list of all currently watched file paths.
+
+        Returns:
+            A list of canonical (resolved) file path strings.
+        """
+        with self.__lock:
+            return [e['path'] for e in self.__watches.values()]
+
+    @property
+    def watch_handler(self) -> WatchEventHandler:
+        """The callback invoked for file system events.
+
+        The getter returns ``None`` if no handler has been set. The setter
+        accepts ``None`` to clear the handler.
+
+        The handler reference is captured under a lock and then invoked
+        outside the lock to avoid potential deadlocks with external calls
+        from within the handler (e.g. ``add_watch`` / ``remove_watch``).
+
+        Returns:
+            A callable of the form ``Callable[[str, WatchEventType, Configuration], None]``,
+            or ``None`` if no handler is set.
+        """
+        with self.__handler_lock:
+            return self.__handler
+
+    @watch_handler.setter
+    def watch_handler(self, handler: WatchEventHandler) -> None:
+        """Set the event handler callback.
+
+        Args:
+            handler: A callable of the form ``Callable[[str, WatchEventType, Configuration], None]``,
+                or ``None`` to clear.
+        """
+        with self.__handler_lock:
+            self.__handler = handler
+
+    def __start_thread(self) -> None:
+        """Start the background polling thread.
+
+        Called internally on the first ``add_watch``. The thread is a
+        daemon thread so it does not prevent process exit.
+        """
+        self.__running = True
+        self.__thread = threading.Thread(target=self.__poll_loop, daemon=True)
+        self.__thread.start()
+
+    def __drain_thread(self) -> None:
+        """Stop the background polling thread and wait for it to exit.
+
+        Sets ``__running`` to ``False``, then joins the thread with a
+        timeout of ``self.__interval + 1`` seconds.
+        """
+        self.__running = False
+        if self.__thread is not None:
+            self.__thread.join(timeout=self.__interval + 1)
+            if self.__thread.is_alive():
+                self.__logger.warning(
+                    'Watcher thread did not drain within %s seconds.',
+                    self.__interval + 1,
+                )
+            self.__thread = None
+
+    def __poll_loop(self) -> None:
+        """Background thread entry point — continuous polling loop."""
+        while self.__running:
+            self.__poll_once()
+            try:
+                time.sleep(self.__interval)
+            except KeyboardInterrupt:
+                break
+
+    def __poll_once(self) -> None:
+        """Execute a single poll cycle over all watches.
+
+        A snapshot of watch states is taken at the start of the cycle so
+        that concurrent ``add_watch``/``remove_watch`` calls do not
+        interfere with the current iteration. All file I/O and parsing
+        errors are logged at ERROR level and do not crash the thread.
+        The watch state is updated directly in ``self.__watches`` after
+        each event is processed.
+        """
+        with self.__lock:
+            paths = list(self.__watches.keys())
+
+        if not paths:
+            return
+
+        handler_ref = None
+        with self.__handler_lock:
+            handler_ref = self.__handler
+
+        for path in paths:
+            with self.__lock:
+                if path not in self.__watches:
+                    continue
+                state = self.__watches[path]
+                prev_state = state['state']
+                prev_size = state['size']
+                prev_mtime = state['mtime']
+
+                file_exists = os.path.isfile(path)
+
+                if file_exists and prev_state in ('deleted', 'pending'):
+                    self.__on_created(path, state, handler_ref)
+                elif file_exists and prev_state == 'active':
+                    if prev_size is None or prev_mtime is None:
+                        try:
+                            stat = os.stat(path)
+                            state['size'] = stat.st_size
+                            state['mtime'] = stat.st_mtime
+                        except OSError:
+                            state['state'] = 'deleted'
+                            self.__on_deleted(path, handler_ref)
+                    else:
+                        try:
+                            stat = os.stat(path)
+                            if stat.st_size != prev_size or stat.st_mtime != prev_mtime:
+                                self.__on_modified(path, state, handler_ref)
+                            else:
+                                state['size'] = stat.st_size
+                                state['mtime'] = stat.st_mtime
+                        except OSError:
+                            state['state'] = 'deleted'
+                            self.__on_deleted(path, handler_ref)
+                elif not file_exists and prev_state == 'active':
+                    state['state'] = 'deleted'
+                    self.__on_deleted(path, handler_ref)
+
+    def __on_created(
+        self, path: str, state: WatchState, handler: WatchEventHandler,
+    ) -> None:
+        """Handle a CREATED event.
+
+        Loads the configuration from the newly appeared file, updates the
+        watch state to ``'active'``, and fires the handler.
+
+        Args:
+            path: The canonical file path.
+            state: The watch state dictionary (updated in place, already in ``self.__watches``).
+            handler: The handler callback reference (local copy).
+        """
+        if handler is None:
+            return
+        config = self.__load_configuration(path)
+        if config is not None:
+            state['state'] = 'active'
+            try:
+                stat = os.stat(path)
+                state['size'] = stat.st_size
+                state['mtime'] = stat.st_mtime
+            except OSError:
+                pass
+            handler(path, WatchEventType.CREATED, config)
+
+    def __on_modified(
+        self, path: str, state: WatchState, handler: WatchEventHandler,
+    ) -> None:
+        """Handle a MODIFIED event.
+
+        Loads the configuration from the modified file and fires the handler.
+        Updates the watch state only if the configuration was successfully
+        loaded.
+
+        Args:
+            path: The canonical file path.
+            state: The watch state dictionary (updated in place, already in ``self.__watches``).
+            handler: The handler callback reference (local copy).
+        """
+        if handler is None:
+            return
+        config = self.__load_configuration(path)
+        if config is not None:
+            try:
+                stat = os.stat(path)
+                state['size'] = stat.st_size
+                state['mtime'] = stat.st_mtime
+            except OSError:
+                pass
+            handler(path, WatchEventType.MODIFIED, config)
+
+    def __on_deleted(self, path: str, handler: WatchEventHandler) -> None:
+        """Handle a DELETED event.
+
+        Fires the handler with ``None`` as the configuration parameter since
+        the file cannot be parsed.
+
+        Args:
+            path: The canonical file path.
+            handler: The handler callback reference (local copy).
+        """
+        if handler is None:
+            return
+        handler(path, WatchEventType.DELETED, None)
+
+    def __load_configuration(self, path: str) -> Configuration | None:
+        """Load a Configuration from a file based on its extension.
+
+        Supported extensions: ``.json``, ``.toml``, ``.yaml`` / ``.yml``.
+        Unrecognised extensions cause an error to be logged and ``None``
+        is returned. Parsing errors and I/O errors are logged and return
+        ``None`` without crashing.
+
+        Args:
+            path: The canonical file path to load.
+
+        Returns:
+            A populated ``Configuration`` instance, or ``None`` if the
+            file cannot be loaded.
+        """
+        ext = os.path.splitext(path)[1].lower()
+        try:
+            configuration = Configuration()
+            if ext == '.json':
+                JsonConfigurationProvider(
+                    filepath=path, required=False,
+                ).populate_configuration(configuration)
+            elif ext == '.toml':
+                TomlConfigurationProvider(
+                    filepath=path, required=False,
+                ).populate_configuration(configuration)
+            elif ext in ('.yaml', '.yml'):
+                YamlConfigurationProvider(
+                    filepath=path, required=False,
+                ).populate_configuration(configuration)
+            else:
+                self.__logger.error(
+                    'Cannot determine format for watched file %s '
+                    '(extension \'%s\'). Skipping.',
+                    path,
+                    ext,
+                )
+                return None
+            return configuration
+        except Exception as e:
+            self.__logger.error(
+                'Error loading configuration from %s: %s. Skipping update.',
+                path,
+                e,
+            )
+            return None
+
+
+__all__ = ['ConfigurationWatcher', 'WatchEventType']

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/__init__.py

@@ -2,20 +2,24 @@
 # SPDX-FileCopyrightText: © 2025 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
-from .Configuration import Configuration
+from .Configuration import Configuration, ChangeType
 from .ConfigurationBuilder import ConfigurationBuilder
+from .ConfigurationWatcher import ConfigurationWatcher, WatchEventType
 from .ConfigurationException import ConfigurationException
 from .helpers import get_configuration, getConfiguration
 from . import helpers
 from . import providers
 
 
-__version__ = '2.0.14'
-__commit__ = '654e291'
+__version__ = '2.1.0'
+__commit__ = 'a6890cf'
 __all__ = [
     '__version__', '__commit__',
     'Configuration',
+    'ChangeType',
     'ConfigurationBuilder',
+    'ConfigurationWatcher',
+    'WatchEventType',
     'ConfigurationException',
     'get_configuration',
     'helpers',

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/helpers.py

@@ -17,7 +17,8 @@ def get_configuration(
     cli: bool = True,
     environment: bool = True,
     variations: Optional[list[str | None]] = ['', 'prod', 'production', 'stage', 'staging', 'qa', 'dev', 'development', 'local'],
-    env_prefix: str | None = None
+    env_prefix: str | None = None,
+    disable_events: bool | None = None
 ) -> Configuration:
     """
     Get a ``Configuration`` instance by loading from a set of well-known providers and their variations.
@@ -30,6 +31,7 @@ def get_configuration(
     :param environment: ``True`` to load configuration from process Environment, defaults to True
     :param variations: A set of variations to apply to use with file-based Configuration Providers, defaults to ['', 'prod', 'production', 'stage', 'staging', 'qa', 'dev', 'development', 'local']
     :param env_prefix: (OPTIONAL) When specified, only env vars having the specified prefix are bound as configuration settings, the prefix is stripped from the resulting setting name.
+    :param disable_events: Option indicating whether change events should be emitted, defaults to False.
     :return: An ``appsettings2.Configuration`` instance.
     """
     if type(basename) is pathlib.Path or type(basename) is pathlib.PosixPath:
@@ -48,7 +50,7 @@ def get_configuration(
         builder.add_command_line()
     if environment:
         builder.add_environment(required_prefix=env_prefix)
-    return builder.build()
+    return builder.build(disable_events=disable_events)
 
 
 getConfiguration = get_configuration  # noqa: N816

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/providers/ConfigurationProvider.py

@@ -1,10 +1,11 @@
 # SPDX-FileCopyrightText: © 2025 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
-from ..Configuration import Configuration
 from abc import ABC, abstractmethod
 from typing import final
 
+from ..Configuration import Configuration
+
 
 class ConfigurationProvider(ABC):
     """The abstract base class which all Configuration Providers implement."""

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/providers/JsonConfigurationProvider.py

@@ -3,10 +3,11 @@
 
 import json as _json
 import os
-from typing import Optional, TypeAlias
+from typing import Any, Optional, TypeAlias
+
+from .ConfigurationProvider import ConfigurationProvider
 from ..Configuration import Configuration
 from ..ConfigurationException import ConfigurationException
-from .ConfigurationProvider import ConfigurationProvider
 
 
 FileDescriptor: TypeAlias = int
@@ -15,7 +16,8 @@ FileDescriptor: TypeAlias = int
 class JsonConfigurationProvider(ConfigurationProvider):
     """A ``ConfigurationProvider`` that populates configuration data from JSON."""
 
-    __obj: dict
+    __filepath: str | None
+    __obj: dict[str, Any]
 
     def __init__(self, filepath: Optional[str] = None, json: Optional[str] = None, fd: Optional[FileDescriptor] = None, required: bool = True) -> None:
         """
@@ -28,6 +30,7 @@ class JsonConfigurationProvider(ConfigurationProvider):
         :param fd: Optional file descriptor (int) to be used as a configuration source, defaults to None.
         :param required: Optional parameter indicating whether the configuration source will raise `ConfigurationException` if the specified configuration source is missing, defaults to True.
         """
+        self.__filepath = filepath
         obj = None
         try:
             if filepath:
@@ -44,7 +47,7 @@ class JsonConfigurationProvider(ConfigurationProvider):
         finally:
             self.__obj = {} if obj is None else obj
 
-    def __populate_recursive(self, configuration: Configuration, prefix: str, o: dict) -> None:
+    def __populate_recursive(self, configuration: Configuration, prefix: str, o: dict[str, Any]) -> None:
         for kvp in o.items():
             if isinstance(kvp[1], dict):
                 self.__populate_recursive(configuration, f'{prefix}__{kvp[0]}', kvp[1])
@@ -60,5 +63,10 @@ class JsonConfigurationProvider(ConfigurationProvider):
             else:
                 configuration.set(f'{kvp[0]}', kvp[1])
 
+    @property
+    def filepath(self) -> str | None:
+        """The file path used to initialize this provider, or ``None``."""
+        return self.__filepath
+
 
 __all__ = ['JsonConfigurationProvider']

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/providers/TomlConfigurationProvider.py

@@ -1,12 +1,13 @@
 # SPDX-FileCopyrightText: © 2025 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
+import os
+import tomllib as _toml
+from typing import Any, Optional, TypeAlias
+
 from .ConfigurationProvider import ConfigurationProvider
 from ..Configuration import Configuration
 from ..ConfigurationException import ConfigurationException
-import os
-import tomllib as _toml
-from typing import Optional, TypeAlias
 
 
 FileDescriptor: TypeAlias = int
@@ -15,7 +16,8 @@ FileDescriptor: TypeAlias = int
 class TomlConfigurationProvider(ConfigurationProvider):
     """A ``ConfigurationProvider`` that populates configuration data from TOML."""
 
-    __obj: dict
+    __filepath: str | None
+    __obj: dict[str, Any]
 
     def __init__(self, filepath: Optional[str] = None, toml: Optional[str] = None, fd: Optional[FileDescriptor] = None, required: bool = True) -> None:
         """
@@ -28,6 +30,7 @@ class TomlConfigurationProvider(ConfigurationProvider):
         :param fd: Optional file descriptor (int) to be used as a configuration source, defaults to None.
         :param required: Optional parameter indicating whether the configuration source will raise `ConfigurationException` if the specified configuration source is missing, defaults to True.
         """
+        self.__filepath = filepath
         obj = None
         try:
             if filepath:
@@ -44,7 +47,7 @@ class TomlConfigurationProvider(ConfigurationProvider):
         finally:
             self.__obj = {} if obj is None else obj
 
-    def __populate_recursive(self, configuration: Configuration, prefix: str, o: dict) -> None:
+    def __populate_recursive(self, configuration: Configuration, prefix: str, o: dict[str, Any]) -> None:
         for kvp in o.items():
             if isinstance(kvp[1], dict):
                 self.__populate_recursive(configuration, f'{prefix}__{kvp[0]}', kvp[1])
@@ -60,5 +63,10 @@ class TomlConfigurationProvider(ConfigurationProvider):
             else:
                 configuration.set(f'{kvp[0]}', kvp[1])
 
+    @property
+    def filepath(self) -> str | None:
+        """The file path used to initialize this provider, or ``None``."""
+        return self.__filepath
+
 
 __all__ = ['TomlConfigurationProvider']

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/providers/YamlConfigurationProvider.py

@@ -1,13 +1,14 @@
 # SPDX-FileCopyrightText: © 2025 Shaun Wilson
 # SPDX-License-Identifier: MIT
 
-from .ConfigurationProvider import ConfigurationProvider
-from ..Configuration import Configuration
-from ..ConfigurationException import ConfigurationException
 from io import StringIO
 import os
-from typing import Optional, TypeAlias
 import yaml as _yaml
+from typing import Any, Optional, TypeAlias
+
+from .ConfigurationProvider import ConfigurationProvider
+from ..Configuration import Configuration
+from ..ConfigurationException import ConfigurationException
 
 FileDescriptor: TypeAlias = int
 
@@ -15,7 +16,8 @@ FileDescriptor: TypeAlias = int
 class YamlConfigurationProvider(ConfigurationProvider):
     """A ``ConfigurationProvider`` that populates configuration data from YAML."""
 
-    __obj: dict
+    __filepath: str | None
+    __obj: dict[str, Any]
 
     def __init__(self, filepath: Optional[str] = None, yaml: Optional[str] = None, fd: Optional[FileDescriptor] = None, required: bool = True) -> None:
         """
@@ -28,6 +30,7 @@ class YamlConfigurationProvider(ConfigurationProvider):
         :param fd: Optional file descriptor (int) to be used as a configuration source, defaults to None.
         :param required: Optional parameter indicating whether the configuration source will raise `ConfigurationException` if the specified configuration source is missing, defaults to True.
         """
+        self.__filepath = filepath
         obj = None
         try:
             if filepath:
@@ -47,7 +50,7 @@ class YamlConfigurationProvider(ConfigurationProvider):
         finally:
             self.__obj = {} if obj is None else obj
 
-    def __populate_recursive(self, configuration: Configuration, prefix: str, o: dict) -> None:
+    def __populate_recursive(self, configuration: Configuration, prefix: str, o: dict[str, Any]) -> None:
         for kvp in o.items():
             if isinstance(kvp[1], dict):
                 self.__populate_recursive(
@@ -64,5 +67,10 @@ class YamlConfigurationProvider(ConfigurationProvider):
             else:
                 configuration.set(f'{kvp[0]}', kvp[1])
 
+    @property
+    def filepath(self) -> str | None:
+        """The file path used to initialize this provider, or ``None``."""
+        return self.__filepath
+
 
 __all__ = ['YamlConfigurationProvider']

{appsettings2-2.0.14 → appsettings2-2.1.0/src/appsettings2.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: appsettings2
-Version: 2.0.14
+Version: 2.1.0
 Summary: Unifies configuration sources into a Configuration object that can be bound to complex types, or accessed directly for configuration data.
 Author-email: Shaun Wilson <mrshaunwilson@msn.com>
 License-Expression: MIT
@@ -14,14 +14,14 @@ Classifier: Programming Language :: Python
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: pyyaml>=6.0.3
 Provides-Extra: dev
 Requires-Dist: coverage; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: flake8-pyproject; extra == "dev"
 Requires-Dist: mypy; extra == "dev"
 Requires-Dist: pep8-naming; extra == "dev"
-Requires-Dist: punit>=1.10.8; extra == "dev"
+Requires-Dist: punit>=1.12.5; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Dynamic: license-file

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/appsettings2/Configuration.py
 src/appsettings2/ConfigurationBuilder.py
 src/appsettings2/ConfigurationException.py
+src/appsettings2/ConfigurationWatcher.py
 src/appsettings2/SKILL.md
 src/appsettings2/__init__.py
 src/appsettings2/helpers.py

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2.egg-info/requires.txt

@@ -1,4 +1,4 @@
-pyyaml>=6.0.2
+pyyaml>=6.0.3
 
 [dev]
 coverage
@@ -6,6 +6,6 @@ flake8
 flake8-pyproject
 mypy
 pep8-naming
-punit>=1.10.8
+punit>=1.12.5
 twine
 types-PyYAML

{appsettings2-2.0.14 → appsettings2-2.1.0}/src/appsettings2/providers/CommandLineConfigurationProvider.py

@@ -4,8 +4,8 @@
 import sys
 from typing import Optional
 
-from ..Configuration import Configuration
 from .ConfigurationProvider import ConfigurationProvider
+from ..Configuration import Configuration
 
 
 class CommandLineConfigurationProvider(ConfigurationProvider):