pyconfigtree 0.1.0__py3-none-any.whl

pyconfigtree/__init__.py

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

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/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/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/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/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

pyconfigtree/parameter/choice_parameter.py

@@ -0,0 +1,92 @@
+from typing import Any, Generic, TypeVar
+from types import MappingProxyType
+from dataclasses import dataclass
+from collections.abc import Mapping, Sequence
+
+from typing_extensions import Self, Unpack
+
+from .base import TypedParameter, _MutableParameterKwargs
+
+
+T = TypeVar('T')
+
+
+@dataclass(kw_only=True, frozen=True)
+class Choice(Generic[T]):
+    id: str
+    name: str = ''
+    description: str = ''
+    value: T
+
+    def __post_init__(self) -> None:
+        if not self.id:
+            raise ValueError('Choice ID cannot be empty.')
+
+        if not isinstance(id, str):
+            raise TypeError('Choice ID must be a string.')
+
+    def __str__(self) -> str:
+        return self.id
+
+
+def choice_serializer(node: 'ChoiceParameter[Any]', value: Choice[Any]) -> str:
+    return value.id
+
+
+def choice_deserializer(node: 'ChoiceParameter[Any]', value: Any) -> Choice[Any]:
+    value = str(value)
+    return node.choices.get(value, node.choices[node.fallback_choice_id])
+
+
+class ChoiceParameter(TypedParameter[Choice[T]], Generic[T]):
+    _DEFAULT_SERIALIZER = choice_serializer
+    _DEFAULT_DESERIALIZER = choice_deserializer
+    _VALUE_TYPE = Choice
+
+    def __init__(
+        self,
+        node_id: str,
+        *,
+        choices: Sequence[Choice[T]],
+        fallback_choice_id: str,
+        **kwargs: Unpack[_MutableParameterKwargs[Self, Choice[T]]],
+    ) -> None:
+        if not choices:
+            raise ValueError('At least 1 choice must be provided.')
+
+        self._choices: dict[str, Choice[T]] = {}
+        for i in choices:
+            if i.id in self._choices:
+                raise ValueError('Duplicate choice ID.')  # todo
+            self._choices[i.id] = i
+
+        if fallback_choice_id not in self._choices:
+            raise ValueError('Fallback choice ID does not exists.')
+        self._fallback_choice_id = fallback_choice_id
+
+        super().__init__(node_id=node_id, **kwargs)
+
+    @property
+    def choices(self) -> Mapping[str, Choice[T]]:
+        return MappingProxyType(self._choices)
+
+    @property
+    def fallback_choice_id(self) -> str:
+        return self._fallback_choice_id
+
+    async def set_value(
+        self,
+        value: Choice[T] | str,
+        *,
+        deserialize: bool = True,
+        validate: bool = True,
+        run_hook: bool = True,
+        save: bool = True,
+    ) -> None:
+        choice = self.choices.get(value) if isinstance(value, str) else value
+        if choice not in self.choices.values():
+            raise ValueError('Invalid choice.')
+
+        await super().set_value(
+            choice, deserialize=deserialize, validate=validate, run_hook=run_hook, save=save
+        )

pyconfigtree/parameter/float_parameter.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'float_serializer',
+    'float_deserializer',
+    'FloatParameter',
+]
+
+
+from typing import Any
+
+from .base import TypedParameter
+
+
+def float_serializer(node: FloatParameter, value: float) -> float:
+    return value
+
+
+def float_deserializer(node: FloatParameter, value: Any) -> float:
+    return float(value)
+
+
+class FloatParameter(TypedParameter[float]):
+    _DEFAULT_SERIALIZER = staticmethod(float_serializer)
+    _DEFAULT_DESERIALIZER = staticmethod(float_deserializer)
+    _VALUE_TYPE = float

pyconfigtree/parameter/int_parameter.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'int_serializer',
+    'int_deserializer',
+    'IntParameter',
+]
+
+
+from typing import Any
+
+from .base import TypedParameter
+
+
+def int_serializer(node: IntParameter, value: int) -> int:
+    return value
+
+
+def int_deserializer(node: IntParameter, value: Any) -> int:
+    return int(value)
+
+
+class IntParameter(TypedParameter[int]):
+    _DEFAULT_SERIALIZER = staticmethod(int_serializer)
+    _DEFAULT_DESERIALIZER = staticmethod(int_deserializer)
+    _VALUE_TYPE = int

pyconfigtree/parameter/list_parameter.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import json
+from typing import Generic, TypeVar
+from json import JSONDecodeError
+from collections.abc import Callable, Iterable, Awaitable
+
+from typing_extensions import Self, Unpack
+
+from pyconfigtree.exceptions import DeserializationError
+
+from .base import ALLOWED_TYPES, ParameterHookTypes, _TypedParameterKwargs
+
+
+__all__ = [
+    'list_serializer',
+    'list_deserializer',
+    'ListParameter',
+]
+
+
+from typing import Any
+
+from pyconfigtree.exceptions import SerializationError
+
+from .base import TypedParameter
+
+
+def list_serializer(value: list[Any]) -> list[ALLOWED_TYPES]:
+    result: list[ALLOWED_TYPES] = []
+    for i in value:
+        if isinstance(i, (int, str, float, bool)):
+            result.append(i)
+        elif isinstance(i, list):
+            result.append(list_serializer(i))
+        else:
+            raise SerializationError(f'Unable to serialize list item {i!r}.')
+    return result
+
+
+def list_deserializer(value: Any) -> list[Any]:
+    if isinstance(value, str):
+        try:
+            value = json.loads(value)
+        except JSONDecodeError:
+            raise DeserializationError(f'Unable to convert string {value!r} to list.')
+
+    if isinstance(value, Iterable):
+        return [str(i) if not isinstance(i, (int, str, float, bool)) else i for i in value]
+
+    raise DeserializationError(f'Unable to convert {value!r} to list of strings.')
+
+
+T = TypeVar('T')
+
+
+class ListParameter(TypedParameter[list[T]], Generic[T]):
+    _DEFAULT_SERIALIZER = staticmethod(list_serializer)
+    _DEFAULT_DESERIALIZER = staticmethod(list_deserializer)
+    _VALUE_TYPE = list
+
+    def __init__(
+        self,
+        node_id: str,
+        *,
+        item_deserializer: Callable[[Any], T] | None = None,
+        add_item_validator: Callable[[T, Self], Awaitable[None]] | None = None,
+        remove_item_validator: Callable[[T, Self], Awaitable[None]] | None = None,
+        **kwargs: Unpack[_TypedParameterKwargs[Self, list[T]]],
+    ) -> None:
+        super().__init__(node_id=node_id, **kwargs)
+        self.item_deserializer = item_deserializer
+        self.add_item_validator = add_item_validator
+        self.remove_item_validator = remove_item_validator
+
+    async def add_item(
+        self,
+        item: T,
+        deserialize: bool = True,
+        validate: bool = True,
+        run_hook: bool = True,
+        save: bool = True,
+    ) -> None:
+        async with self._changing_lock:
+            if deserialize:
+                item = await self.deserialize_item(item)
+            if validate:
+                await self.add_item_validate(item)
+
+            self._value.append(item)
+            if save:
+                await self.save()
+
+        if run_hook:
+            await self.run_hook(ParameterHookTypes.PARAMETER_VALUE_CHANGED, self)
+
+    async def pop_item(
+        self, index: int, validate: bool = True, run_hook: bool = True, save: bool = True
+    ) -> T | None:
+        if index < 0 or index >= len(self.value):
+            return None
+
+        async with self._changing_lock:
+            if validate:
+                item = self._value[index]
+                await self.remove_item_validate(item)
+
+            result = self._value.pop(index)
+            if save:
+                await self.save()
+
+        if run_hook:
+            await self.run_hook(ParameterHookTypes.PARAMETER_VALUE_CHANGED, self)
+
+        return result
+
+    async def remove_item(
+        self, item: T, validate: bool = True, run_hook: bool = True, save: bool = True
+    ) -> None:
+        if item not in self._value:
+            return
+
+        async with self._changing_lock:
+            if validate:
+                await self.remove_item_validate(item)
+
+            self._value.remove(item)
+            if save:
+                await self.save()
+
+        if run_hook:
+            await self.run_hook(ParameterHookTypes.PARAMETER_VALUE_CHANGED, self)
+
+    async def add_item_validate(self, item: T) -> None:
+        if self.add_item_validator is not None:
+            await self.add_item_validator(item, self)
+
+    async def remove_item_validate(self, item: T) -> None:
+        if self.remove_item_validator is not None:
+            await self.remove_item_validator(item, self)
+
+    def deserialize_item(self, item: Any) -> T:
+        return item if self.item_deserializer is None else self.item_deserializer(item)

pyconfigtree/parameter/string_parameter.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+
+__all__ = [
+    'str_serializer',
+    'str_deserializer',
+    'StringParameter',
+]
+
+
+from typing import Any
+
+from .base import TypedParameter
+
+
+def str_serializer(node: StringParameter, value: str) -> str:
+    return value
+
+
+def str_deserializer(node: StringParameter, value: Any) -> str:
+    return str(value)
+
+
+class StringParameter(TypedParameter[str]):
+    _DEFAULT_SERIALIZER = staticmethod(str_serializer)
+    _DEFAULT_DESERIALIZER = staticmethod(str_deserializer)
+    _VALUE_TYPE = str

pyconfigtree/source/__init__.py

@@ -0,0 +1,2 @@
+from .base import ConfigSource as ConfigSource
+from .json import JSONSource as JSONSource

pyconfigtree/source/base.py

@@ -0,0 +1,42 @@
+from typing import Any, Union, TypeAlias
+from abc import ABC, abstractmethod
+from enum import Enum, auto
+from dataclasses import field, dataclass
+
+
+SIMPLE_TYPES: TypeAlias = int | float | bool | str
+CONTAINER_TYPES: TypeAlias = (
+    dict[str, Union[SIMPLE_TYPES, 'CONTAINER_TYPES']]
+    | list[Union[SIMPLE_TYPES, 'CONTAINER_TYPES']]
+)
+ALLOWED_TYPES: TypeAlias = SIMPLE_TYPES | CONTAINER_TYPES
+
+
+class ConfigSource(ABC):
+    @abstractmethod
+    async def load(self) -> dict[str, Any]: ...
+
+    @abstractmethod
+    async def save(self, data: 'NodeInfo') -> None: ...
+
+    @abstractmethod
+    def __eq__(self, other: Any) -> bool: ...
+
+
+class NodeType(Enum):
+    CONTAINER = auto()
+    LEAF = auto()
+
+
+@dataclass
+class NodeInfo:
+    id: str
+    name: str
+    description: str
+    type: NodeType
+    subnodes: dict[str, 'NodeInfo'] = field(default_factory=dict)
+    value: ALLOWED_TYPES | None = None
+
+    def __post_init__(self) -> None:
+        if self.type is NodeType.CONTAINER and self.value is not None:
+            raise ValueError(f'Node of type {self.type} cannot contain value.')

pyconfigtree/source/json.py

@@ -0,0 +1,41 @@
+import json
+from typing import Any
+from pathlib import Path
+
+from .base import NodeInfo, NodeType, ConfigSource
+
+
+class JSONSource(ConfigSource):
+    def __init__(self, path: str | Path, encoding: str = 'utf-8') -> None:
+        self._path = Path(path)
+        self._encoding = encoding
+
+    async def load(self) -> dict[str, Any]:
+        with open(self._path, 'r', encoding=self.encoding) as f:
+            return json.load(f)  # type: ignore
+
+    async def save(self, data: NodeInfo) -> None:
+        dicted = self.node_info_to_dict(data)
+        with open(self._path, 'w', encoding=self.encoding) as f:
+            json.dump(dicted, f, indent=4)
+        return
+
+    def node_info_to_dict(self, node: NodeInfo) -> Any:
+        if node.type is NodeType.LEAF:
+            return node.value
+        return {k: self.node_info_to_dict(v) for k, v in node.subnodes.items()}
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def encoding(self) -> str:
+        return self._encoding
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, JSONSource):
+            return self.path == other.path
+        if isinstance(other, (str, Path)):
+            return self.path == Path(other)
+        return False

pyconfigtree/source/toml.py

@@ -0,0 +1,43 @@
+from typing import Any
+from pathlib import Path
+
+import tomli_w
+import tomllib  # type: ignore
+
+from .base import NodeInfo, NodeType, ConfigSource
+
+
+class TOMLSource(ConfigSource):
+    def __init__(self, path: str | Path, encoding: str = 'utf-8') -> None:
+        self._path = Path(path)
+        self._encoding = encoding
+
+    async def load(self) -> dict[str, Any]:
+        with open(self._path, 'rb') as f:
+            return tomllib.load(f)  # type: ignore
+
+    async def save(self, data: NodeInfo) -> None:
+        dicted = self.node_info_to_dict(data)
+        with open(self._path, 'w', encoding='utf-8') as f:
+            f.write(tomli_w.dumps(dicted, multiline_strings=True, indent=4))
+        return
+
+    def node_info_to_dict(self, node: NodeInfo) -> Any:
+        if node.type is NodeType.LEAF:
+            return node.value
+        return {k: self.node_info_to_dict(v) for k, v in node.subnodes.items()}
+
+    @property
+    def path(self) -> Path:
+        return self._path
+
+    @property
+    def encoding(self) -> str:
+        return self._encoding
+
+    def __eq__(self, other: Any) -> bool:
+        if isinstance(other, TOMLSource):
+            return self.path == other.path
+        if isinstance(other, (str, Path)):
+            return self.path == Path(other)
+        return False

pyconfigtree-0.1.0.dist-info/METADATA

@@ -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-info/RECORD

@@ -0,0 +1,19 @@
+pyconfigtree/__init__.py,sha256=TFRM-hfFZvku9kXrzzHJs8cUXDn6kB2SbodICyhKv48,78
+pyconfigtree/base.py,sha256=1gQG7V803Omw-iAXPuq7IiwQZ0A7qwCBTILx2wUvtIU,8955
+pyconfigtree/exceptions.py,sha256=6WrZE6y9_TsgpTb2DPMC-jEv9r9O0z9GmxUUlkPPhXQ,588
+pyconfigtree/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyconfigtree/parameter/__init__.py,sha256=kHEB8nrbMjsQh-zFk5c11Js0Ko3KZeLw44HEK-Hk5Pc,381
+pyconfigtree/parameter/base.py,sha256=lHVjdApfr1kiU8WkcLIg3epecVqWkFjSXziSrntl2R8,8237
+pyconfigtree/parameter/bool_parameter.py,sha256=t9piL_6w_FnXG46KoYFRkOxbwTwzUHYWpjou7GwyyIk,1605
+pyconfigtree/parameter/choice_parameter.py,sha256=YFlawqSRjmjAkpXGEVvxq66dEXsFeilX3v1O39hx0Hg,2644
+pyconfigtree/parameter/float_parameter.py,sha256=WRx-rY2426U9IFoliSOJ9TZ-Regeg9lCglqHgbDYkvM,550
+pyconfigtree/parameter/int_parameter.py,sha256=6UQgFLF6Wcali3TcS60LYaoaN2pvrYMtFWIphU46S34,518
+pyconfigtree/parameter/list_parameter.py,sha256=kZJA0CNq6j2UK92QxkxJQ5iR6sAsgJsAQfOcsCoIAN8,4365
+pyconfigtree/parameter/string_parameter.py,sha256=5uR_RfXm3O3hl-voocM6Pha97TyxuQ96FhzCbyoxHiM,530
+pyconfigtree/source/__init__.py,sha256=7O2UoHfcjlQZKeQkJzxXdh73ovkj2et_yQoqqvndqTc,90
+pyconfigtree/source/base.py,sha256=cSelegHJUkTAGnq1zxLCbkq0OPih4d-HrQ95J6aot0o,1088
+pyconfigtree/source/json.py,sha256=gkOgDid4M7rClD6NhORedtRN79KS0RSPWNHUin9JTl4,1252
+pyconfigtree/source/toml.py,sha256=WlgMvXc8pJfBUNcneA7609ryJ1BVTiT_mIp-cz5MgRI,1295
+pyconfigtree-0.1.0.dist-info/METADATA,sha256=AqmWUG8tXPRW6GC8ugzFqpHJNUrU7gxCSeRQbxpmM-w,292
+pyconfigtree-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pyconfigtree-0.1.0.dist-info/RECORD,,

pyconfigtree-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any