tesorotools-python 0.0.38__tar.gz → 0.0.40__tar.gz

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/PKG-INFO

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

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/pyproject.toml

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

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/src/tesorotools/__init__.py

@@ -51,7 +51,12 @@ from tesorotools.artists import (
     StackedBarPlot,
     TypeCurve,
 )
-from tesorotools.providers.base import DataProvider, DataProviderProtocol
+from tesorotools.orchestration import CompositeRegistry, iter_contexts
+from tesorotools.providers.base import (
+    DataProvider,
+    RegistryProtocol,
+    bootstrap_providers,
+)
 from tesorotools.render import (
     Content,
     Image,
@@ -91,9 +96,9 @@ __all__ = [
     "Artist",
     "BdeProvider",
     "BuildContext",
+    "CompositeRegistry",
     "Content",
     "DataProvider",
-    "DataProviderProtocol",
     "EcbProvider",
     "Format",
     "HorizontalBarChart",
@@ -101,6 +106,7 @@ __all__ = [
     "Images",
     "Legend",
     "LinePlot",
+    "RegistryProtocol",
     "Report",
     "Section",
     "StackedAreaPlot",
@@ -114,9 +120,11 @@ __all__ = [
     "all_artists",
     "all_providers",
     "all_tags",
+    "bootstrap_providers",
     "get_artist",
     "get_provider",
     "iter_artists",
+    "iter_contexts",
     "iter_providers",
     "iter_tags",
     "register_artist",

tesorotools_python-0.0.40/src/tesorotools/_build_context.py

@@ -0,0 +1,59 @@
+"""Shared context object for ``build_for`` provider factories.
+
+Each provider class has a :meth:`tesorotools.DataProvider.build_for`
+classmethod that decides whether to instantiate itself based
+on the registry and runtime context.  ``BuildContext`` is the
+shared input to that method.
+
+The base fields cover the cross-project minimum:
+
+* ``registry`` -- the catalog the orchestrator uses to decide
+  which series each provider must serve.  Typed as
+  :class:`tesorotools.providers.base.RegistryProtocol` so
+  that ``build_for`` bodies are statically checked.
+* ``consumer`` -- a free-form string identifying the calling
+  workflow (e.g. ``"diary"``, ``"weekly"``).  ``build_for``
+  implementations dispatch on it via
+  ``registry.all_cids_for_provider(ctx.consumer, ...)``.
+* ``mock`` / ``mock_seed`` -- toggle for deterministic
+  fixtures during tests and demos.
+* ``provider_config`` -- per-provider knobs keyed by
+  :attr:`tesorotools.DataProvider.PROVIDER_NAME`.  Lets each
+  provider read its own sub-config (API keys, fallback
+  policy, historical file paths, ...) without polluting the
+  shared context surface.
+
+Cross-provider settings that genuinely belong to the context
+(a project-wide cache directory, say) can still go on a
+``BuildContext`` subclass:
+
+.. code-block:: python
+
+    @dataclass(frozen=True)
+    class DiaryBuildContext(BuildContext):
+        cache_dir: Path = Path(".cache")
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from tesorotools.providers.base import RegistryProtocol
+
+
+def _empty_provider_config() -> dict[str, Mapping[str, Any]]:
+    return {}
+
+
+@dataclass(frozen=True)
+class BuildContext:
+    registry: "RegistryProtocol"
+    consumer: str
+    mock: bool = False
+    mock_seed: int | None = None
+    provider_config: Mapping[str, Mapping[str, Any]] = field(
+        default_factory=_empty_provider_config
+    )

tesorotools_python-0.0.40/src/tesorotools/orchestration.py

@@ -0,0 +1,100 @@
+"""Optional orchestration helpers for multi-consumer setups.
+
+The single-consumer flow is already short with the core
+contract (one ``BuildContext``, one
+:func:`tesorotools.providers.base.bootstrap_providers` call).
+Projects that fan out across several consumers and several
+registries end up rewriting the same wiring: pick a registry
+list, wrap it in a composite when there is more than one,
+build the context, populate ``provider_config``, call
+``bootstrap_providers``.  The two helpers below collapse that
+to a one-liner per consumer.
+
+These helpers are deliberately optional.  A project that
+ignores them is unaffected; a project building its second or
+third consumer can pull them in without rewriting any
+provider.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+from typing import Any
+
+from tesorotools._build_context import BuildContext
+from tesorotools.providers.base import RegistryProtocol
+
+
+class CompositeRegistry:
+    """Concatenate several :class:`RegistryProtocol` instances
+    as if they were one.
+
+    Iteration order over *parts* is the lookup order for
+    :meth:`get_provider_meta` (first match wins).  For
+    :meth:`all_cids_for_provider` the result is the
+    concatenation; if the same canonical ID appears in two
+    parts, both are returned -- duplicates should be resolved
+    upstream by the consumer's registry layout, not here.
+
+    The class itself satisfies :class:`RegistryProtocol`, so
+    callers cannot tell whether they are talking to one
+    registry or several.
+    """
+
+    def __init__(self, parts: list[RegistryProtocol]) -> None:
+        self._parts = parts
+
+    def all_cids_for_provider(
+        self, consumer: str, provider_name: str
+    ) -> list[str]:
+        return [
+            cid
+            for r in self._parts
+            for cid in r.all_cids_for_provider(consumer, provider_name)
+        ]
+
+    def get_provider_meta(
+        self, canonical_id: str, provider_name: str
+    ) -> dict[str, Any]:
+        for r in self._parts:
+            try:
+                return r.get_provider_meta(canonical_id, provider_name)
+            except KeyError:
+                continue
+        raise KeyError(f"unknown cid {canonical_id!r}")
+
+
+def iter_contexts(
+    consumer_registries: Mapping[str, list[RegistryProtocol]],
+    provider_config_for: Callable[
+        [str], Mapping[str, Mapping[str, Any]]
+    ] = lambda _: {},
+    *,
+    mock: bool = False,
+    mock_seed: int | None = None,
+) -> Iterator[BuildContext]:
+    """Yield one :class:`BuildContext` per consumer.
+
+    Multi-registry consumers are wrapped in
+    :class:`CompositeRegistry` transparently; single-registry
+    consumers receive their registry unchanged so that
+    ``ctx.registry is registries[0]`` holds when the consumer
+    only has one.
+
+    *provider_config_for* is called once per consumer and its
+    result is attached as :attr:`BuildContext.provider_config`.
+    The default returns an empty mapping for every consumer.
+    """
+    for consumer, registries in consumer_registries.items():
+        registry: RegistryProtocol = (
+            registries[0]
+            if len(registries) == 1
+            else CompositeRegistry(registries)
+        )
+        yield BuildContext(
+            registry=registry,
+            consumer=consumer,
+            mock=mock,
+            mock_seed=mock_seed,
+            provider_config=provider_config_for(consumer),
+        )

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/src/tesorotools/providers/__init__.py

@@ -9,7 +9,11 @@ extras.
 
 from typing import TYPE_CHECKING, Any
 
-from tesorotools.providers.base import DataProvider, DataProviderProtocol
+from tesorotools.providers.base import (
+    DataProvider,
+    RegistryProtocol,
+    bootstrap_providers,
+)
 
 if TYPE_CHECKING:
     from tesorotools.providers.bde import BdeProvider
@@ -18,8 +22,9 @@ if TYPE_CHECKING:
 __all__ = [
     "BdeProvider",
     "DataProvider",
-    "DataProviderProtocol",
     "EcbProvider",
+    "RegistryProtocol",
+    "bootstrap_providers",
 ]
 
 

tesorotools_python-0.0.40/src/tesorotools/providers/base.py

@@ -0,0 +1,213 @@
+"""Abstract base class for data providers and the contract
+glue around it.
+
+A provider knows how to download time series from a specific
+external source (Bank of Spain, Eikon, ECB, etc.).  It does
+not know anything about local storage, incremental updates,
+or presentation -- those concerns belong elsewhere.
+
+Every provider returns data in the same shape: a DataFrame
+with a DatetimeIndex and one column per series code.
+
+In addition to ``fetch`` and ``is_available``, this module
+formalises the construction contract that consumer projects
+were already converging on informally:
+
+* :attr:`DataProvider.PROVIDER_NAME` -- the stable identifier
+  every consumer ends up adding to its provider classes.
+  Required at definition time; ``__init_subclass__`` raises
+  ``TypeError`` if a concrete subclass forgets it.
+* :class:`RegistryProtocol` -- the two methods consumers
+  uniformly call on whatever catalog they pass through
+  ``BuildContext.registry``.  Formalising them lets
+  ``build_for`` be statically typed.
+* :meth:`DataProvider.build_for` -- a default factory that
+  covers the simple "no constructor args, single instance"
+  case and skips construction when the registry has no
+  canonical IDs for this provider in the current consumer.
+  Providers that need configuration, multiple instances, or
+  fallback logic override it.
+* :func:`bootstrap_providers` -- the trivial loop every
+  consumer ends up writing on top of ``build_for``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, ClassVar, Protocol
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from tesorotools._build_context import BuildContext
+
+
+class RegistryProtocol(Protocol):
+    """Structural type for whatever catalog a project passes
+    through :attr:`BuildContext.registry`.
+
+    Only the two methods :meth:`DataProvider.build_for` reads
+    are formalised.  Projects with idiosyncratic registries
+    (composite layouts, different storage backends) keep
+    working as long as they expose these two methods.
+    """
+
+    def all_cids_for_provider(
+        self, consumer: str, provider_name: str
+    ) -> list[str]:
+        """Return every canonical ID this provider must serve
+        for *consumer*.  Empty list means "this provider is
+        not needed for this consumer"."""
+        ...
+
+    def get_provider_meta(
+        self, canonical_id: str, provider_name: str
+    ) -> dict[str, Any]:
+        """Return the per-instrument metadata block this
+        provider expects for *canonical_id*."""
+        ...
+
+
+class DataProvider(ABC):
+    """Base class for all data providers.
+
+    Subclasses must:
+
+    * set :attr:`PROVIDER_NAME` (enforced at class-definition
+      time by :meth:`__init_subclass__`);
+    * implement :meth:`fetch` and :meth:`is_available`
+      (enforced at instantiation time by ``ABC``).
+
+    They MAY override :meth:`build_for` to customise
+    construction (multiple instances, constructor arguments,
+    fallback logic).
+    """
+
+    #: Stable, lowercase identifier under which this provider
+    #: registers in the global ``register_provider`` index.
+    #: Concrete subclasses MUST set it; abstract intermediates
+    #: may leave it unset.
+    PROVIDER_NAME: ClassVar[str]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # ``ABCMeta.__new__`` populates ``__abstractmethods__``
+        # *after* ``__init_subclass__`` runs, so we compute
+        # the set ourselves to detect intermediate ABCs that
+        # still have abstract methods.  Those will never be
+        # instantiated; forcing them to declare
+        # ``PROVIDER_NAME`` would be noise.
+        if _has_abstract_methods(cls):
+            return
+        if "PROVIDER_NAME" not in cls.__dict__ and not any(
+            "PROVIDER_NAME" in base.__dict__ for base in cls.__mro__[1:-1]
+        ):
+            raise TypeError(
+                f"{cls.__name__} must define a class-level "
+                "``PROVIDER_NAME: ClassVar[str]`` "
+                "(required by tesorotools.DataProvider)."
+            )
+
+    @abstractmethod
+    def fetch(
+        self,
+        codes: list[str],
+        start: str | None = None,
+        end: str | None = None,
+    ) -> pd.DataFrame:
+        """Download series data for a date range.
+
+        Parameters
+        ----------
+        codes
+            Provider-specific series codes to download.
+        start
+            Start date as ISO string (e.g. ``"2025-01-01"``).
+            If ``None``, the provider decides the earliest
+            date (typically the full available history).
+        end
+            End date as ISO string.  If ``None``, the
+            provider fetches up to the latest available data.
+
+        Returns
+        -------
+        pd.DataFrame
+            - Index: ``DatetimeIndex`` named ``"date"``,
+              tz-naive, normalized to midnight.
+            - Columns: one per code in ``codes``.
+            - Values: ``float64``, with ``NaN`` for missing
+              observations.
+        """
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check whether this provider can serve data.
+
+        Returns ``True`` if the external service is reachable
+        and ready.  Useful for fail-fast checks before
+        starting a long download, or for choosing between
+        a primary provider and a fallback.
+        """
+        ...
+
+    @classmethod
+    def build_for(cls, ctx: "BuildContext") -> dict[str, "DataProvider"]:
+        """Default factory used by :func:`bootstrap_providers`.
+
+        Skips construction entirely if no canonical ID asks
+        for this provider in *ctx.consumer*; otherwise
+        instantiates with no arguments and registers under
+        :attr:`PROVIDER_NAME`.
+
+        Override when the provider needs constructor
+        arguments, returns multiple instances, or has
+        fallback logic.  Calling ``cls()`` on a class with
+        required ``__init__`` arguments raises ``TypeError``;
+        that is intentional -- a provider that needs
+        configuration is forced to override this method.
+        """
+        if not ctx.registry.all_cids_for_provider(
+            ctx.consumer, cls.PROVIDER_NAME
+        ):
+            return {}
+        return {cls.PROVIDER_NAME: cls()}
+
+
+def _has_abstract_methods(cls: type) -> bool:
+    """Return True if *cls* still has abstract methods.
+
+    ``ABCMeta`` populates ``__abstractmethods__`` after
+    ``__init_subclass__`` runs, so we compute the abstract
+    set manually by walking the MRO bottom-up.  An abstract
+    method introduced higher in the MRO is "discharged" when
+    a lower class overrides it with a concrete implementation.
+    """
+    abstracts: set[str] = set()
+    for base in reversed(cls.__mro__):
+        for name, value in vars(base).items():
+            if getattr(value, "__isabstractmethod__", False):
+                abstracts.add(name)
+            elif name in abstracts:
+                abstracts.discard(name)
+    return bool(abstracts)
+
+
+def bootstrap_providers(
+    ctx: "BuildContext",
+    classes: Iterable[type[DataProvider]],
+) -> dict[str, DataProvider]:
+    """Run :meth:`DataProvider.build_for` over *classes* and
+    merge the results.
+
+    Iteration order over *classes* is preserved for log
+    readability; behaviour does not depend on it.  When two
+    classes return the same key, the later one wins, matching
+    plain ``dict.update`` semantics; that is the consumer's
+    problem to avoid.
+    """
+    out: dict[str, DataProvider] = {}
+    for cls in classes:
+        out.update(cls.build_for(ctx))
+    return out

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/src/tesorotools/providers/bde.py

@@ -30,7 +30,7 @@ Notes
 from __future__ import annotations
 
 import logging
-from typing import TypedDict, cast
+from typing import ClassVar, TypedDict, cast
 
 import pandas as pd
 import requests
@@ -72,6 +72,8 @@ class BdeProvider(DataProvider):
         Maximum seconds to wait per HTTP request.
     """
 
+    PROVIDER_NAME: ClassVar[str] = "bde"
+
     def __init__(
         self,
         *,

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/src/tesorotools/providers/ecb.py

@@ -36,7 +36,7 @@ from __future__ import annotations
 import csv
 import io
 import logging
-from typing import cast
+from typing import ClassVar, cast
 
 import pandas as pd
 import requests
@@ -106,6 +106,8 @@ class EcbProvider(DataProvider):
         tests or for custom retry policies.
     """
 
+    PROVIDER_NAME: ClassVar[str] = "ecb"
+
     def __init__(
         self,
         *,

{tesorotools_python-0.0.38 → tesorotools_python-0.0.40}/src/tesorotools/render/content/table.py

@@ -15,6 +15,7 @@ from docx.oxml.ns import nsdecls, qn
 from docx.shared import Inches, Pt, RGBColor
 from docx.table import Table as TableDocx
 from docx.table import _Cell as TableCell
+from docx.table import _Row as TableRow
 from yaml import MappingNode
 
 from tesorotools.utils.config import read_config
@@ -49,46 +50,6 @@ TEXTO_TABLAS: int = 9
 CENTER = WD_ALIGN_PARAGRAPH.CENTER
 
 
-def _set_cell_border(cell: TableCell, **kwargs: Any) -> None:
-    """
-    Set cell`s border
-    Usage:
-
-    set_cell_border(
-        cell,
-        top={"sz": 12, "val": "single", "color": "#FF0000", "space": "0"},
-        bottom={"sz": 12, "color": "#00FF00", "val": "single"},
-        start={"sz": 24, "val": "dashed", "shadow": "true"},
-        end={"sz": 12, "val": "dashed"},
-    )
-    """
-    tc = cell._tc
-    tcPr = tc.get_or_add_tcPr()
-
-    # check for tag existence, if none found, create one
-    tcBorders: Any = tcPr.first_child_found_in("w:tcBorders")  # type: ignore[reportUnknownMemberType]
-    if tcBorders is None:
-        tcBorders = OxmlElement("w:tcBorders")  # type: ignore[reportUnknownVariableType]
-        tcPr.append(tcBorders)  # type: ignore[reportUnknownMemberType]
-
-    # list over all available tags
-    for edge in ("start", "top", "end", "bottom", "insideH", "insideV"):
-        edge_data: Any = kwargs.get(edge)
-        if edge_data:
-            tag = "w:{}".format(edge)
-
-            # check for tag existence, if none found, then create one
-            element: Any = tcBorders.find(qn(tag))  # type: ignore[reportUnknownMemberType]
-            if element is None:
-                element = OxmlElement(tag)  # type: ignore[reportUnknownVariableType]
-                tcBorders.append(element)  # type: ignore[reportUnknownMemberType]
-
-            # looks like order of attributes is important
-            for key in ["sz", "val", "color", "space", "shadow"]:
-                if key in edge_data:
-                    element.set(qn("w:{}".format(key)), str(edge_data[key]))  # type: ignore[reportUnknownMemberType]
-
-
 def _style_horizontal_blocks_header(cell: TableCell) -> None:
     cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER
     cell.paragraphs[0].runs[0].font.size = Pt(12)
@@ -192,25 +153,47 @@ def _separate_blocks(
             "got a flat Index. Set block_sep=False or wrap rows in a "
             "MultiIndex with the block name as level 0."
         )
+    _disable_implicit_last_row(table_docx)
     blocks: list[str] = list(index.get_level_values(level=0).unique())
     previous_rows: int = 0
     for block in blocks[:-1]:
         block_size: int = len(index[index.get_level_values(level=0) == block])
-        for cell in table_docx.rows[block_size + previous_rows].cells:
-            _separate_cell(cell)
+        _separate_row(table_docx.rows[block_size + previous_rows])
         previous_rows += block_size
 
 
-def _separate_cell(cell: TableCell) -> None:
-    _set_cell_border(
-        cell,
-        bottom={
-            "sz": 1,
-            "val": "double",
-            "color": "#000000",
-            "space": 2,
-        },
-    )
+def _separate_row(row: TableRow) -> None:
+    """Mark *row* as ``lastRow`` via conditional-formatting reference.
+
+    The visible separator border belongs to the active table style
+    (``<w:tblStylePr w:type="lastRow">`` in ``styles.xml``). Emitting
+    only ``<w:cnfStyle>`` on ``<w:trPr>`` keeps direct formatting out of
+    ``<w:tcPr>``, which is the construct Word's co-authoring merge
+    engine corrupts in shared OneDrive/SharePoint documents. The
+    consumer's ``template.docx`` must define the ``lastRow`` conditional
+    formatting on the table style referenced by ``plots.yaml``.
+    """
+    trPr: Any = row._tr.get_or_add_trPr()  # type: ignore[reportUnknownMemberType]
+    cnfStyle: Any = OxmlElement("w:cnfStyle")  # type: ignore[reportUnknownVariableType]
+    # 12-bit mask, ECMA-376 §17.4.7. Bit 1 (zero-indexed) = lastRow.
+    cnfStyle.set(qn("w:val"), "010000000000")  # type: ignore[reportUnknownMemberType]
+    trPr.append(cnfStyle)  # type: ignore[reportUnknownMemberType]
+
+
+def _disable_implicit_last_row(table_docx: TableDocx) -> None:
+    """Force ``<w:tblLook w:lastRow="0"/>`` so the real last row stays plain.
+
+    With block_sep we mark *interior* rows as ``lastRow`` via
+    ``cnfStyle``. The table's own last row must not pick up the same
+    conditional formatting automatically, so we disable the implicit
+    ``lastRow`` flag at the ``<w:tblLook>`` level.
+    """
+    tblPr: Any = table_docx._element.tblPr  # type: ignore[reportUnknownMemberType]
+    tblLook: Any = tblPr.find(qn("w:tblLook"))  # type: ignore[reportUnknownMemberType]
+    if tblLook is None:
+        tblLook = OxmlElement("w:tblLook")  # type: ignore[reportUnknownVariableType]
+        tblPr.append(tblLook)  # type: ignore[reportUnknownMemberType]
+    tblLook.set(qn("w:lastRow"), "0")  # type: ignore[reportUnknownMemberType]
 
 
 def _is_bright(hex_color: str) -> bool:

tesorotools_python-0.0.38/src/tesorotools/_build_context.py

@@ -1,49 +0,0 @@
-"""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.38/src/tesorotools/providers/base.py

@@ -1,114 +0,0 @@
-"""Abstract base class for data providers.
-
-A provider knows how to download time series from a specific
-external source (Bank of Spain, Eikon, ECB, etc.).  It does
-not know anything about local storage, incremental updates,
-or presentation -- those concerns belong elsewhere.
-
-The interface is intentionally minimal: ``fetch`` to download
-data and ``is_available`` to check connectivity.  Any
-provider-specific configuration (API keys, rate limits, etc.)
-belongs in the concrete class constructor, not in the
-abstract interface.
-
-Every provider returns data in the same shape: a DataFrame
-with a DatetimeIndex and one column per series code.
-
-This module exposes both ``DataProvider`` (an ``ABC`` --
-recommended base class because it enforces ``fetch`` and
-``is_available`` at instantiation time) and
-``DataProviderProtocol`` (a ``runtime_checkable`` Protocol
-mirroring the same surface).  The Protocol exists for
-callers that need to compose Protocols, e.g.
-
-.. code-block:: python
-
-    class DiaryProvider(DataProviderProtocol, Protocol):
-        PROVIDER_NAME: ClassVar[str]
-        @classmethod
-        def build_for(cls, ctx: BuildContext) -> dict[str, ...]: ...
-
-without dragging in the ABC's runtime enforcement.
-"""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Protocol, runtime_checkable
-
-import pandas as pd
-
-
-class DataProvider(ABC):
-    """Base class for all data providers.
-
-    Subclasses must implement ``fetch`` and ``is_available``.
-    """
-
-    @abstractmethod
-    def fetch(
-        self,
-        codes: list[str],
-        start: str | None = None,
-        end: str | None = None,
-    ) -> pd.DataFrame:
-        """Download series data for a date range.
-
-        Parameters
-        ----------
-        codes
-            Provider-specific series codes to download.
-        start
-            Start date as ISO string (e.g. ``"2025-01-01"``).
-            If ``None``, the provider decides the earliest
-            date (typically the full available history).
-        end
-            End date as ISO string.  If ``None``, the
-            provider fetches up to the latest available data.
-
-        Returns
-        -------
-        pd.DataFrame
-            - Index: ``DatetimeIndex`` named ``"date"``,
-              tz-naive, normalized to midnight.
-            - Columns: one per code in ``codes``.
-            - Values: ``float64``, with ``NaN`` for missing
-              observations.
-        """
-        ...
-
-    @abstractmethod
-    def is_available(self) -> bool:
-        """Check whether this provider can serve data.
-
-        Returns ``True`` if the external service is reachable
-        and ready.  Useful for fail-fast checks before
-        starting a long download, or for choosing between
-        a primary provider and a fallback.
-        """
-        ...
-
-
-@runtime_checkable
-class DataProviderProtocol(Protocol):
-    """Structural counterpart of :class:`DataProvider`.
-
-    Anything with ``fetch(codes, start=None, end=None)`` and
-    ``is_available()`` satisfies this Protocol.  Subclassing
-    is unnecessary; useful when callers need to compose
-    Protocols (``class DiaryProvider(DataProviderProtocol,
-    Protocol): ...``) without inheriting an ABC.
-
-    Prefer subclassing :class:`DataProvider` for new concrete
-    providers: the ABC enforces the contract at
-    instantiation time, the Protocol does not.
-    """
-
-    def fetch(
-        self,
-        codes: list[str],
-        start: str | None = None,
-        end: str | None = None,
-    ) -> pd.DataFrame: ...
-
-    def is_available(self) -> bool: ...