merge: testing → main (reconcile 2-week divergence)

decnet/geoip/base.py

@@ -0,0 +1,34 @@
+"""GeoIP provider protocol.
+
+Concrete providers (:mod:`decnet.geoip.rir`, future ``dbip``, ``maxmind``)
+implement this. Callers must go through
+:func:`~decnet.geoip.factory.get_provider`; never import a concrete
+provider class directly.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Sequence
+
+from decnet.geoip.lookup import Lookup
+
+
+class Provider(ABC):
+    """Abstract GeoIP data provider."""
+
+    #: Short tag written to ``Attacker.country_source`` (e.g. ``'rir'``).
+    name: str
+
+    @abstractmethod
+    def refresh(self) -> None:
+        """Download / regenerate the provider's raw data files."""
+
+    @abstractmethod
+    def build_lookup(self) -> Lookup:
+        """Parse the on-disk data files and return a ready-to-query Lookup."""
+
+    @abstractmethod
+    def data_paths(self) -> Sequence[Path]:
+        """Return the list of files this provider manages — used for staleness
+        detection. Order is not significant."""