tesorotools-python 0.0.36__tar.gz → 0.0.37__tar.gz

{tesorotools_python-0.0.36 → tesorotools_python-0.0.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesorotools-python
-Version: 0.0.36
+Version: 0.0.37
 Requires-Python: >=3.13
 Requires-Dist: babel>=2.17
 Requires-Dist: matplotlib>=3.10

{tesorotools_python-0.0.36 → tesorotools_python-0.0.37}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "tesorotools-python"
 requires-python = ">=3.13"
-version = "0.0.36"
+version = "0.0.37"
 dependencies = [
     # database and ORM
     "psycopg[binary]>=3.1",

{tesorotools_python-0.0.36 → tesorotools_python-0.0.37}/src/tesorotools/__init__.py

@@ -12,7 +12,9 @@ requires ``[ecb]``) are exposed lazily through
 extras to be installed.
 
 Third parties extend the package via ``register_artist``,
-``register_tag``, and ``register_provider``.
+``register_tag``, and ``register_provider`` (and their
+plural variants).  See ``docs/extending.md`` for the
+recommended idioms.
 """
 
 from typing import TYPE_CHECKING, Any
@@ -21,13 +23,24 @@ if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
     from tesorotools.providers.ecb import EcbProvider
 
+from tesorotools._build_context import BuildContext
 from tesorotools._registry import (
     Artist,
+    YamlConstructor,
+    all_artists,
+    all_providers,
+    all_tags,
     get_artist,
     get_provider,
+    iter_artists,
+    iter_providers,
+    iter_tags,
     register_artist,
+    register_artists,
     register_provider,
+    register_providers,
     register_tag,
+    register_tags,
 )
 from tesorotools.artists import (
     Format,
@@ -38,7 +51,7 @@ from tesorotools.artists import (
     StackedBarPlot,
     TypeCurve,
 )
-from tesorotools.providers.base import DataProvider
+from tesorotools.providers.base import DataProvider, DataProviderProtocol
 from tesorotools.render import (
     Content,
     Image,
@@ -77,8 +90,10 @@ _register_builtins()
 __all__ = [
     "Artist",
     "BdeProvider",
+    "BuildContext",
     "Content",
     "DataProvider",
+    "DataProviderProtocol",
     "EcbProvider",
     "Format",
     "HorizontalBarChart",
@@ -95,11 +110,21 @@ __all__ = [
     "Text",
     "Title",
     "TypeCurve",
+    "YamlConstructor",
+    "all_artists",
+    "all_providers",
+    "all_tags",
     "get_artist",
     "get_provider",
+    "iter_artists",
+    "iter_providers",
+    "iter_tags",
     "register_artist",
+    "register_artists",
     "register_provider",
+    "register_providers",
     "register_tag",
+    "register_tags",
 ]
 
 

tesorotools_python-0.0.37/src/tesorotools/_build_context.py

@@ -0,0 +1,49 @@
+"""Shared context object for ``build_for`` provider/artist factories.
+
+Consumer projects increasingly converge on a pattern where
+each provider/artist class has a ``build_for(cls, ctx) ->
+dict[str, ...]`` classmethod that decides whether to
+instantiate itself based on the catalog and runtime context.
+
+``BuildContext`` is the minimal shape we expect callers to
+share across that pattern.  It deliberately stays small so
+projects can subclass or compose freely:
+
+.. code-block:: python
+
+    @dataclass(frozen=True)
+    class DiaryBuildContext(BuildContext):
+        lseg_fallback: Literal["mock", "raise"] = "mock"
+
+The base fields capture the cross-project minimum:
+
+* ``registry`` -- whatever catalog the orchestrator uses to
+  decide which series each provider must serve.  Typed as
+  ``Any`` because each project's catalog has a different
+  shape.
+* ``consumer`` -- a free-form string identifying the calling
+  workflow (e.g. ``"diary"``, ``"weekly"``).  ``build_for``
+  implementations dispatch on this.
+* ``mock`` / ``mock_seed`` -- toggle for deterministic
+  fixtures during tests and demos.
+* ``historic_file`` -- optional path to a historical dump
+  used by some providers as a fallback.
+
+See ``docs/extending.md`` for the recommended ``build_for``
+classmethod shape.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class BuildContext:
+    registry: Any
+    consumer: str
+    mock: bool = False
+    mock_seed: int | None = None
+    historic_file: Path | None = None

tesorotools_python-0.0.37/src/tesorotools/_registry.py

@@ -0,0 +1,238 @@
+"""Registries for artists, providers, and YAML tags.
+
+Single source of truth for "name -> class" lookups used both
+by the YAML loader (``TemplateLoader``) and by code that
+dispatches by string name.
+
+Singular registration entry points:
+
+``register_artist(name, cls, *, with_tag=True)``
+    Adds ``cls`` to the artist registry and, when
+    ``with_tag`` is true (the default), binds the YAML tag
+    ``!{name}`` to ``cls.from_yaml``.  Pass
+    ``with_tag=False`` to register an artist that is
+    dispatched only programmatically (no YAML tag, no
+    ``from_yaml`` requirement).
+
+``register_tag(name, constructor)``
+    Registers a YAML tag ``!{name}`` only.  Use for things
+    that exist as YAML constructors but are not artists or
+    providers (Format, Legend, Title, Subtitle, Section,
+    Image, Text, Table, Report).
+
+``register_provider(name, cls)``
+    Adds ``cls`` to the provider registry.  Programmatic
+    only -- providers do not appear in YAML today.
+
+Plural variants (``register_artists`` / ``register_tags`` /
+``register_providers``) accept a ``Mapping[str, type]`` and
+iterate, saving boilerplate when a project registers several
+items at once.
+
+Look up registered classes via ``get_artist`` /
+``get_provider``; both raise ``KeyError`` listing the
+available names.  Iterate the live state via
+``iter_artists`` / ``iter_providers`` / ``iter_tags`` (and
+the eager ``all_*`` snapshots) so callers do not need to
+import the private dictionaries.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Any, Callable, Literal, Protocol, Self, cast, overload
+
+from yaml.nodes import MappingNode
+
+from tesorotools.artists._common import Artist
+from tesorotools.providers.base import DataProvider
+from tesorotools.utils.template import TemplateLoader
+
+# Re-export so ``from tesorotools._registry import Artist`` keeps working
+# (and the runtime-checkable Protocol is the single source of truth in
+# :mod:`tesorotools.artists._common`).
+__all__ = ["Artist"]
+
+
+class _YamlConstructable(Protocol):
+    """Loose Protocol for any class plugged in as a YAML tag.
+
+    ``register_tag`` and ``register_artist(with_tag=True)``
+    both end up calling ``cls.from_yaml`` on the registered
+    type; that is the only structural requirement.  The
+    artist-grade Protocol (with ``plot()`` and ``out_path``)
+    lives in :mod:`tesorotools.artists._common`.
+    """
+
+    @classmethod
+    def from_yaml(cls, loader: Any, node: MappingNode) -> Self: ...
+
+
+YamlConstructor = Callable[[Any, MappingNode], Any]
+
+
+_ARTIST_REGISTRY: dict[str, type[Artist]] = {}
+_PROVIDER_REGISTRY: dict[str, type[DataProvider]] = {}
+
+
+# ----------------------------------------------------------------------
+# Singular registration
+# ----------------------------------------------------------------------
+
+
+@overload
+def register_artist(name: str, cls: type[Artist]) -> None: ...
+@overload
+def register_artist(
+    name: str, cls: type[Artist], *, with_tag: Literal[True]
+) -> None: ...
+@overload
+def register_artist(
+    name: str, cls: type, *, with_tag: Literal[False]
+) -> None: ...
+def register_artist(name: str, cls: type, *, with_tag: bool = True) -> None:
+    """Register ``cls`` as the artist for ``name``.
+
+    Adds ``cls`` to the artist registry.  When ``with_tag``
+    is true (the default), also binds the YAML tag
+    ``!{name}`` to ``cls.from_yaml``.  Re-registering the
+    same name overrides both bindings.
+
+    Pass ``with_tag=False`` to skip the YAML side; in that
+    case ``cls`` is not required to expose ``from_yaml``.
+    """
+    _ARTIST_REGISTRY[name] = cast(type[Artist], cls)
+    if with_tag:
+        TemplateLoader.add_constructor(
+            f"!{name}",
+            cast(YamlConstructor, cast(type[Artist], cls).from_yaml),
+        )
+
+
+def get_artist(name: str) -> type[Artist]:
+    try:
+        return _ARTIST_REGISTRY[name]
+    except KeyError:
+        available = sorted(_ARTIST_REGISTRY)
+        raise KeyError(
+            f"No artist registered as {name!r}. Available: {available}"
+        ) from None
+
+
+def register_provider(name: str, cls: type[DataProvider]) -> None:
+    """Register ``cls`` as the provider for ``name``."""
+    _PROVIDER_REGISTRY[name] = cls
+
+
+def get_provider(name: str) -> type[DataProvider]:
+    try:
+        return _PROVIDER_REGISTRY[name]
+    except KeyError:
+        available = sorted(_PROVIDER_REGISTRY)
+        raise KeyError(
+            f"No provider registered as {name!r}. Available: {available}"
+        ) from None
+
+
+def register_tag(
+    name: str,
+    constructor: type[_YamlConstructable] | YamlConstructor,
+) -> None:
+    """Register a YAML tag ``!{name}``.
+
+    Accepts either a class with a ``from_yaml`` classmethod
+    or a bare callable matching the loader signature.  Use
+    ``register_artist`` / ``register_provider`` instead when
+    the registered name should also be looked up by code
+    via ``get_artist`` / ``get_provider``.
+    """
+    if isinstance(constructor, type):
+        cls = cast(type[_YamlConstructable], constructor)
+        TemplateLoader.add_constructor(
+            f"!{name}", cast(YamlConstructor, cls.from_yaml)
+        )
+    else:
+        TemplateLoader.add_constructor(f"!{name}", constructor)
+
+
+# ----------------------------------------------------------------------
+# Plural registration helpers
+# ----------------------------------------------------------------------
+
+
+@overload
+def register_artists(items: Mapping[str, type[Artist]]) -> None: ...
+@overload
+def register_artists(
+    items: Mapping[str, type[Artist]], *, with_tag: Literal[True]
+) -> None: ...
+@overload
+def register_artists(
+    items: Mapping[str, type], *, with_tag: Literal[False]
+) -> None: ...
+def register_artists(
+    items: Mapping[str, type], *, with_tag: bool = True
+) -> None:
+    """Register every (name, cls) entry as an artist.
+
+    Equivalent to looping over ``items.items()`` and calling
+    :func:`register_artist`.  ``with_tag`` is forwarded to
+    every call; pass ``with_tag=False`` to register classes
+    that do not expose ``from_yaml``.
+    """
+    for name, cls in items.items():
+        if with_tag:
+            register_artist(name, cast(type[Artist], cls))
+        else:
+            register_artist(name, cls, with_tag=False)
+
+
+def register_providers(items: Mapping[str, type[DataProvider]]) -> None:
+    """Register every (name, cls) entry as a provider."""
+    for name, cls in items.items():
+        register_provider(name, cls)
+
+
+def register_tags(
+    items: Mapping[str, type[Artist] | YamlConstructor],
+) -> None:
+    """Register every (name, constructor) entry as a YAML tag."""
+    for name, constructor in items.items():
+        register_tag(name, constructor)
+
+
+# ----------------------------------------------------------------------
+# Read-only views over the registries
+# ----------------------------------------------------------------------
+
+
+def iter_artists() -> Iterator[tuple[str, type[Artist]]]:
+    """Yield (name, cls) pairs for every registered artist."""
+    return iter(_ARTIST_REGISTRY.items())
+
+
+def all_artists() -> dict[str, type[Artist]]:
+    """Return a snapshot dict of every registered artist."""
+    return dict(_ARTIST_REGISTRY)
+
+
+def iter_providers() -> Iterator[tuple[str, type[DataProvider]]]:
+    """Yield (name, cls) pairs for every registered provider."""
+    return iter(_PROVIDER_REGISTRY.items())
+
+
+def all_providers() -> dict[str, type[DataProvider]]:
+    """Return a snapshot dict of every registered provider."""
+    return dict(_PROVIDER_REGISTRY)
+
+
+def iter_tags() -> Iterator[tuple[str, YamlConstructor]]:
+    """Yield (tag, constructor) pairs for every ``!`` YAML tag."""
+    for tag, ctor in TemplateLoader.yaml_constructors.items():
+        if isinstance(tag, str) and tag.startswith("!"):
+            yield tag, cast(YamlConstructor, ctor)
+
+
+def all_tags() -> dict[str, YamlConstructor]:
+    """Return a snapshot dict of every registered ``!`` YAML tag."""
+    return dict(iter_tags())

tesorotools_python-0.0.37/src/tesorotools/artists/__init__.py

@@ -0,0 +1,47 @@
+"""Image artists.
+
+Five chart classes, one shared helpers module, one
+matplotlib stylesheet side effect on import.
+
+Each class follows the same shape:
+
+* ``__init__(out_path, *, data | data_path, series, ...)``
+  -- kw-only configuration; ``out_path`` must be ``.png``.
+  Pass either ``data`` (DataFrame in memory) or
+  ``data_path`` (``.feather`` on disk), never both.
+* ``from_yaml(loader, node)`` -- builds the same instance
+  from a ``!{name}`` YAML tag.
+* ``plot()`` -- renders the chart and writes the PNG; some
+  classes also expose ``build()`` / ``save()`` for
+  fine-grained control.
+
+Shared layout, annotation and styling helpers (plus the
+``Format`` and ``Legend`` config holders) live in
+:mod:`tesorotools.artists._common`.
+
+Document-element artists (Word tables, sections, titles)
+live under :mod:`tesorotools.render`; this package is
+strictly image output.
+"""
+
+import matplotlib.style
+
+from tesorotools.artists._common import Artist, Format, Legend
+from tesorotools.artists.barh_plot import HorizontalBarChart
+from tesorotools.artists.line_plot import LinePlot
+from tesorotools.artists.stacked import StackedAreaPlot, StackedBarPlot
+from tesorotools.artists.type_curve import TypeCurve
+from tesorotools.utils.globals import STYLE_SHEET
+
+matplotlib.style.use(STYLE_SHEET)
+
+__all__ = [
+    "Artist",
+    "Format",
+    "HorizontalBarChart",
+    "Legend",
+    "LinePlot",
+    "StackedAreaPlot",
+    "StackedBarPlot",
+    "TypeCurve",
+]