storebind 0.1.0__tar.gz

storebind-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Chau
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

storebind-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.3
+Name: storebind
+Version: 0.1.0
+Summary: Typed application state, dependency injection, and reactive subscriptions for Python.
+Keywords: state-management,dependency-injection,reactive,store,typed-state
+Author: Benjamin Chau
+Author-email: Benjamin Chau <68836494+swarfte@users.noreply.github.com>
+License: MIT License
+         
+         Copyright (c) 2026 Benjamin Chau
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+

storebind-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "storebind"
+version = "0.1.0"
+description = "Typed application state, dependency injection, and reactive subscriptions for Python."
+readme = "README.md"
+authors = [
+    { name = "Benjamin Chau", email = "68836494+swarfte@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = []
+license = { file = "LICENSE" }
+keywords = [
+"state-management",
+"dependency-injection",
+"reactive",
+"store",
+"typed-state",
+]
+
+classifiers = [
+"Development Status :: 3 - Alpha",
+"Intended Audience :: Developers",
+"Programming Language :: Python :: 3",
+"Programming Language :: Python :: 3.11",
+"Programming Language :: Python :: 3.12",
+"Programming Language :: Python :: 3.13",
+"Programming Language :: Python :: 3.14",
+"Typing :: Typed",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.25,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.16.8",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+"E",
+"F",
+"I",
+"UP",
+"B",
+"SIM",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = [
+"src",
+"tests",
+]

storebind-0.1.0/src/storebind/__init__.py

@@ -0,0 +1,25 @@
+from .base import BaseStore
+from .exceptions import (
+    InvalidStateTypeError,
+    MissingStateValueError,
+    StateNotDeclaredError,
+    StoreAlreadyRegisteredError,
+    StoreBindError,
+    StoreNotRegisteredError,
+)
+from .registry import StoreRegistry
+
+store = StoreRegistry()
+
+
+__all__ = [
+    "BaseStore",
+    "InvalidStateTypeError",
+    "MissingStateValueError",
+    "StateNotDeclaredError",
+    "StoreAlreadyRegisteredError",
+    "StoreBindError",
+    "StoreNotRegisteredError",
+    "StoreRegistry",
+    "store",
+]

storebind-0.1.0/src/storebind/base.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, ClassVar, get_type_hints
+
+from .exceptions import MissingStateValueError
+
+_MISSING = object()
+
+
+class BaseStore:
+    """
+    Base class for all StoreBind stores.
+
+    Store fields are declared using type annotations:
+
+        class ConfigStore(BaseStore):
+            theme: str = "dark"
+            style: str
+    """
+
+    __storebind_internal_fields__: ClassVar[frozenset[str]] = frozenset(
+        {
+            "__storebind_internal_fields__",
+        }
+    )
+
+    def __init__(self, **initial_values: Any) -> None:
+        field_types = self.field_types()
+
+        unknown_fields = set(initial_values) - set(field_types)
+
+        if unknown_fields:
+            fields = ", ".join(sorted(unknown_fields))
+            raise TypeError(
+                f"{type(self).__name__} received unknown state field(s): {fields}."
+            )
+
+        missing_fields: list[str] = []
+
+        for field_name in field_types:
+            if field_name in initial_values:
+                value = initial_values[field_name]
+            else:
+                value = self._get_default(field_name)
+
+            if value is _MISSING:
+                missing_fields.append(field_name)
+                continue
+
+            object.__setattr__(
+                self,
+                field_name,
+                deepcopy(value),
+            )
+
+        if missing_fields:
+            formatted_fields = ", ".join(sorted(missing_fields))
+
+            raise MissingStateValueError(
+                f"{type(self).__name__} requires initial values "
+                f"for: {formatted_fields}."
+            )
+
+    @classmethod
+    def field_types(cls) -> dict[str, Any]:
+        """
+        Return declared store fields and their resolved types.
+        """
+
+        annotations = get_type_hints(cls)
+
+        return {
+            name: annotation
+            for name, annotation in annotations.items()
+            if not name.startswith("_")
+        }
+
+    @classmethod
+    def _get_default(cls, field_name: str) -> Any:
+        for base in cls.__mro__:
+            if field_name in base.__dict__:
+                return base.__dict__[field_name]
+
+        return _MISSING
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            field_name: getattr(self, field_name) for field_name in self.field_types()
+        }
+
+    def __repr__(self) -> str:
+        values = ", ".join(
+            f"{name}={value!r}" for name, value in self.to_dict().items()
+        )
+
+        return f"{type(self).__name__}({values})"

storebind-0.1.0/src/storebind/exceptions.py

@@ -0,0 +1,22 @@
+class StoreBindError(Exception):
+    """Base exception for StoreBind."""
+
+
+class StoreAlreadyRegisteredError(StoreBindError):
+    """Raised when a store class is registered more than once."""
+
+
+class StoreNotRegisteredError(StoreBindError):
+    """Raised when accessing an unregistered store."""
+
+
+class StateNotDeclaredError(StoreBindError):
+    """Raised when accessing a state field not declared by the store."""
+
+
+class MissingStateValueError(StoreBindError):
+    """Raised when a required state field has no initial value."""
+
+
+class InvalidStateTypeError(StoreBindError, TypeError):
+    """Raised when a state value does not match its declared type."""

storebind-0.1.0/src/storebind/registry.py

@@ -0,0 +1,549 @@
+from __future__ import annotations
+
+import inspect
+import types
+from collections.abc import Callable
+from functools import wraps
+from threading import RLock
+from typing import (
+    Any,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+)
+
+from .base import BaseStore
+from .exceptions import (
+    InvalidStateTypeError,
+    StateNotDeclaredError,
+    StoreAlreadyRegisteredError,
+    StoreNotRegisteredError,
+)
+
+StoreT = TypeVar("StoreT", bound=BaseStore)
+ReturnT = TypeVar("ReturnT")
+
+Subscriber = Callable[[Any, Any], None]
+
+
+class StoreRegistry:
+    """
+    Registry containing application-wide store instances.
+    """
+
+    def __init__(
+        self,
+        *,
+        validate_types: bool = True,
+    ) -> None:
+        self._stores: dict[type[BaseStore], BaseStore] = {}
+
+        self._subscribers: dict[
+            tuple[type[BaseStore], str],
+            set[Subscriber],
+        ] = {}
+
+        self._validate_types = validate_types
+        self._lock = RLock()
+
+    def register(
+        self,
+        store_type: type[StoreT],
+        /,
+        *,
+        replace: bool = False,
+        **initial_values: Any,
+    ) -> StoreT:
+        """
+        Register and instantiate a store class.
+        """
+
+        if not isinstance(store_type, type):
+            raise TypeError("register() expects a BaseStore class, not an instance.")
+
+        if not issubclass(store_type, BaseStore):
+            raise TypeError(f"{store_type!r} must inherit from BaseStore.")
+
+        with self._lock:
+            if store_type in self._stores and not replace:
+                raise StoreAlreadyRegisteredError(
+                    f"{store_type.__name__} is already registered."
+                )
+
+            instance = store_type(**initial_values)
+
+            if self._validate_types:
+                self._validate_store(instance)
+
+            self._stores[store_type] = instance
+
+            if replace:
+                self._remove_store_subscribers(store_type)
+
+            return instance
+
+    def unregister(
+        self,
+        store_type: type[BaseStore],
+    ) -> None:
+        with self._lock:
+            self._require_store(store_type)
+
+            del self._stores[store_type]
+            self._remove_store_subscribers(store_type)
+
+    def is_registered(
+        self,
+        store_type: type[BaseStore],
+    ) -> bool:
+        with self._lock:
+            return store_type in self._stores
+
+    def use(
+        self,
+        store_type: type[StoreT],
+    ) -> StoreT:
+        """
+        Return the registered store instance.
+        """
+
+        with self._lock:
+            instance = self._require_store(store_type)
+
+        return instance  # type: ignore[return-value]
+
+    def get(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+    ) -> Any:
+        with self._lock:
+            instance = self._require_store(store_type)
+
+            self._require_attribute(
+                store_type,
+                attribute_name,
+            )
+
+            return getattr(instance, attribute_name)
+
+    def set(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+        value: Any,
+    ) -> Any:
+        self._require_attribute(
+            store_type,
+            attribute_name,
+        )
+
+        if self._validate_types:
+            self._validate_field_value(
+                store_type,
+                attribute_name,
+                value,
+            )
+
+        subscriber_key = (
+            store_type,
+            attribute_name,
+        )
+
+        with self._lock:
+            instance = self._require_store(store_type)
+            old_value = getattr(instance, attribute_name)
+
+            if self._values_equal(old_value, value):
+                return value
+
+            setattr(instance, attribute_name, value)
+
+            subscribers = tuple(
+                self._subscribers.get(
+                    subscriber_key,
+                    (),
+                )
+            )
+
+        for callback in subscribers:
+            callback(value, old_value)
+
+        return value
+
+    def inject(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+        *,
+        as_: str,
+    ) -> Callable[
+        [Callable[..., ReturnT]],
+        Callable[..., ReturnT],
+    ]:
+        """
+        Inject a store value into a function parameter.
+
+        Explicit caller arguments take priority over injection.
+        """
+
+        if not as_:
+            raise ValueError("inject() requires a non-empty 'as_' parameter.")
+
+        self._require_attribute(
+            store_type,
+            attribute_name,
+        )
+
+        def decorator(
+            function: Callable[..., ReturnT],
+        ) -> Callable[..., ReturnT]:
+            signature = inspect.signature(function)
+
+            if as_ not in signature.parameters:
+                raise TypeError(
+                    f"{function.__qualname__}() has no parameter named {as_!r}."
+                )
+
+            if inspect.iscoroutinefunction(function):
+
+                @wraps(function)
+                async def async_wrapper(
+                    *args: Any,
+                    **kwargs: Any,
+                ) -> Any:
+                    call_kwargs = self._build_injected_kwargs(
+                        function,
+                        signature,
+                        args,
+                        kwargs,
+                        store_type,
+                        attribute_name,
+                        as_,
+                    )
+
+                    return await function(
+                        *args,
+                        **call_kwargs,
+                    )
+
+                return async_wrapper  # type: ignore[return-value]
+
+            @wraps(function)
+            def sync_wrapper(
+                *args: Any,
+                **kwargs: Any,
+            ) -> ReturnT:
+                call_kwargs = self._build_injected_kwargs(
+                    function,
+                    signature,
+                    args,
+                    kwargs,
+                    store_type,
+                    attribute_name,
+                    as_,
+                )
+
+                return function(
+                    *args,
+                    **call_kwargs,
+                )
+
+            return sync_wrapper
+
+        return decorator
+
+    def capture(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+    ) -> Callable[
+        [Callable[..., ReturnT]],
+        Callable[..., ReturnT],
+    ]:
+        """
+        Write a function's return value into a store field.
+        """
+
+        self._require_attribute(
+            store_type,
+            attribute_name,
+        )
+
+        def decorator(
+            function: Callable[..., ReturnT],
+        ) -> Callable[..., ReturnT]:
+            if inspect.iscoroutinefunction(function):
+
+                @wraps(function)
+                async def async_wrapper(
+                    *args: Any,
+                    **kwargs: Any,
+                ) -> Any:
+                    result = await function(
+                        *args,
+                        **kwargs,
+                    )
+
+                    self.set(
+                        store_type,
+                        attribute_name,
+                        result,
+                    )
+
+                    return result
+
+                return async_wrapper  # type: ignore[return-value]
+
+            @wraps(function)
+            def sync_wrapper(
+                *args: Any,
+                **kwargs: Any,
+            ) -> ReturnT:
+                result = function(
+                    *args,
+                    **kwargs,
+                )
+
+                self.set(
+                    store_type,
+                    attribute_name,
+                    result,
+                )
+
+                return result
+
+            return sync_wrapper
+
+        return decorator
+
+    def subscribe(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+        callback: Subscriber,
+        *,
+        immediate: bool = False,
+    ) -> Callable[[], None]:
+        self._require_store(store_type)
+        self._require_attribute(
+            store_type,
+            attribute_name,
+        )
+
+        key = (
+            store_type,
+            attribute_name,
+        )
+
+        with self._lock:
+            callbacks = self._subscribers.setdefault(
+                key,
+                set(),
+            )
+
+            callbacks.add(callback)
+
+        if immediate:
+            current_value = self.get(
+                store_type,
+                attribute_name,
+            )
+
+            callback(
+                current_value,
+                current_value,
+            )
+
+        def unsubscribe() -> None:
+            with self._lock:
+                callbacks = self._subscribers.get(key)
+
+                if callbacks is None:
+                    return
+
+                callbacks.discard(callback)
+
+                if not callbacks:
+                    self._subscribers.pop(
+                        key,
+                        None,
+                    )
+
+        return unsubscribe
+
+    def reset(self) -> None:
+        """
+        Remove every registered store and subscriber.
+        """
+
+        with self._lock:
+            self._stores.clear()
+            self._subscribers.clear()
+
+    def _require_store(
+        self,
+        store_type: type[StoreT],
+    ) -> StoreT:
+        try:
+            instance = self._stores[store_type]
+        except KeyError:
+            raise StoreNotRegisteredError(
+                f"{store_type.__name__} is not registered."
+            ) from None
+
+        return instance  # type: ignore[return-value]
+
+    def _require_attribute(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+    ) -> None:
+        field_types = store_type.field_types()
+
+        if attribute_name not in field_types:
+            raise StateNotDeclaredError(
+                f"{store_type.__name__} has no declared state field {attribute_name!r}."
+            )
+
+    def _validate_store(
+        self,
+        instance: BaseStore,
+    ) -> None:
+        store_type = type(instance)
+
+        for field_name in store_type.field_types():
+            self._validate_field_value(
+                store_type,
+                field_name,
+                getattr(instance, field_name),
+            )
+
+    def _validate_field_value(
+        self,
+        store_type: type[BaseStore],
+        attribute_name: str,
+        value: Any,
+    ) -> None:
+        expected_type = store_type.field_types()[attribute_name]
+
+        if not self._matches_type(
+            value,
+            expected_type,
+        ):
+            raise InvalidStateTypeError(
+                f"{store_type.__name__}.{attribute_name} "
+                f"expects {expected_type!r}, "
+                f"but received {type(value).__name__}."
+            )
+
+    def _matches_type(
+        self,
+        value: Any,
+        expected_type: Any,
+    ) -> bool:
+        if expected_type is Any:
+            return True
+
+        origin = get_origin(expected_type)
+        arguments = get_args(expected_type)
+
+        if origin in {
+            Union,
+            types.UnionType,
+        }:
+            return any(self._matches_type(value, argument) for argument in arguments)
+
+        if origin is list:
+            if not isinstance(value, list):
+                return False
+
+            if not arguments:
+                return True
+
+            item_type = arguments[0]
+
+            return all(self._matches_type(item, item_type) for item in value)
+
+        if origin is dict:
+            if not isinstance(value, dict):
+                return False
+
+            if len(arguments) != 2:
+                return True
+
+            key_type, value_type = arguments
+
+            return all(
+                self._matches_type(key, key_type)
+                and self._matches_type(item, value_type)
+                for key, item in value.items()
+            )
+
+        if origin is tuple:
+            return isinstance(value, tuple)
+
+        if origin is set:
+            return isinstance(value, set)
+
+        if origin is not None:
+            try:
+                return isinstance(value, origin)
+            except TypeError:
+                return True
+
+        try:
+            return isinstance(value, expected_type)
+        except TypeError:
+            # Some typing constructs cannot be checked safely
+            # through isinstance().
+            return True
+
+    def _build_injected_kwargs(
+        self,
+        function: Callable[..., Any],
+        signature: inspect.Signature,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        store_type: type[BaseStore],
+        attribute_name: str,
+        parameter_name: str,
+    ) -> dict[str, Any]:
+        call_kwargs = dict(kwargs)
+
+        try:
+            bound_arguments = signature.bind_partial(
+                *args,
+                **call_kwargs,
+            )
+        except TypeError:
+            # Preserve the original function call error.
+            return call_kwargs
+
+        if parameter_name not in bound_arguments.arguments:
+            call_kwargs[parameter_name] = self.get(
+                store_type,
+                attribute_name,
+            )
+
+        return call_kwargs
+
+    def _remove_store_subscribers(
+        self,
+        store_type: type[BaseStore],
+    ) -> None:
+        keys = [key for key in self._subscribers if key[0] is store_type]
+
+        for key in keys:
+            del self._subscribers[key]
+
+    @staticmethod
+    def _values_equal(
+        old_value: Any,
+        new_value: Any,
+    ) -> bool:
+        try:
+            return bool(old_value == new_value)
+        except Exception:
+            return old_value is new_value