edapitool 0.6.3__py3-none-any.whl

APITool/catalog.py

@@ -0,0 +1,274 @@
+"""
+Canonical commodity identity: FDev id <-> symbol <-> display name.
+
+Why this exists
+---------------
+Elite Dangerous names the same commodity three different ways, and the three
+do not agree. Measured against a live station market, 97 of 366 symbols do not
+normalize to their display name:
+
+    id 128049232  symbol TerrainEnrichmentSystems  display "Land Enrichment Systems"
+    id 128049208  symbol AgriculturalMedicines     display "Agri-Medicines"
+    id 128049220  symbol HeliostaticFurnaces       display "Microbial Furnaces"
+
+The spreadsheet speaks display names. The journal (Market.json) emits all three.
+The Frontier CAPI emits id + symbol + locName. So matching a spreadsheet row to
+a market entry needs a table, not string munging.
+
+The second reason matters more than the first: without a catalog, "this name is
+not in the market response" is ambiguous between *the station does not sell it*
+and *we do not recognize the name*. A station listing 366 items hides that
+ambiguity; a small outpost listing 30 does not.
+
+The table is bundled (see APITool/data/fdev_commodities.csv) and regenerated by
+scripts/update-commodity-catalog.py. Runtime never touches the network -- a
+GitHub outage must not break a docking.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import re
+from dataclasses import dataclass
+from functools import lru_cache
+from pathlib import Path
+from typing import Iterable, Mapping, Optional
+
+DEFAULT_CATALOG_PATH = Path(__file__).parent / "data" / "fdev_commodities.csv"
+DEFAULT_ALIASES_PATH = Path(__file__).parent / "data" / "name_aliases.json"
+
+
+def normalize(text: object) -> str:
+    """
+    Fold a commodity name to a comparison key.
+
+    Lowercases and drops everything that is not a letter or digit, so
+    "Micro-weave Cooling Hoses", "microweave cooling hoses" and
+    "MicroWeaveCoolingHoses" all collapse together. Deliberately aggressive:
+    it is only ever used to look up a canonical entry, never to decide that
+    two things are different.
+    """
+    return re.sub(r"[^a-z0-9]", "", str(text).lower())
+
+
+def strip_symbol(raw: object) -> str:
+    """
+    Reduce a journal-style symbol token to its bare symbol.
+
+    The journal writes symbols as game localization keys:
+        "$terrainenrichmentsystems_name;" -> "terrainenrichmentsystems"
+    CAPI writes them bare already:
+        "TerrainEnrichmentSystems"       -> "TerrainEnrichmentSystems"
+    """
+    text = str(raw).strip()
+    if text.startswith("$"):
+        text = text[1:]
+    text = text.rstrip(";")
+    if text.lower().endswith("_name"):
+        text = text[: -len("_name")]
+    return text
+
+
+@dataclass(frozen=True)
+class Commodity:
+    """One canonical commodity."""
+
+    id: int
+    symbol: str
+    category: str
+    name: str
+    rare: bool = False
+
+    @property
+    def key(self) -> str:
+        """Stable comparison key for this commodity's display name."""
+        return normalize(self.name)
+
+
+class CommodityCatalog:
+    """
+    Three-way index over the bundled FDev commodity table.
+
+    Lookup precedence in :meth:`resolve` is id -> symbol -> display name.
+    That order is not arbitrary: ids never collide, symbols are stable across
+    game updates, and display names are the only one of the three that
+    Frontier has historically rewritten.
+    """
+
+    def __init__(self, commodities: Iterable[Commodity]):
+        self._by_id: dict[int, Commodity] = {}
+        self._by_symbol: dict[str, Commodity] = {}
+        self._by_name: dict[str, Commodity] = {}
+
+        for item in commodities:
+            self._by_id[item.id] = item
+            self._by_symbol.setdefault(normalize(item.symbol), item)
+            self._by_name.setdefault(item.key, item)
+
+    def __len__(self) -> int:
+        return len(self._by_id)
+
+    def __iter__(self):
+        return iter(self._by_id.values())
+
+    def add_alias(self, alias: object, commodity: Commodity) -> bool:
+        """
+        Register an extra display name for a commodity.
+
+        Returns True if the alias was newly registered. An alias never
+        displaces an existing canonical name -- first registration wins, so a
+        user file cannot accidentally shadow a real commodity.
+
+        This exists because EDCD's table and the game's own localised output
+        do not always agree. Measured against a live market: EDCD says
+        "Low Temperature Diamonds", the game says "Low Temp. Diamonds". A
+        commander copying the game's spelling into their spreadsheet would
+        otherwise be unmatchable.
+        """
+        key = normalize(alias)
+        if not key or key in self._by_name:
+            return False
+        self._by_name[key] = commodity
+        return True
+
+    def learn_from_market(self, items: Iterable[Mapping]) -> int:
+        """
+        Register localised names observed in a real market response.
+
+        Lets display-name drift self-heal within a session: whatever the game
+        called a commodity becomes a lookup key for it. Accepts both journal
+        (``id`` / ``Name_Localised``) and CAPI (``id`` / ``locName``) shapes.
+        Returns the number of new aliases learned.
+        """
+        learned = 0
+        for item in items:
+            found = self.by_id(item.get("id"))
+            if found is None:
+                continue
+            for field in ("Name_Localised", "locName"):
+                value = item.get(field)
+                if value and self.add_alias(value, found):
+                    learned += 1
+        return learned
+
+    def load_aliases(self, path: Path) -> int:
+        """
+        Load a user-editable alias map: ``{"Some Name": <id | symbol | name>}``.
+
+        Unresolvable entries are skipped rather than raising -- a typo in a
+        hand-edited file must not stop the tool from docking.
+        """
+        if not path.exists():
+            return 0
+        try:
+            raw = json.loads(path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return 0
+        if not isinstance(raw, dict):
+            return 0
+
+        learned = 0
+        for alias, target in raw.items():
+            # Underscore-prefixed keys are documentation, not aliases.
+            if isinstance(alias, str) and alias.startswith("_"):
+                continue
+            if isinstance(target, bool):
+                continue
+            if isinstance(target, int):
+                found = self.by_id(target)
+            else:
+                found = self.resolve(symbol=target, name=target)
+            if found is not None and self.add_alias(alias, found):
+                learned += 1
+        return learned
+
+    @classmethod
+    def load(
+        cls,
+        path: Optional[Path] = None,
+        aliases_path: Optional[Path] = None,
+    ) -> "CommodityCatalog":
+        """Load the catalog from a CSV. Defaults to the bundled table."""
+        source = Path(path) if path else DEFAULT_CATALOG_PATH
+        if not source.exists():
+            raise FileNotFoundError(
+                f"Commodity catalog not found at {source}. "
+                "Regenerate it with: python scripts/update-commodity-catalog.py"
+            )
+
+        rows = []
+        with open(source, encoding="utf-8", newline="") as handle:
+            for row in csv.DictReader(handle):
+                try:
+                    rows.append(
+                        Commodity(
+                            id=int(row["id"]),
+                            symbol=(row.get("symbol") or "").strip(),
+                            category=(row.get("category") or "").strip(),
+                            name=(row.get("name") or "").strip(),
+                            rare=str(row.get("rare", "0")).strip() in ("1", "true", "True"),
+                        )
+                    )
+                except (KeyError, ValueError, TypeError):
+                    # A malformed row must not take down a docking. Skip it.
+                    continue
+
+        if not rows:
+            raise ValueError(f"Commodity catalog at {source} contained no usable rows")
+
+        catalog = cls(rows)
+        alias_source = Path(aliases_path) if aliases_path else DEFAULT_ALIASES_PATH
+        catalog.load_aliases(alias_source)
+        return catalog
+
+    def by_id(self, commodity_id: object) -> Optional[Commodity]:
+        try:
+            return self._by_id.get(int(commodity_id))
+        except (TypeError, ValueError):
+            return None
+
+    def by_symbol(self, symbol: object) -> Optional[Commodity]:
+        if symbol in (None, ""):
+            return None
+        return self._by_symbol.get(normalize(strip_symbol(symbol)))
+
+    def by_name(self, name: object) -> Optional[Commodity]:
+        if name in (None, ""):
+            return None
+        return self._by_name.get(normalize(name))
+
+    def resolve(
+        self,
+        commodity_id: object = None,
+        symbol: object = None,
+        name: object = None,
+    ) -> Optional[Commodity]:
+        """
+        Resolve a commodity from whichever identifiers are available.
+
+        Tries id, then symbol, then display name, and returns the first hit.
+        Returns None when nothing matches -- callers must treat that as
+        "unknown name", never as "the station does not sell it".
+        """
+        for lookup, value in (
+            (self.by_id, commodity_id),
+            (self.by_symbol, symbol),
+            (self.by_name, name),
+        ):
+            if value in (None, ""):
+                continue
+            found = lookup(value)
+            if found is not None:
+                return found
+        return None
+
+
+@lru_cache(maxsize=4)
+def _cached_catalog(path: Optional[str]) -> CommodityCatalog:
+    return CommodityCatalog.load(Path(path) if path else None)
+
+
+def load_catalog(path: Optional[Path] = None) -> CommodityCatalog:
+    """Load (and memoize) the commodity catalog."""
+    return _cached_catalog(str(path) if path else None)