model-lib 0.99.1__tar.gz

model_lib-0.99.1/.gitignore

@@ -0,0 +1,40 @@
+# path-sync copy -n python-template
+
+# === DO_NOT_EDIT: path-sync gitignore ===
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environments
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.egg-info/
+
+# Coverage
+.coverage
+htmlcov/
+coverage.xml
+
+# Cache directories
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/
+
+# IDE
+.idea/
+*.iml
+.vscode/
+
+# pkg-ext dev mode files
+.groups-dev.yaml
+CHANGELOG-dev.md
+*.api-dev.yaml
+
+# MkDocs build output
+site/
+# === OK_EDIT: path-sync gitignore ===

model_lib-0.99.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Espen Albert
+
+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.

model_lib-0.99.1/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: model-lib
+Version: 0.99.1
+Summary: Pydantic model utilities for serialization and settings
+Author-email: EspenAlbert <espen.albert1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.13
+Requires-Dist: pydantic-settings>=2.8
+Requires-Dist: pydantic>=2.11
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: zero-3rdparty
+Provides-Extra: toml
+Requires-Dist: tomli-w~=1.1.0; extra == 'toml'
+Description-Content-Type: text/markdown
+
+# model-lib

model_lib-0.99.1/README.md

@@ -0,0 +1 @@
+# model-lib

model_lib-0.99.1/model_lib/__init__.py

@@ -0,0 +1,5 @@
+# Generated by pkg-ext
+# flake8: noqa
+
+VERSION = "0.99.1"
+__all__ = []

model_lib-0.99.1/model_lib/base_settings.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Generic, TypeVar
+
+from pydantic import Field
+from pydantic.fields import FieldInfo
+from zero_3rdparty.run_env import running_in_container_environment
+
+logger = logging.getLogger(__name__)
+
+
+def env_value_as_str(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, Path | bool | float | int):
+        value = str(value)
+    if isinstance(value, list | dict):
+        value = json.dumps(value)
+    assert isinstance(value, str), f"env value must be str, was {value!r}"
+    return value
+
+
+T = TypeVar("T")
+
+
+def container_or_default(container_default: T, cls_default: T) -> FieldInfo:
+    return Field(default_factory=DockerOrClsDefDefault(docker_default=container_default, cls_default=cls_default))  # type: ignore
+
+
+@dataclass
+class DockerOrClsDefDefault(Generic[T]):
+    docker_default: T
+    cls_default: T
+
+    def __call__(self) -> T:
+        if running_in_container_environment():
+            return self.docker_default
+        return self.cls_default
+
+
+def port_info(number: int, *, url_prefix: str, protocol: str) -> int:
+    """Used for pants plugin "artifacts" to know which url_prefix and protocol
+    to use in Chart."""
+    return Field(default=number)

model_lib-0.99.1/model_lib/constants.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+from typing import Callable, TypeVar, Union
+
+from zero_3rdparty.enum_utils import StrEnum
+
+RegisteredPayloadT = TypeVar("RegisteredPayloadT")
+PayloadT = Union[RegisteredPayloadT, str, bytes, Path, dict, list]
+ModelRawT = Union[dict, list]
+METADATA_DUMP_KEY = "metadata"
+MODEL_DUMP_KEY = "model"
+METADATA_MODEL_NAME_FIELD = "model_name"
+METADATA_MODEL_NAME_BACKUP_FIELD = "model_name_backup"
+
+
+class FileFormat(StrEnum):
+    json = "json"
+    pretty_json = "pretty_json"
+    json_pretty = "json_pretty"
+    yaml = "yaml"
+    yml = "yml"
+    # only recommended to use with pydantic2
+    json_pydantic = "json_pydantic"
+    pydantic_json = "pydantic_json"
+    # pip install tomlkit
+    toml = "toml"
+    toml_compact = "toml_compact"
+
+
+FileFormatT = Union[FileFormat, str]
+PayloadParser = Callable[[RegisteredPayloadT, FileFormatT], ModelRawT]

model_lib-0.99.1/model_lib/dump_functions.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import pydantic
+from pydantic import BaseModel, RootModel, model_serializer
+from zero_3rdparty.iter_utils import ignore_falsy
+
+from model_lib.model_dump import register_dumper
+
+
+def base_model_dumper(model: BaseModel):
+    if isinstance(model, RootModel):
+        return model.root
+    fields = model.model_fields  # type: ignore
+    return {key: value for key, value in model if key in fields}
+
+
+class IgnoreFalsy(BaseModel):
+    @model_serializer(mode="wrap")
+    def _ignore_falsy(
+        self,
+        nxt: pydantic.SerializerFunctionWrapHandler,
+    ):
+        serialized = nxt(self)
+        no_falsy = ignore_falsy(**serialized)  # type: ignore
+        return self.dump_dict_modifier(no_falsy)
+
+    def dump_dict_modifier(self, payload: dict) -> dict:
+        return payload
+
+
+register_dumper(BaseModel, base_model_dumper)

model_lib-0.99.1/model_lib/errors.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import Any, Type, TypeVar
+
+from zero_3rdparty.error import BaseError
+
+from model_lib.constants import FileFormat, PayloadT
+
+T = TypeVar("T")
+
+
+class UnknownModelError(BaseError):
+    def __init__(self, model_name: str):
+        self.model_name: str = model_name
+
+
+class ClsNameAlreadyExist(BaseError):
+    def __init__(self, new_cls_path: str, old_cls_path: str):
+        self.new_cls_path = new_cls_path
+        self.old_cls_path = old_cls_path
+
+
+class NoDumper(Exception):
+    def __init__(self, instance_type: Type[T]):
+        self.instance_type = instance_type
+
+
+class DumperExist(Exception):
+    def __init__(self, existing_type: Type, new_type: Type):
+        self.existing_type = existing_type
+        self.new_type = new_type
+
+
+class EnvVarParsingFailure(BaseError):
+    def __init__(self, errors: list[Any]):
+        self.errors = errors
+
+
+class ParseError(BaseError):
+    pass
+
+
+class PayloadParserNotFoundError(ParseError):
+    def __init__(self, payload: object, format: FileFormat):
+        self.payload = payload
+        self.format = format
+
+
+class PayloadError(ParseError):
+    def __init__(self, payload: PayloadT, message: str, metadata: dict | None = None):
+        self.message = message
+        self.payload = payload
+        self.metadata = metadata
+
+
+class DumpConfigureError(BaseError):
+    pass
+
+
+class PayloadParserAlreadyExistError(DumpConfigureError):
+    def __init__(self, old_call_name: str, new_call_name: str):
+        self.old_call_name = old_call_name
+        self.new_call_name = new_call_name

model_lib-0.99.1/model_lib/metadata/__init__.py

@@ -0,0 +1,36 @@
+"""isort:skip_file."""
+
+from model_lib.metadata.metadata import (
+    current_metadata,
+    metadata_from_context_dict,
+    pop_metadata,
+    read_metadata,
+    read_metadata_or_none,
+    set_metadata,
+    update_metadata,
+)
+from model_lib.metadata.metadata_dump import (
+    add_metadata_dumper,
+    dump_metadata,
+    get_metadata_dumpers,
+    metadata_dumper,
+    set_metadata_dumpers,
+)
+from model_lib.metadata.metadata_fields import EventMetadata, iter_tags
+
+__all__ = (
+    "EventMetadata",
+    "add_metadata_dumper",
+    "current_metadata",
+    "dump_metadata",
+    "get_metadata_dumpers",
+    "iter_tags",
+    "metadata_dumper",
+    "metadata_from_context_dict",
+    "pop_metadata",
+    "read_metadata",
+    "read_metadata_or_none",
+    "set_metadata",
+    "set_metadata_dumpers",
+    "update_metadata",
+)

model_lib-0.99.1/model_lib/metadata/context_dict.py

@@ -0,0 +1,205 @@
+"""A dictionary with values specific to a thread/task Useful for:
+
+- current Request in a http handler
+- metadata during event processing
+- storing unhandled errors
+"""
+
+from __future__ import annotations
+
+from asyncio import Task, create_task
+from collections import UserDict
+from contextlib import suppress
+from contextvars import Context, ContextVar
+from dataclasses import dataclass
+from typing import Callable, Coroutine, Protocol, TypeVar, Union
+
+from typing_extensions import TypeAlias
+from zero_3rdparty.object_name import as_name
+
+T = TypeVar("T")
+KeyT: TypeAlias = Union[type, str]
+
+
+def identity(value: T) -> T:
+    return value
+
+
+class ParentChildCopy(Protocol):
+    def __call__(
+        self,
+        parent: LocalDict,
+        child: LocalDict,
+        is_new_thread: bool,
+        func_name: str,
+    ) -> None: ...
+
+
+@dataclass
+class CopyConfig:
+    """
+    >>> c1 = CopyConfig()
+    >>> c1.copy_to_thread
+    False
+    >>> c1.copy_to_task
+    True
+    """
+
+    never: bool = False
+    thread_copy: bool | Callable[[], bool] = False
+    task_copy: bool | Callable[[], bool] = True
+    copy_func: Callable[[T], T] = identity  # type: ignore
+    # is thread
+    on_copy_done: ParentChildCopy | None = None
+
+    @property
+    def copy_to_thread(self) -> bool:
+        if self.never:
+            return False
+        thread_copy = self.thread_copy
+        if isinstance(thread_copy, bool):
+            return thread_copy
+        return thread_copy()
+
+    @property
+    def copy_to_task(self) -> bool:
+        if self.never:
+            return False
+        task_copy = self.task_copy
+        if isinstance(task_copy, bool):
+            return task_copy
+        return task_copy()
+
+
+_copy_config: dict[KeyT, CopyConfig] = {}
+DEFAULT_CONFIG = CopyConfig()
+assert not DEFAULT_CONFIG.copy_to_thread
+assert DEFAULT_CONFIG.copy_to_task
+
+
+def copy_value(key: KeyT, value: T) -> T:
+    config = get_copy_behavior(key) or DEFAULT_CONFIG
+    return config.copy_func(value)  # type: ignore
+
+
+def set_copy_behavior(t: KeyT, config: CopyConfig) -> None:
+    global _copy_config
+    _copy_config[t] = config
+
+
+def get_copy_behavior(t: KeyT) -> CopyConfig | None:
+    return _copy_config.get(t)
+
+
+class LocalDict(UserDict):
+    def set_instance(self, instance: T) -> T | None:
+        """Returns the previous instance if set."""
+        instance_type = type(instance)
+        old = self.get(instance_type, None)
+        self[instance_type] = instance
+        return old
+
+    def get_instance(self, instance_type: type[T]) -> T:
+        return self[instance_type]
+
+    def get_instance_or_none(self, instance_type: type[T]) -> T | None:
+        return self.get(instance_type)
+
+    def pop_instance(self, instance_type: type[T]) -> T | None:
+        return self.pop(instance_type, None)
+
+    def copy_to_new_thread(self, thread_name: str) -> LocalDict:
+        on_done_calls = []
+
+        def should_include(t: KeyT) -> bool:
+            config = get_copy_behavior(t) or DEFAULT_CONFIG
+            if on_done := config.on_copy_done:
+                on_done_calls.append(on_done)
+            return config.copy_to_thread
+
+        copy = LocalDict({key: copy_value(key, value) for key, value in self.items() if should_include(key)})
+        for call in on_done_calls:
+            call(self, copy, True, thread_name)
+        return copy
+
+    def copy_to_new_task(self, task_name: str) -> LocalDict:
+        on_done_calls = []
+
+        def should_include(t: KeyT):
+            config = get_copy_behavior(t) or DEFAULT_CONFIG
+            if on_done := config.on_copy_done:
+                on_done_calls.append(on_done)
+            return config.copy_to_task
+
+        copy = LocalDict({key: copy_value(key, value) for key, value in self.items() if should_include(key)})
+        for call in on_done_calls:
+            call(self, copy, False, task_name)
+        return copy
+
+
+_context_dict: ContextVar[LocalDict] = ContextVar(f"{__name__}.LocalDict")
+
+
+def get_context_dict() -> LocalDict:
+    try:
+        local_dict = _context_dict.get()
+    except LookupError:
+        local_dict = LocalDict()
+        _context_dict.set(local_dict)
+        return local_dict
+    if local_dict is ...:
+        local_dict = LocalDict()
+        _context_dict.set(local_dict)
+    return local_dict
+
+
+def set_context_dict(context_dict: LocalDict):
+    _context_dict.set(context_dict)
+
+
+def force_new_context_dict_on_task(task_name: str = "unknown"):
+    old = get_context_dict()
+    new = old.copy_to_new_task(task_name)
+    set_context_dict(new)
+
+
+def create_task_copy_context(awaitable: Coroutine) -> Task:
+    old = get_context_dict()
+    task_name = as_name(awaitable)
+    new = old.copy_to_new_task(task_name)
+
+    def start_task():
+        set_context_dict(new)
+        return create_task(awaitable)
+
+    return Context().run(start_task)
+
+
+def clear_context_dict():
+    """Ideally we would _context.dict.reset(token) but we have no token But
+    this is usually only needed for testing."""
+    try:
+        old = _context_dict.get()
+    except LookupError:
+        return
+    if old is ...:
+        return
+    _context_dict.set(...)  # type: ignore
+
+
+def get_context_instance(t: type[T]) -> T:
+    return get_context_dict().get_instance(t)
+
+
+def get_context_instance_or_none(t: type[T]) -> T | None:
+    with suppress(KeyError):
+        return get_context_instance(t)
+    return None
+
+
+def set_context_instance(t: T) -> T | None:
+    return get_context_dict().set_instance(t)
+
+
+def pop_context_instance(t: type[T]) -> T | None:
+    return get_context_dict().pop_instance(t)

model_lib-0.99.1/model_lib/metadata/metadata.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from contextlib import suppress
+from copy import deepcopy
+from typing import Any, Iterable, Mapping, TypeVar
+
+from model_lib.metadata.context_dict import (
+    CopyConfig,
+    LocalDict,
+    get_context_dict,
+    set_copy_behavior,
+)
+
+_METADATA_LOCAL_KEY = __name__
+T = TypeVar("T")
+
+
+set_copy_behavior(  # type: ignore
+    _METADATA_LOCAL_KEY,
+    CopyConfig(
+        thread_copy=True,
+        task_copy=True,
+        copy_func=deepcopy,
+    ),
+)
+
+
+def update_metadata(metadata: Mapping[str, Any] | Iterable[tuple[str, Any]]) -> dict:
+    metadata_in_context = current_metadata()
+    metadata_in_context.update(metadata)
+    return metadata_in_context
+
+
+def current_metadata() -> dict[str, Any]:
+    context_dict = get_context_dict()
+    return metadata_from_context_dict(context_dict)
+
+
+def metadata_from_context_dict(context_dict: LocalDict) -> dict:
+    return context_dict.setdefault(_METADATA_LOCAL_KEY, {})
+
+
+def read_metadata(key: str) -> Any:
+    """Raises KeyError."""
+    return current_metadata()[key]
+
+
+def read_metadata_or_none(key: str) -> Any:
+    with suppress(KeyError):
+        return read_metadata(key)
+
+
+def set_metadata(key: str, value: Any) -> None:
+    metadata = current_metadata()
+    metadata[key] = value
+
+
+def pop_metadata(key: str, default: T | None = None) -> T | None:
+    metadata = current_metadata()
+    return metadata.pop(key, default)

model_lib-0.99.1/model_lib/metadata/metadata_dump.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import logging
+from contextlib import suppress
+from copy import deepcopy
+from time import time
+from typing import Any, Callable
+from uuid import uuid4
+
+from typing_extensions import TypeAlias
+from zero_3rdparty.object_name import as_name
+
+from model_lib.metadata.metadata import current_metadata
+from model_lib.metadata.metadata_fields import EventMetadata
+
+logger = logging.getLogger(__name__)
+MetadataDumper = Callable[[dict], Any]
+RemoveDumper: TypeAlias = Callable[[], None]
+_dumpers: list[MetadataDumper] = []
+
+
+def set_metadata_dumpers(*calls: MetadataDumper) -> None:
+    global _dumpers
+    _dumpers = list(calls)
+
+
+def _no_removal():
+    return None
+
+
+def add_metadata_dumper(call: MetadataDumper) -> RemoveDumper:
+    global _dumpers
+    call_names = {as_name(call): call for call in _dumpers}
+    call_name = as_name(call)
+    if same_name_call := call_names.get(call_name):
+        if same_name_call is call:
+            logger.warning(f"metadat_dump_call_already_added={call_name}")
+            return _no_removal
+        _dumpers.remove(same_name_call)
+    _dumpers.append(call)
+
+    def remove():
+        with suppress(ValueError):
+            _dumpers.remove(call)
+
+    return remove
+
+
+def get_metadata_dumpers() -> list[MetadataDumper]:
+    return _dumpers
+
+
+def dump_metadata(skip_dumpers: bool = False) -> dict:
+    metadata = current_metadata()
+    dumped_metadata = deepcopy(metadata)
+    if not skip_dumpers:
+        for dumper in _dumpers:
+            dumper(dumped_metadata)
+    return dumped_metadata
+
+
+class metadata_dumper:
+    def __init__(
+        self,
+        static_dict: dict,
+        dump_event_id: bool = True,
+        dump_time: bool = True,
+        extra_calls: list[MetadataDumper] | None = None,
+        remove_existing: bool = False,
+    ):
+        self.calls = calls = [] if remove_existing else list(get_metadata_dumpers())
+        if static_dict:
+
+            def add_static_metadata(metadata: dict):
+                metadata |= static_dict
+
+            calls.append(add_static_metadata)
+        if dump_event_id:
+
+            def add_event_id(metadata: dict):
+                metadata[EventMetadata.event_id] = uuid4().hex
+
+            self.calls.append(add_event_id)
+        if dump_time:
+
+            def add_ts(metadata: dict):
+                metadata[EventMetadata.dump_time] = time()
+
+            self.calls.append(add_ts)
+        calls.extend(extra_calls or [])
+
+    def __enter__(self):
+        self.old_dumpers = get_metadata_dumpers()
+        set_metadata_dumpers(*self.calls)
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        set_metadata_dumpers(*self.old_dumpers)

model_lib-0.99.1/model_lib/metadata/metadata_fields.py

@@ -0,0 +1,29 @@
+"""Example of metadata to use when dumping."""
+
+from typing import Any, Iterable
+
+
+class EventMetadata:
+    task_id_parent = "task_id_parent"
+    topic = "topic"
+    topic_prefix = "topic_prefix"
+    tags = "tags"  #: a list of [(key, value)] pairs
+    app_id = "app_id"
+    task_level = "task_level"  # see Action.task_level
+    task_id = "task_id"  # see Action.task_uuid
+    task_start = "task_start"  # the start of the 1st RootContext
+    debug = "debug"  # flag for sending messages to a debug exchange
+    trace_start = "trace_start"  # the start of current RootContext
+    dispatch_start_time = "dispatch_start_time"  # start of the DispatchContext
+    dispatch_name = "dispatch_name"  # who dispatched
+    dump_time = "dump_time"  # dump time
+    event_id = "event_id"  # unique event_id per Event (useful to avoid duplicates)
+    trace_action = "trace_action"  # action name of the current trace
+    session_id = "session_id"  # found from request/previous metadata
+    user_id = "user_id"  # found from request/previous metadata
+    maybe_duplicate = "maybe_duplicate"  # e.g. when consuming the same message twice
+
+
+def iter_tags(metadata: dict) -> Iterable[tuple[str, Any]]:
+    #: a list of [(key, value)] pairs
+    yield from metadata.get(EventMetadata.tags, [])