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

decnet/asn/base.py

@@ -0,0 +1,33 @@
+"""ASN provider protocol — mirror of :mod:`decnet.geoip.base`.
+
+Concrete providers (e.g. :mod:`decnet.asn.iptoasn`) implement this.
+Callers must go through :func:`decnet.asn.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.asn.lookup import AsnLookup
+
+
+class Provider(ABC):
+    """Abstract IP→ASN data provider."""
+
+    #: Short tag written to ``Attacker.asn_source`` (e.g. ``'iptoasn'``).
+    name: str
+
+    @abstractmethod
+    def refresh(self) -> None:
+        """Download / regenerate the provider's raw data files."""
+
+    @abstractmethod
+    def build_lookup(self) -> AsnLookup:
+        """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."""