pyconfigtree 0.1.0__tar.gz

pyconfigtree-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.*
+!.gitignore

pyconfigtree-0.1.0/.idea/.gitignore

@@ -0,0 +1,8 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml

pyconfigtree-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: pyconfigtree
+Version: 0.1.0
+Summary: A lightweight yet powerful mini-framework for building hierarchical, tree-structured configs.
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.15.0
+Provides-Extra: toml
+Requires-Dist: tomli-w>=1.0.0; extra == 'toml'

pyconfigtree-0.1.0/dist/.gitignore

@@ -0,0 +1 @@
+*

pyconfigtree-0.1.0/pyconfigtree/__init__.py

@@ -0,0 +1,3 @@
+from .base import Node as Node
+from .source import *
+from .parameter import *

pyconfigtree-0.1.0/pyconfigtree/base.py

@@ -0,0 +1,273 @@
+from __future__ import annotations
+
+from typing import Any, TypeVar, TypeAlias, overload
+from enum import Enum, auto
+from types import MappingProxyType
+from collections.abc import Mapping, Callable, Sequence, Awaitable, Generator
+
+from .source import ConfigSource
+from .exceptions import LeafNodeError, NodeLoopError, NoSourceError, NodeDuplicateError
+from .source.base import NodeInfo, NodeType
+
+
+T = TypeVar('T', bound='Node')
+
+ON_NODE_ATTACHED_HOOK: TypeAlias = Callable[['Node', 'Node'], Awaitable[Any]]
+ON_NODE_DETACHED_HOOK: TypeAlias = Callable[['Node', 'Node'], Awaitable[Any]]
+
+
+class BaseHookTypes(Enum):
+    ON_NODE_ATTACHED = auto()
+    ON_NODE_DETACHED = auto()
+
+
+class Node:
+    _allow_children: bool = True
+
+    def __init__(
+        self,
+        node_id: str,
+        name: str = '',
+        description: str = '',
+        source: ConfigSource | None = None,
+        flags: set[Any] | None = None,
+        on_node_attached_hook: ON_NODE_ATTACHED_HOOK | None = None,
+        on_node_detached_hook: ON_NODE_DETACHED_HOOK | None = None,
+    ):
+        self._id: str = node_id
+        self._name = name
+        self._description = description
+        self._parent: Node | None = None
+        self._subnodes: dict[str, Node] = {}
+        self._subnodes_proxy = MappingProxyType(self._subnodes)
+        self._source = source
+        self._flags = flags or set()
+
+        self._hooks: dict[Any, Callable[..., Awaitable[Any]] | None] = {}
+        self.on_node_attached_hook = on_node_attached_hook
+        self.on_node_detached_hook = on_node_detached_hook
+
+    @property
+    def flags(self) -> frozenset[Any]:
+        return frozenset(self._flags)
+
+    @property
+    def hooks(self) -> Mapping[Any, Callable[..., Awaitable[Any]] | None]:
+        return MappingProxyType(self._hooks)
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def parent(self) -> Node | None:
+        return self._parent
+
+    @property
+    def subnodes(self) -> Mapping[str, Node]:
+        return self._subnodes_proxy
+
+    @property
+    def root(self) -> Node:
+        node = self
+        while node.parent is not None:
+            node = node.parent
+        return node
+
+    @property
+    def path(self) -> tuple[str, ...]:
+        path = [i.id for i in self.chain_to_root()]
+        path.reverse()
+        return tuple(path)
+
+    @property
+    def source(self) -> ConfigSource | None:
+        return self._source
+
+    @property
+    def inherited_source(self) -> ConfigSource | None:
+        if self.source is not None:
+            return self._source
+        if self.parent is not None:
+            return self.parent.inherited_source
+        return None
+
+    @property
+    def on_node_attached_hook(self) -> ON_NODE_ATTACHED_HOOK | None:
+        return self._hooks.get(BaseHookTypes.ON_NODE_ATTACHED)
+
+    @on_node_attached_hook.setter
+    def on_node_attached_hook(self, hook: ON_NODE_ATTACHED_HOOK | None) -> None:
+        self._hooks[BaseHookTypes.ON_NODE_ATTACHED] = hook
+
+    @property
+    def on_node_detached_hook(self) -> ON_NODE_DETACHED_HOOK | None:
+        return self._hooks.get(BaseHookTypes.ON_NODE_DETACHED)
+
+    @on_node_detached_hook.setter
+    def on_node_detached_hook(self, hook: ON_NODE_DETACHED_HOOK | None) -> None:
+        self._hooks[BaseHookTypes.ON_NODE_DETACHED] = hook
+
+    def _attach_node(self, node: T) -> T:
+        self.check_can_attach_node(node)
+        node._parent = self
+        self._subnodes[node.id] = node
+        return node
+
+    async def attach_node(self, node: T, run_hook: bool = True) -> T:
+        node = self._attach_node(node)
+        if run_hook:
+            await self.run_hook(BaseHookTypes.ON_NODE_ATTACHED, node, self)
+        return node
+
+    @overload
+    def _detach_node(self, node: str) -> Node: ...
+
+    @overload
+    def _detach_node(self, node: T) -> T: ...
+
+    def _detach_node(self, node: T | str) -> T | Node:
+        node_id = node if isinstance(node, str) else node.id
+        if node_id not in self.subnodes:
+            raise KeyError(f'Node {self.path} has no subnode with id {node_id}.')
+
+        detached_node = self._subnodes.pop(node_id)
+        detached_node._parent = None
+        return detached_node
+
+    @overload
+    async def detach_node(self, node: str, run_hook: bool = True) -> Node: ...
+
+    @overload
+    async def detach_node(self, node: T, run_hook: bool = True) -> T: ...
+
+    async def detach_node(self, node: T | str, run_hook: bool = True) -> T | Node:
+        detached_node = self._detach_node(node)
+        if run_hook:
+            await self.run_hook(BaseHookTypes.ON_NODE_DETACHED, detached_node, self)
+        return detached_node
+
+    def get_node_info(self, same_source_only: bool = True) -> NodeInfo:
+        return NodeInfo(
+            id=self.id,
+            name=self.name,
+            description=self.description,
+            type=NodeType.CONTAINER,
+            subnodes={
+                k: i.get_node_info(same_source_only=same_source_only)
+                for k, i in self.subnodes.items()
+                if (same_source_only and self.inherited_source == i.inherited_source)
+                or not same_source_only
+            },
+        )
+
+    def check_can_be_attached(self) -> None:
+        if self._parent is not None:
+            raise RuntimeError(
+                f'Node {self.path} already has a parent and cannot be attached to another node.',
+            )
+
+    def check_can_attach_node(self, node: Node) -> None:
+        if not self._allow_children:
+            raise LeafNodeError(f'Node of type {type(self)} cannot contain subnodes.')
+
+        node.check_can_be_attached()
+
+        if node is self:
+            raise NodeLoopError('Node cannot be attached to itself.')
+
+        if node.id in self.subnodes:
+            raise NodeDuplicateError(
+                f'Node {self.path} already contains a subnode with id {node.id}.',
+            )
+
+        for i in node.chain_to_tails():
+            if i is self:
+                raise NodeLoopError('Node loop.')  # todo
+        return
+
+    def chain_to_root(self) -> Generator[Node, None, None]:
+        node: Node | None = self
+        while node is not None:
+            yield node
+            node = node.parent
+
+    def chain_to_tails(self) -> Generator[Node, None, None]:
+        yield self
+        for i in self.subnodes.values():
+            yield from i.chain_to_tails()
+
+    def is_child_of(self, node: Node | Sequence[str], direct: bool = True) -> bool:
+        path = node.path if isinstance(node, Node) else tuple(node)
+        self_path = self.path
+
+        if direct:
+            if len(self_path) != len(path) + 1:
+                return False
+        else:
+            if len(self_path) <= len(path):
+                return False
+
+        return self_path[: len(path)] == path
+
+    def is_parent_of(self, node: Node | Sequence[str], direct: bool = True) -> bool:
+        path = node.path if isinstance(node, Node) else node
+        self_path = self.path
+
+        if direct:
+            if len(self_path) != len(path) - 1:
+                return False
+        else:
+            if len(self_path) >= len(path):
+                return False
+
+        return path[: len(self_path)] == self_path
+
+    async def save(self, same_source_only: bool = True) -> None:
+        if self.source is None:
+            if not self.inherited_source:
+                raise NoSourceError(f'Cannot save node {self.path}: source not specified.')
+            for i in self.chain_to_root():
+                if i.source is not None:
+                    return await i.save(same_source_only=same_source_only)
+        else:
+            node_info = self.get_node_info()
+            return await self.source.save(data=node_info)
+
+    async def load(self, validate: bool = True, run_hook: bool = False) -> None:
+        if self.source is None:
+            raise NoSourceError(f'Cannot load node {self.path}: source not specified.')
+
+        data = await self.source.load()
+        await self.load_from_dict(data, validate=validate, run_hook=run_hook)
+
+    async def load_from_dict(
+        self,
+        data_dict: dict[str, Any],
+        validate: bool = True,
+        run_hook: bool = False,
+    ) -> None:
+        for k, data in data_dict.items():
+            if k not in self.subnodes:
+                continue
+            node = self.subnodes[k]
+            await node.load_from_dict(
+                data_dict=data_dict[k],
+                validate=validate,
+                run_hook=run_hook,
+            )
+
+    async def run_hook(self, hook_identifier: Any, *args: Any, **kwargs: Any) -> Any:
+        hook = self.hooks.get(hook_identifier)
+        if hook is not None:
+            await hook(*args, **kwargs)
+        if self.parent is not None:
+            await self.parent.run_hook(hook_identifier, *args, **kwargs)

pyconfigtree-0.1.0/pyconfigtree/exceptions.py

@@ -0,0 +1,34 @@
+__all__ = [
+    'PyConfigTreeError',
+    'ValidationError',
+    'SerializationError',
+    'DeserializationError',
+    'NoSourceError',
+    'NodeLoopError',
+    'NodeDuplicateError',
+    'LeafNodeError',
+]
+
+
+class PyConfigTreeError(Exception): ...
+
+
+class ValidationError(PyConfigTreeError): ...
+
+
+class SerializationError(PyConfigTreeError): ...
+
+
+class DeserializationError(PyConfigTreeError): ...
+
+
+class NoSourceError(PyConfigTreeError): ...
+
+
+class NodeLoopError(PyConfigTreeError): ...
+
+
+class NodeDuplicateError(PyConfigTreeError): ...
+
+
+class LeafNodeError(PyConfigTreeError): ...

pyconfigtree-0.1.0/pyconfigtree/parameter/__init__.py

@@ -0,0 +1,9 @@
+from .base import (
+    Parameter as Parameter,
+    MutableParameter as MutableParameter,
+)
+from .int_parameter import IntParameter as IntParameter
+from .bool_parameter import BoolParameter as BoolParameter
+from .float_parameter import FloatParameter as FloatParameter
+from .choice_parameter import Choice as Choice
+from .string_parameter import StringParameter as StringParameter

pyconfigtree-0.1.0/pyconfigtree/parameter/base.py

@@ -0,0 +1,267 @@
+__all__ = [
+    'ParameterHookTypes',
+    'Serializer',
+    'Deserializer',
+    'Validator',
+    'Parameter',
+    'MutableParameter',
+    'TypedParameter',
+    'ON_PARAMETER_VALUE_CHANGED_HOOK',
+    '_MutableParameterKwargs',
+]
+
+
+from typing import Any, Type, Generic, TypeVar, Protocol, TypeAlias
+from enum import Enum, auto
+from asyncio import Lock
+from collections.abc import Callable, Awaitable
+
+from typing_extensions import Self, Unpack, Required, TypedDict, NotRequired
+
+from pyconfigtree.exceptions import ValidationError, DeserializationError
+
+from ..base import Node
+from ..source.base import ALLOWED_TYPES, NodeInfo, NodeType
+
+
+ON_PARAMETER_VALUE_CHANGED_HOOK: TypeAlias = Callable[['MutableParameter[Any]'], Awaitable[Any]]
+
+
+class ParameterHookTypes(Enum):
+    PARAMETER_VALUE_CHANGED = auto()
+
+
+_VALUE_contra = TypeVar('_VALUE_contra', contravariant=True)
+_VALUE_co = TypeVar('_VALUE_co', covariant=True)
+_NODE = TypeVar('_NODE', contravariant=True)
+
+
+class Serializer(Protocol[_NODE, _VALUE_contra]):
+    def __call__(self, node: _NODE, value: _VALUE_contra) -> ALLOWED_TYPES: ...
+
+
+class Deserializer(Protocol[_NODE, _VALUE_co]):
+    def __call__(self, node: _NODE, value: ALLOWED_TYPES) -> _VALUE_co: ...
+
+
+class Validator(Protocol[_NODE, _VALUE_contra]):
+    async def __call__(self, node: _NODE, value: _VALUE_contra) -> None: ...
+
+
+T = TypeVar('T')
+
+
+class Parameter(Node, Generic[T]):
+    _allow_children = False
+
+    def __init__(
+        self,
+        node_id: str,
+        value: T,
+        name: str = '',
+        description: str = '',
+    ) -> None:
+        super().__init__(node_id=node_id, name=name, description=description)
+        self._value = value
+
+    @property
+    def value(self) -> T:
+        return self._value
+
+    async def load_from_dict(
+        self,
+        data_dict: dict[str, Any],
+        validate: bool = True,
+        run_hook: bool = False,
+    ) -> None:
+        # Parameter is immutable and its value cannot be set.
+        return
+
+
+_VALUE_TYPE = TypeVar('_VALUE_TYPE')  # Parameter value type
+_PARAM_CLASS = TypeVar('_PARAM_CLASS')  # Parameter class
+
+
+class _CommonMutableParameterKwargs(TypedDict, Generic[_PARAM_CLASS, _VALUE_TYPE]):
+    name: NotRequired[str]
+    description: NotRequired[str]
+    value: NotRequired[_VALUE_TYPE | None]
+    default_value: NotRequired[_VALUE_TYPE | None]
+    default_factory: NotRequired[Callable[[], _VALUE_TYPE] | None]
+    validator: NotRequired[Validator[_PARAM_CLASS, _VALUE_TYPE] | None]
+    on_value_changed_hook: NotRequired[ON_PARAMETER_VALUE_CHANGED_HOOK | None]
+
+
+class _MutableParameterKwargs(
+    _CommonMutableParameterKwargs[_PARAM_CLASS, _VALUE_TYPE], Generic[_PARAM_CLASS, _VALUE_TYPE]
+):
+    serializer: Required[Serializer[_PARAM_CLASS, _VALUE_TYPE]]
+    deserializer: Required[Deserializer[_PARAM_CLASS, _VALUE_TYPE]]
+
+
+class _TypedParameterKwargs(
+    _CommonMutableParameterKwargs[_PARAM_CLASS, _VALUE_TYPE], Generic[_PARAM_CLASS, _VALUE_TYPE]
+):
+    serializer: NotRequired[Serializer[_PARAM_CLASS, _VALUE_TYPE]]
+    deserializer: NotRequired[Deserializer[_PARAM_CLASS, _VALUE_TYPE]]
+
+
+class MutableParameter(Parameter[T], Generic[T]):
+    def __init__(
+        self,
+        node_id: str,
+        *,
+        name: str = '',
+        description: str = '',
+        value: T | None = None,
+        default_value: T | None = None,
+        default_factory: Callable[[], T] | None = None,
+        validator: Validator[Self, T] | None = None,
+        serializer: Serializer[Self, T],
+        deserializer: Deserializer[Self, T],
+        on_value_changed_hook: ON_PARAMETER_VALUE_CHANGED_HOOK | None = None,
+    ) -> None:
+        if value is None and default_value is None:
+            raise ValueError('Either `default_value` or `default_factory` must be specified.')
+        if value is not None and default_factory is not None:
+            raise ValueError(
+                'Either `default_value` or `default_factory` must be specified, '
+                'but not both of them.',
+            )
+
+        self._default_factory = default_factory
+        self._default_value = default_value
+        self._changing_lock = Lock()
+        self._validator = validator
+        self._serializer = serializer
+        self._deserializer = deserializer
+
+        super().__init__(
+            node_id=node_id,
+            value=value if value is not None else self.default_value,
+            name=name,
+            description=description,
+        )
+
+        self.on_value_changed_hook = on_value_changed_hook
+
+    @property
+    def default_value(self) -> T:
+        if self._default_factory is not None:
+            return self._default_factory()
+        return self._default_value
+
+    @property
+    def serializer(self) -> Serializer[Self, T]:
+        return self._serializer
+
+    @property
+    def deserializer(self) -> Deserializer[Self, T]:
+        return self._deserializer
+
+    @property
+    def validator(self) -> Validator[Self, T] | None:
+        return self._validator
+
+    @property
+    def on_value_changed_hook(self) -> ON_PARAMETER_VALUE_CHANGED_HOOK | None:
+        return self.hooks.get(ParameterHookTypes.PARAMETER_VALUE_CHANGED)
+
+    @on_value_changed_hook.setter
+    def on_value_changed_hook(self, hook: ON_PARAMETER_VALUE_CHANGED_HOOK | None) -> None:
+        self._hooks[ParameterHookTypes.PARAMETER_VALUE_CHANGED] = hook
+
+    def get_node_info(self, same_source_only: bool = True) -> NodeInfo:
+        return NodeInfo(
+            id=self.id,
+            name=self.name,
+            description=self.description,
+            type=NodeType.LEAF,
+            value=self.serialize(),
+        )
+
+    async def load_from_dict(
+        self,
+        data_dict: Any,
+        validate: bool = True,
+        run_hook: bool = False,
+    ) -> None:
+        await self.set_value(
+            data_dict,
+            save=False,
+            run_hook=run_hook,
+            validate=validate,
+        )
+
+    async def set_value(
+        self,
+        value: Any,
+        *,
+        deserialize: bool = True,
+        validate: bool = True,
+        run_hook: bool = True,
+        save: bool = True,
+    ) -> None:
+        async with self._changing_lock:
+            if deserialize:
+                value = self.deserialize(value)
+            if validate:
+                await self.validate(value)
+
+            self._value = value
+            if save:
+                await self.save()
+
+        if run_hook:
+            await self.run_hook(ParameterHookTypes.PARAMETER_VALUE_CHANGED, self)
+
+    def serialize(self) -> ALLOWED_TYPES:
+        return self.serializer(self, self.value)
+
+    def deserialize(self, value: Any) -> T:
+        return self.deserializer(self, value)
+
+    async def validate(self, value: T) -> None:
+        if self.validator is not None:
+            await self.validator(self, value)
+
+
+TT = TypeVar('TT')
+
+
+class TypedParameter(MutableParameter[TT], Generic[TT]):
+    _DEFAULT_SERIALIZER: Serializer[Self, TT]
+    _DEFAULT_DESERIALIZER: Deserializer[Self, TT]
+    _VALUE_TYPE: Type[TT]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        if cls is TypedParameter:
+            return
+
+        for i in [
+            '_DEFAULT_SERIALIZER',
+            '_DEFAULT_DESERIALIZER',
+            '_VALUE_TYPE',
+        ]:
+            if i not in cls.__dict__:
+                raise TypeError(f'`{cls.__name__}` must define `{i}`.')
+
+    def __init__(self, node_id: str, **kwargs: Unpack[_TypedParameterKwargs[Self, TT]]) -> None:
+        super().__init__(node_id=node_id, **kwargs)
+
+    def deserialize(self, value: Any) -> TT:
+        res = super().deserialize(value)
+        if not isinstance(res, self._VALUE_TYPE):
+            raise DeserializationError(
+                f'Deserialized value of `{self.__class__.__name__}` must be an instance of '
+                f'`{self._VALUE_TYPE.__name__}`, not `{type(res)}`.',
+            )
+        return res
+
+    async def validate(self, value: Any) -> None:
+        if not isinstance(value, self._VALUE_TYPE):
+            raise ValidationError(
+                f'Value of `{self.__class__.__name__}` must be an instance of '
+                f'`{self._VALUE_TYPE.__name__}`, not `{type(value)}`.',
+            )
+        return await super().validate(value)

pyconfigtree-0.1.0/pyconfigtree/parameter/bool_parameter.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'bool_serializer',
+    'bool_deserializer',
+    'BoolParameter',
+]
+
+
+from typing import Any
+
+from .base import TypedParameter
+
+
+def bool_serializer(node: 'BoolParameter', value: bool) -> bool:
+    return value
+
+
+def bool_deserializer(node: 'BoolParameter', value: Any) -> bool:
+    return bool(value)
+
+
+class BoolParameter(TypedParameter[bool]):
+    _DEFAULT_SERIALIZER = staticmethod(bool_serializer)
+    _DEFAULT_DESERIALIZER = staticmethod(bool_deserializer)
+    _VALUE_TYPE = bool
+
+    async def on(self, save: bool = True, run_hook: bool = True, validate: bool = True) -> None:
+        await self.set_value(
+            True,
+            deserialize=False,
+            validate=validate,
+            run_hook=run_hook,
+            save=save,
+        )
+
+    async def off(self, save: bool = True, run_hook: bool = True, validate: bool = True) -> None:
+        await self.set_value(
+            False,
+            deserialize=False,
+            validate=validate,
+            run_hook=run_hook,
+            save=save,
+        )
+
+    async def toggle(
+        self, save: bool = True, run_hook: bool = True, validate: bool = True
+    ) -> None:
+        await self.set_value(
+            not self.value,
+            deserialize=False,
+            validate=validate,
+            run_hook=run_hook,
+            save=save,
+        )
+
+    async def next_value(
+        self, save: bool = True, run_hook: bool = True, validate: bool = True
+    ) -> bool:
+        await self.toggle(save=save, run_hook=run_hook, validate=validate)
+        return self.value