focus-data-toolkit 0.11.0__py3-none-any.whl

focus_data_toolkit/context/__init__.py

@@ -0,0 +1,88 @@
+"""Billing and provider context objects, determined per row (never from the first row)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+from focus_data_toolkit.context.billing import (
+    BillingContext,
+    billing_context_of_row,
+    distinct_billing_contexts,
+)
+from focus_data_toolkit.context.provider import (
+    ProviderContext,
+    distinct_provider_contexts,
+    provider_context_of_row,
+    representative_from_contexts,
+    representative_provider,
+)
+
+# Cap on how many distinct values a summary lists inline (keeps the manifest bounded).
+_SAMPLE_CAP = 25
+
+
+def _capped(values: list[str]) -> dict:
+    return {"count": len(values), "sample": values[:_SAMPLE_CAP]}
+
+
+def summarize_contexts(
+    providers: list[ProviderContext], billing: list[BillingContext]
+) -> dict:
+    """Build the bounded context summary from already-distinct provider/billing contexts.
+
+    Shared by :func:`describe_source_contexts` (eager) and the streaming pipeline, which
+    accumulates the distinct contexts incrementally — so both produce an identical summary.
+    """
+    issuers = sorted({b.invoice_issuer_name for b in billing if b.invoice_issuer_name})
+    accounts = sorted({b.billing_account_id for b in billing if b.billing_account_id})
+    currencies = sorted({b.billing_currency for b in billing if b.billing_currency})
+    periods = sorted(
+        {(b.billing_period_start, b.billing_period_end) for b in billing if b.billing_period_start}
+    )
+
+    return {
+        "providers": {
+            "count": len(providers),
+            "sample": [p.as_dict() for p in providers[:_SAMPLE_CAP]],
+        },
+        "invoice_issuers": _capped(issuers),
+        "billing_accounts": _capped(accounts),
+        "billing_currencies": _capped(currencies),
+        "billing_periods": {
+            "count": len(periods),
+            "sample": [list(p) for p in periods[:_SAMPLE_CAP]],
+        },
+        "multi_provider": len(providers) > 1,
+        "multi_issuer": len(issuers) > 1,
+        "multi_currency": len(currencies) > 1,
+        "multi_period": len(periods) > 1,
+    }
+
+
+def describe_source_contexts(
+    rows: Iterable[Mapping[str, str]], source_version: str
+) -> dict:
+    """A bounded, JSON-serialisable summary of the contexts present in a source.
+
+    Reports distinct providers, issuers, accounts, currencies and periods, and boolean
+    ``multi_*`` flags — enough for the manifest to show that (e.g.) the source mixed two
+    issuers and three currencies, without embedding the full cross-product.
+    """
+    rows = list(rows)
+    return summarize_contexts(
+        distinct_provider_contexts(rows, source_version), distinct_billing_contexts(rows)
+    )
+
+
+__all__ = [
+    "BillingContext",
+    "ProviderContext",
+    "billing_context_of_row",
+    "describe_source_contexts",
+    "distinct_billing_contexts",
+    "distinct_provider_contexts",
+    "provider_context_of_row",
+    "representative_from_contexts",
+    "representative_provider",
+    "summarize_contexts",
+]

focus_data_toolkit/context/billing.py

@@ -0,0 +1,54 @@
+"""Billing context — issuer, account, currency and period, determined per row.
+
+An export can consolidate many billing accounts, currencies, issuers and periods. Grouping
+and enrichment must key on the billing context of each row, never on a single global value.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import astuple, dataclass
+
+
+@dataclass(frozen=True)
+class BillingContext:
+    """The billing identity of a charge line."""
+
+    invoice_issuer_name: str
+    billing_account_id: str
+    billing_currency: str
+    billing_period_start: str
+    billing_period_end: str
+
+    @property
+    def is_complete(self) -> bool:
+        return all(astuple(self))
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "invoice_issuer_name": self.invoice_issuer_name,
+            "billing_account_id": self.billing_account_id,
+            "billing_currency": self.billing_currency,
+            "billing_period_start": self.billing_period_start,
+            "billing_period_end": self.billing_period_end,
+        }
+
+
+def billing_context_of_row(row: Mapping[str, str]) -> BillingContext:
+    """Derive the billing context of a single row (empty where a field is absent)."""
+    return BillingContext(
+        (row.get("InvoiceIssuerName") or "").strip(),
+        (row.get("BillingAccountId") or "").strip(),
+        (row.get("BillingCurrency") or "").strip(),
+        (row.get("BillingPeriodStart") or "").strip(),
+        (row.get("BillingPeriodEnd") or "").strip(),
+    )
+
+
+def distinct_billing_contexts(rows: Iterable[Mapping[str, str]]) -> list[BillingContext]:
+    """Return the distinct billing contexts across ``rows`` (deterministically ordered)."""
+    seen: dict[tuple[str, ...], BillingContext] = {}
+    for row in rows:
+        ctx = billing_context_of_row(row)
+        seen[astuple(ctx)] = ctx
+    return [seen[key] for key in sorted(seen)]

focus_data_toolkit/context/provider.py

@@ -0,0 +1,90 @@
+"""Provider context — service provider vs host provider, determined per row.
+
+The service provider (who sells the charge) and the host provider (whose infrastructure it
+runs on) can differ: marketplaces, resellers, MSPs, and third-party services hosted on a
+cloud. This context is therefore a **per-row** property; it must never be inferred once from
+the first row of a file and applied globally.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProviderContext:
+    """Who sells a charge (service) and whose infrastructure hosts it (host)."""
+
+    service_provider_name: str
+    host_provider_name: str
+
+    @property
+    def is_complete(self) -> bool:
+        return bool(self.service_provider_name) and bool(self.host_provider_name)
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "service_provider_name": self.service_provider_name,
+            "host_provider_name": self.host_provider_name,
+        }
+
+
+def provider_context_of_row(row: Mapping[str, str], source_version: str) -> ProviderContext:
+    """Derive the provider context of a single Cost and Usage row.
+
+    A 1.2 source expresses the service provider as ``ProviderName``; 1.3+ uses the
+    ``ServiceProviderName`` / ``HostProviderName`` split (falling back to the deprecated
+    ``ProviderName`` if a 1.3 export still carries it). A source that does not expose the
+    underlying host gets ``host == service`` — FOCUS requires ``HostProviderName`` to
+    match ``ServiceProviderName`` in that case. The deprecated ``PublisherName`` (the
+    entity that *produced* the service) is never treated as a host. Absent values stay
+    empty (UNAVAILABLE).
+    """
+    if source_version == "1.2":
+        service = row.get("ProviderName", "") or ""
+        host = service
+    else:
+        service = row.get("ServiceProviderName", "") or row.get("ProviderName", "") or ""
+        host = row.get("HostProviderName", "") or service
+    return ProviderContext(service.strip(), host.strip())
+
+
+def distinct_provider_contexts(
+    rows: Iterable[Mapping[str, str]], source_version: str
+) -> list[ProviderContext]:
+    """Return the distinct provider contexts across ``rows`` (deterministically ordered)."""
+    seen: dict[tuple[str, str], ProviderContext] = {}
+    for row in rows:
+        ctx = provider_context_of_row(row, source_version)
+        seen[(ctx.service_provider_name, ctx.host_provider_name)] = ctx
+    return [seen[key] for key in sorted(seen)]
+
+
+def representative_from_contexts(
+    contexts: list[ProviderContext],
+) -> tuple[ProviderContext, bool]:
+    """Choose a representative provider from already-distinct contexts (see below)."""
+    if not contexts:
+        return ProviderContext("", ""), False
+    # Prefer a usable representative: a fully complete context, else one with a non-empty
+    # service provider, else the first. This avoids enriching with a blank provider (which
+    # would fail the lint) when the same source also carries a complete provider elsewhere.
+    chosen = (
+        next((c for c in contexts if c.is_complete), None)
+        or next((c for c in contexts if c.service_provider_name), None)
+        or contexts[0]
+    )
+    return chosen, len(contexts) > 1
+
+
+def representative_provider(
+    rows: Iterable[Mapping[str, str]], source_version: str
+) -> tuple[ProviderContext, bool]:
+    """Return ``(context, ambiguous)`` — a usable representative and whether >1 exist.
+
+    Used only where a single value must be chosen for enrichment (e.g. synthetic Contract
+    Commitment, which the 1.3 source leaves without a provider). ``ambiguous`` is surfaced to
+    the caller so the choice is never silent.
+    """
+    return representative_from_contexts(distinct_provider_contexts(rows, source_version))