HTTP: prefer pip-system-certs/certifi_win32 bundle; use init-time verify in retries; add tests

SYS/result_table_api.py

@@ -0,0 +1,109 @@
+"""ResultTable API types and small helpers (breaking: no legacy compatibility).
+
+This module provides the canonical dataclasses and protocols that providers and
+renderers must use. It intentionally refuses to accept legacy dicts/strings/objs
+— adapters must produce `ResultModel` instances.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, Optional, Protocol
+
+
+@dataclass(frozen=True)
+class ResultModel:
+    """Canonical result model that providers must produce.
+
+    Fields:
+      - title: human-friendly title (required)
+      - path: optional filesystem path/URL
+      - ext: file extension (without dot), e.g. "pdf", "mp3"
+      - size_bytes: optional size in bytes
+      - media_kind: one of 'video','audio','image','doc', etc.
+      - metadata: arbitrary provider-specific metadata
+      - source: provider name string
+    """
+
+    title: str
+    path: Optional[str] = None
+    ext: Optional[str] = None
+    size_bytes: Optional[int] = None
+    media_kind: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    source: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class ColumnSpec:
+    """Specification for a column that renderers will use.
+
+    extractor: callable that accepts a ResultModel and returns the cell value.
+    format_fn: optional callable used to format the extracted value to string.
+    """
+
+    name: str
+    header: str
+    extractor: Callable[[ResultModel], Any]
+    format_fn: Optional[Callable[[Any], str]] = None
+    width: Optional[int] = None
+    sortable: bool = False
+
+
+ProviderAdapter = Callable[[Iterable[Any]], Iterable[ResultModel]]
+"""Type for provider adapters.
+
+Adapters must accept provider-specific sequence/iterable and yield
+`ResultModel` instances only. Anything else is an error (no implicit normalization).
+"""
+
+
+class Renderer(Protocol):
+    """Renderer protocol.
+
+    Implementations should accept rows and columns and return a renderable
+    or side-effect (e.g., print to terminal). Keep implementations deterministic
+    and side-effect-free when possible (return a Rich renderable object).
+    """
+
+    def render(self, rows: Iterable[ResultModel], columns: Iterable[ColumnSpec], meta: Optional[Dict[str, Any]] = None) -> Any:  # pragma: no cover - interface
+        ...
+
+
+# Small helper enforcing strict API usage
+
+def ensure_result_model(obj: Any) -> ResultModel:
+    """Ensure `obj` is a `ResultModel` instance, else raise TypeError.
+
+    This makes the API intentionally strict: providers must construct ResultModel
+    objects.
+    """
+    if isinstance(obj, ResultModel):
+        return obj
+    raise TypeError("ResultModel required; providers must yield ResultModel instances")
+
+
+# Convenience column spec generators
+
+def title_column() -> ColumnSpec:
+    return ColumnSpec("title", "Title", lambda r: r.title)
+
+
+def ext_column() -> ColumnSpec:
+    return ColumnSpec("ext", "Ext", lambda r: r.ext or "")
+
+
+# Helper to build a ColumnSpec that extracts a metadata key from ResultModel
+def metadata_column(key: str, header: Optional[str] = None, format_fn: Optional[Callable[[Any], str]] = None) -> ColumnSpec:
+    hdr = header or str(key).replace("_", " ").title()
+    return ColumnSpec(name=key, header=hdr, extractor=lambda r: (r.metadata or {}).get(key), format_fn=format_fn)
+
+
+__all__ = [
+    "ResultModel",
+    "ColumnSpec",
+    "ProviderAdapter",
+    "Renderer",
+    "ensure_result_model",
+    "title_column",
+    "ext_column",
+]