notifig 0.1.0__py3-none-any.whl

notifig/__init__.py

@@ -0,0 +1,60 @@
+"""
+This project exists to allow a living Config to exist as the single
+source-of-truth for every persistent value in a project's settings.
+
+It's built on modern python with strict pydantic typing and
+highly declarative, reactive principles. Declaration is behavior.
+
+It can interact with several file formats for saving/loading,
+supports both plain python syntax as well as config path semantics,
+offers sync and async update notifications, declarative CLI flags,
+field values restricted by Choice, static and dynamic section entries,
+field links.
+"""
+
+from __future__ import annotations
+
+from .annotations import (
+    AbsolutePath,
+    Choice,
+    CliFlags,
+    CommaSeparated,
+    Link,
+    Path,
+    PathPattern,
+)
+from .changes import ConfigChange, Created, Deleted, Updated
+from .config import Config
+from .exceptions import (
+    AsyncObserversNotCalled,
+    EntryRequiresData,
+    NotASection,
+    PathNotFound,
+)
+from .meta import ConfigDict
+from .section.dynamic import DynamicSection
+from .section.static import ConfigSection
+from .sources import FILE_EXTENSIONS
+
+__all__ = [
+    "Config",
+    "ConfigDict",
+    "ConfigSection",
+    "DynamicSection",
+    "Choice",
+    "CliFlags",
+    "CommaSeparated",
+    "Link",
+    "Path",
+    "AbsolutePath",
+    "PathPattern",
+    "PathNotFound",
+    "NotASection",
+    "EntryRequiresData",
+    "AsyncObserversNotCalled",
+    "FILE_EXTENSIONS",
+    "ConfigChange",
+    "Updated",
+    "Deleted",
+    "Created",
+]

notifig/annotations/__init__.py

@@ -0,0 +1,15 @@
+from .choice import Choice
+from .cli_flags import CliFlags
+from .comma_list import CommaSeparated
+from .link import Link
+from .path import AbsolutePath, Path, PathPattern
+
+__all__ = [
+    "Choice",
+    "CliFlags",
+    "CommaSeparated",
+    "Link",
+    "Path",
+    "AbsolutePath",
+    "PathPattern",
+]

notifig/annotations/choice.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import operator
+import typing
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler
+from pydantic.fields import FieldInfo
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import CoreSchema, core_schema
+
+
+# `eq=False` is important to maintain. Without it, pydantic can try to derive __eq__/__hash__
+#  from fields (for caching on schema generation), and since `entries` is a Mapping it would
+#  raise on an unhashable dict. `eq=False` maintains identity through object.__hash__.
+@dataclass(frozen=True, slots=True, eq=False)
+class Choice:
+    entries: Mapping[str, Any]
+    # Optional reverse mapping: how to get the name from an entry
+    key: Callable[[Any], str] = operator.attrgetter("name")
+    label: str = ""
+
+    @classmethod
+    def of(cls, field_info: FieldInfo) -> Choice | None:
+        """Returns the Choice for a field, if it exists."""
+        for annotation in field_info.metadata:
+            if isinstance(annotation, Choice):
+                return annotation
+        return None
+
+    @property
+    def options(self) -> list[str]:
+        return sorted(self.entries)
+
+    def __get_pydantic_core_schema__(
+        self, source: Any, handler: GetCoreSchemaHandler
+    ) -> CoreSchema:
+        """Defines how to validate and serialize `source` using `handler`."""
+        args = typing.get_args(source)
+        member = next((a for a in args if a is not type(None)), source)
+        label = self.label or getattr(member, "__name__", "entry")
+
+        def to_member(value):
+            if not isinstance(value, str):
+                return value
+            try:
+                return self.entries[value]
+            except KeyError as error:
+                raise ValueError(
+                    f"Not a valid {label}. Use one of {self.options}"
+                ) from error
+
+        schema = core_schema.json_or_python_schema(
+            # On the wire an option is its name, so it validates as a string first.
+            json_schema=core_schema.chain_schema(
+                [
+                    core_schema.str_schema(),
+                    core_schema.no_info_plain_validator_function(to_member),
+                ]
+            ),
+            # In Python it is usually the member itself, sometimes still a name.
+            python_schema=core_schema.no_info_plain_validator_function(to_member),
+            # How pydantic serializes instances
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                self.key, return_schema=core_schema.str_schema(), when_used="json"
+            ),
+        )
+        # Whether None is legal is the annotation's to say.
+        return core_schema.nullable_schema(schema) if type(None) in args else schema
+
+    def __get_pydantic_json_schema__(
+        self, schema: dict[str, Any], handler: GetJsonSchemaHandler
+    ) -> JsonSchemaValue:
+        json_schema = handler(core_schema.str_schema())
+        json_schema.update(type="string", enum=self.options)
+        return json_schema

notifig/annotations/cli_flags.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# `init=False` ensures the dataclass doesn't auto-generate an __init__.
+# Without it, we'd be forced to instantiate with `CliFlags(["-u", "--url"])`
+#  instead of `CliFlags("-u", "--url")`
+@dataclass(frozen=True, slots=True, init=False)
+class CliFlags:
+    flags: tuple[str, ...]
+
+    def __init__(self, *flags) -> None:
+        # NOTE: Not a real hack, this is the documented way to expose an alternative
+        #  constructor with a frozen dataclass. The alternative is using `.of(*flags)`
+        object.__setattr__(self, "flags", flags)
+
+    def to_argparse(self) -> list[str]:
+        return [
+            (f"{'-' if len(flag) == 1 else '--'}{flag.replace('_', '-')}")
+            for flag in self.flags
+        ]

notifig/annotations/comma_list.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Annotated, TypeVar
+
+from pydantic import BeforeValidator, PlainSerializer
+from pydantic_settings import NoDecode
+
+T = TypeVar("T")
+CommaSeparated = Annotated[
+    list[T],
+    # Don't try to decode early with a default validator
+    NoDecode,
+    # Converts "a, bb,c," -> ["a", "bb", "c"]
+    BeforeValidator(
+        lambda value: (
+            [token.strip() for token in value.split(",") if token.strip()]
+            if isinstance(value, str)
+            else value
+        )
+    ),
+    # Serializes ["a", "bb", "c"] -> "a,bb,c"
+    PlainSerializer(
+        lambda seq: ",".join(str(token) for token in seq),
+        when_used="json",
+    ),
+]

notifig/annotations/link.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Self, overload
+
+if TYPE_CHECKING:
+    from notifig.section.static import ConfigSection
+
+
+@dataclass(frozen=True)
+class Link[T]:
+    """
+    A read-only reference to a field elsewhere in the same config.
+
+    Stores nothing: every read follows `source_path` to the source field, so the
+    link always shows the source's current value. A path starting with `/` is
+    read from the root of the config the section is attached to; any other path
+    is read from the section itself.
+    ```python
+        class FileToolConfig(ConfigSection):
+            ignored_paths: ClassVar[Link[list[PathPattern]]] = Link("/files.ignored_paths")
+    ```
+    Declared as a `ClassVar`, so pydantic doesn't treat it as a field: it isn't
+    validated, exported or editable, and writing to it raises.
+    """
+
+    source_path: str
+
+    def __post_init__(self) -> None:
+        if not self.source_path.removeprefix("/"):
+            raise ValueError(
+                f"A link needs a path to a field, got {self.source_path!r}"
+            )
+
+    # NOTE: Python calls `__get__` on attribute lookup: `section.link` passes the
+    #  instance, `SectionClass.link` passes None and gets the Link itself.
+    @overload
+    def __get__(self, section: None, owner: Any = None) -> Self: ...
+    @overload
+    def __get__(self, section: ConfigSection, owner: Any = None) -> T: ...
+    def __get__(self, section: ConfigSection | None, owner: Any = None) -> Self | T:
+        if section is None:
+            return self
+        if not self.source_path.startswith("/"):
+            return section.get(self.source_path)
+        root = section
+        while root._parent is not None:
+            root = root._parent
+        if root is section:
+            raise ValueError(
+                f"{type(section).__name__} isn't attached to a config, "
+                f"so its link to {self.source_path!r} can't be read"
+            )
+        return root.get(self.source_path.removeprefix("/"))

notifig/annotations/path.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import pathlib
+from typing import Annotated
+
+from pydantic import BeforeValidator, PlainSerializer
+
+Path = Annotated[
+    pathlib.Path,
+    BeforeValidator(lambda value: pathlib.Path(value)),
+    PlainSerializer(str, return_type=str, when_used="json"),
+]
+
+AbsolutePath = Annotated[
+    pathlib.Path,
+    BeforeValidator(lambda value: pathlib.Path(value).expanduser().resolve()),
+    PlainSerializer(str, return_type=str, when_used="json"),
+]
+
+
+def _resolve_pattern(value) -> pathlib.Path:
+    path = pathlib.Path(value)
+    # Don't expand bare names, unlike AbsolutePath
+    if str(path) == path.name:
+        return path
+    return path.expanduser().resolve()
+
+
+PathPattern = Annotated[
+    pathlib.Path,
+    BeforeValidator(_resolve_pattern),
+]

notifig/changes.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ConfigChange:
+    path: str
+
+
+@dataclass(frozen=True)
+class Created(ConfigChange):
+    value: Any  # what appeared
+
+
+@dataclass(frozen=True)
+class Updated(ConfigChange):
+    before: Any
+    after: Any
+
+
+@dataclass(frozen=True)
+class Deleted(ConfigChange):
+    value: Any  # what left

notifig/config.py

@@ -0,0 +1,89 @@
+import sys
+from typing import override
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, CliSettingsSource
+
+from .annotations import AbsolutePath, CommaSeparated
+from .meta import ConfigDict
+from .section.static import ConfigSection
+from .sources import ConfigFileSource
+
+
+class Config(BaseSettings, ConfigSection):
+    model_config = ConfigDict(
+        cli_avoid_json=True,
+        cli_exit_on_error=False,
+        cli_kebab_case=True,
+        cli_implicit_flags=True,
+        cli_enforce_required=False,
+        default_config_files=[],
+    )
+
+    # Whether to read `sys.argv`. An internal switch, never saved or edited
+    parse_cli: bool = Field(default=True, exclude=True)
+    # Config file paths read, sorted lowest -> highest priority.
+    # Add flags and defaults for this field using:
+    #  `ConfigDict(cli_shortcuts={"config_files":["c", "config"]}, default_config_files=["~/config.json"])`
+    config_files: CommaSeparated[AbsolutePath] = Field(
+        default_factory=list, exclude=True
+    )
+
+    @override
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls,
+        init_settings,
+        env_settings,
+        dotenv_settings,
+        file_secret_settings,
+    ):
+        """Build the settings-source stack. CLI args flow through `cli_parse_args`;
+        `--config` flags are split out for ConfigFileSource."""
+        # Parse CLI args list. If `parse_cli` is absent from init_kwargs,
+        # then it wasn't passed, use field default
+        parse_cli: bool | None = init_settings.init_kwargs.get("parse_cli")
+        if parse_cli is None:
+            parse_cli = settings_cls.model_fields["parse_cli"].get_default()
+        argv = sys.argv[1:] if parse_cli else []
+
+        # A key must match the flag name pydantic-settings generated for the field,
+        #  which `cli_kebab_case` makes kebab-case: `max_context` -> `max-context`,
+        #  a nested field -> `api.max-context`. Values are used verbatim, with no
+        #  case conversion, and a one-character value gets a single dash. Expected:
+        #  {"path.to.my-section": ["my-section", "m"]}
+        #  Creates: `--my-section` and `-m`
+        # Shortcuts from `model_config` (for inherited fields), then from each
+        #  field's own `CliFlags`. A value may be one flag or a list of them.
+        shortcuts: dict[str, list[str]] = {}
+        for path, flags in (cls.model_config.get("cli_shortcuts") or {}).items():
+            shortcuts[path.replace("_", "-")] = (
+                [flags] if isinstance(flags, str) else list(flags)
+            )
+        for path, all_cli_flags in cls._cli_flags_from_schema().items():
+            shortcuts.setdefault(path.replace("_", "-"), []).extend(
+                flag for cli_flags in all_cli_flags for flag in cli_flags.flags
+            )
+        # A flag can only belong to one field, wherever it was declared
+        claimed_by: dict[str, str] = {}
+        for path, flags in shortcuts.items():
+            for flag in flags:
+                if flag in claimed_by:
+                    raise ValueError(
+                        f"Flag {flag!r} is claimed by both "
+                        f"{claimed_by[flag]!r} and {path!r}"
+                    )
+                claimed_by[flag] = path
+
+        # Precedence high->low: init kwargs, CLI, env, then config files.
+        return (
+            init_settings,
+            CliSettingsSource(
+                settings_cls,
+                cli_parse_args=argv,
+                cli_shortcuts=shortcuts,
+            ),
+            env_settings,
+            ConfigFileSource(settings_cls),
+        )

notifig/exceptions.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from pydantic import BaseModel
+
+
+class PathNotFound(AttributeError):
+    def __init__(self, model: type[BaseModel], path: str) -> None:
+        super().__init__(f"{model.__name__!r} does not contain {path!r}")
+
+
+class NotASection(AttributeError):
+    def __init__(self, name: str, path: str | None = None) -> None:
+        msg = f"{name} is not a section"
+        if path:
+            msg = f"{path!r}: {msg}"
+        super().__init__(msg)
+
+
+class EntryRequiresData(ValueError):
+    """A section was asked to give a name a type that its data cannot build.
+
+    Raised when the entry type declares fields with no default, and the data the
+    section has for the entry — nothing, an incomplete block, or another entry's
+    own values — carries none for them. A caller that can live without the entry
+    catches this and decides what the absence means; a caller that needs the
+    entry lets it travel.
+    """
+
+    def __init__(
+        self,
+        model: type[BaseModel],
+        name: str,
+        missing_fields: Sequence[str],
+    ) -> None:
+        self.model = model
+        self.name = name
+        self.missing_fields = list(missing_fields)
+        fields = ", ".join(repr(field) for field in self.missing_fields)
+        plural = len(self.missing_fields) > 1
+        super().__init__(
+            f"the {name!r} entry cannot be built as {model.__name__!r}: {fields} "
+            f"{'have' if plural else 'has'} no default, and the data available for the "
+            f"entry carries no value for {'them' if plural else 'it'}. Declare a "
+            f"default, or let {'them' if plural else 'it'} accept absence."
+        )
+
+
+class AsyncObserversNotCalled(RuntimeError):
+    """
+    At least one async observer was found when attempting to set a value in a
+    context that cannot return or call it (ex: `section[name]=value`).
+    """
+
+    def __init__(
+        self, path: str, callbacks: Sequence[str], applied: bool = False
+    ) -> None:
+        self.path = path
+        self.callbacks = list(callbacks)
+        if applied:
+            tail = (
+                "The change was applied and sync observers were notified; the async "
+                "observers were not called and will not run until the next change "
+                "to this path."
+            )
+        else:
+            tail = (
+                "Nothing was applied. Write this path with `section.set(...)` and "
+                "await what it returns, or `await section.set_and_wait(...)`."
+            )
+        super().__init__(
+            f"the {path!r} change reaches async observer(s) {', '.join(self.callbacks)}, "
+            f"which a plain assignment can neither run nor return. {tail}"
+        )

notifig/meta.py

@@ -0,0 +1,16 @@
+"""Describes a Config's own config."""
+
+from os import PathLike
+
+from pydantic_settings import SettingsConfigDict
+
+
+class ConfigDict(SettingsConfigDict, total=False):
+    """
+    Takes pydantic-settings defaults like `cli_shortcuts`.
+    Adds `default_config_files`, the default files to read a config from
+    if none was specified.
+    """
+
+    # Config files read when no source names any; each is read only if it exists
+    default_config_files: list[str | PathLike]

notifig/section/__init__.py

@@ -0,0 +1,7 @@
+from .dynamic import DynamicSection
+from .static import ConfigSection
+
+__all__ = [
+    "ConfigSection",
+    "DynamicSection",
+]