tango-python 1.3.0__py3-none-any.whl → 1.5.0__py3-none-any.whl

tango/__init__.py

@@ -50,7 +50,7 @@ from .webhooks import (
 )
 from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "1.3.0"
+__version__ = "1.5.0"
 __all__ = [
     "TangoClient",
     "TangoAPIError",

tango/client.py

@@ -491,6 +491,7 @@ class TangoClient:
                 for ag in (self._parse_agency(agency) for agency in data["results"])
                 if ag is not None
             ],
+            meta=data.get("meta"),
         )
 
     def get_agency(self, code: str) -> Agency:
@@ -521,6 +522,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=data.get("results", []),
+            meta=data.get("meta"),
         )
 
     def get_office(self, code: str) -> dict[str, Any]:
@@ -573,6 +575,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_organization(
@@ -785,6 +788,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=results,
             cursor=data.get("cursor"),
+            meta=data.get("meta"),
         )
 
     def get_contract(
@@ -846,6 +850,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=results,
             cursor=data.get("cursor"),
+            meta=data.get("meta"),
         )
 
     def get_contract_transactions(
@@ -868,6 +873,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=data.get("results") or [],
             cursor=data.get("cursor"),
+            meta=data.get("meta"),
         )
 
     # ============================================================================
@@ -971,6 +977,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=results,
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def get_idv(
@@ -1072,6 +1079,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=results,
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def list_idv_child_idvs(
@@ -1116,6 +1124,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=results,
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def list_idv_transactions(
@@ -1132,6 +1141,7 @@ class TangoClient:
             previous=data.get("previous"),
             results=data.get("results") or [],
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def list_otas(
@@ -1214,6 +1224,7 @@ class TangoClient:
             results=results,
             cursor=data.get("cursor"),
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def get_ota(
@@ -1319,6 +1330,7 @@ class TangoClient:
             results=results,
             cursor=data.get("cursor"),
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def get_otidv(
@@ -1395,6 +1407,7 @@ class TangoClient:
             results=results,
             cursor=data.get("cursor"),
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def list_subawards(
@@ -1449,6 +1462,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_subaward(
@@ -1533,6 +1547,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_gsa_elibrary_contract(
@@ -1639,6 +1654,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_itdashboard_investment(
@@ -1808,6 +1824,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_vehicle(
@@ -1889,6 +1906,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def list_vehicle_orders(
@@ -1937,6 +1955,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     # Business Types endpoints
@@ -1971,6 +1990,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def list_naics(
@@ -2022,6 +2042,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=data.get("results", []),
+            meta=data.get("meta"),
         )
 
     # Entity endpoints
@@ -2108,6 +2129,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_entity(
@@ -2164,6 +2186,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     # Forecast endpoints
@@ -2256,6 +2279,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_forecast(
@@ -2379,6 +2403,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_opportunity(
@@ -2493,6 +2518,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_notice(
@@ -2540,6 +2566,7 @@ class TangoClient:
         filed_date_before: str | None = None,
         decision_date_after: str | None = None,
         decision_date_before: str | None = None,
+        naics_code: str | None = None,
         search: str | None = None,
     ) -> PaginatedResponse:
         """
@@ -2569,6 +2596,7 @@ class TangoClient:
             filed_date_before: Filed date on or before
             decision_date_after: Decision date on or after
             decision_date_before: Decision date on or before
+            naics_code: Filter by the solicitation's NAICS code (e.g. 541519)
             search: Full-text search over protest searchable fields
         """
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
@@ -2594,6 +2622,7 @@ class TangoClient:
             ("filed_date_before", filed_date_before),
             ("decision_date_after", decision_date_after),
             ("decision_date_before", decision_date_before),
+            ("naics_code", naics_code),
             ("search", search),
         ):
             if val is not None:
@@ -2611,6 +2640,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_protest(
@@ -2747,6 +2777,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_dibbs_rfq(
@@ -2866,6 +2897,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_dibbs_rfp(
@@ -3003,6 +3035,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_dibbs_award(
@@ -3148,6 +3181,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_exclusion(
@@ -3275,6 +3309,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_sbir_topic(
@@ -3395,6 +3430,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_sbir_solicitation(
@@ -3769,6 +3805,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_budget_account(
@@ -3820,6 +3857,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=data.get("results") or [],
+            meta=data.get("meta"),
         )
 
     def get_budget_account_recipients(
@@ -3847,6 +3885,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=data.get("results") or [],
+            meta=data.get("meta"),
         )
 
     # Grant endpoints
@@ -3940,6 +3979,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_grant(
@@ -4032,6 +4072,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def create_webhook_endpoint(
@@ -4216,6 +4257,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_webhook_alert(self, alert_id: str) -> WebhookAlert:
@@ -4430,6 +4472,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     def get_department(self, code: str) -> dict[str, Any]:
@@ -4445,8 +4488,13 @@ class TangoClient:
         shape: str | None = None,
         flat: bool = False,
         flat_lists: bool = False,
+        has_awards: bool | None = None,
     ) -> PaginatedResponse[dict[str, Any]]:
-        """List Product Service Codes (`/api/psc/`)."""
+        """List Product Service Codes (`/api/psc/`).
+
+        Args:
+            has_awards: When True, return only codes with contract award history.
+        """
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
         if shape:
             params["shape"] = shape
@@ -4454,12 +4502,15 @@ class TangoClient:
                 params["flat"] = "true"
             if flat_lists:
                 params["flat_lists"] = "true"
+        if has_awards is not None:
+            params["has_awards"] = "true" if has_awards else "false"
         data = self._get("/api/psc/", params)
         return PaginatedResponse(
             count=int(data.get("count", 0)),
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     def get_psc(
@@ -4560,6 +4611,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     def get_assistance_listing(
@@ -4606,6 +4658,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     def get_mas_sin(
@@ -4675,6 +4728,7 @@ class TangoClient:
             results=results,
             cursor=data.get("cursor"),
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def list_entity_contracts(
@@ -4850,6 +4904,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def list_entity_lcats(
@@ -4880,6 +4935,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     def get_entity_metrics(self, uei: str, months: int, period_grouping: str) -> dict[str, Any]:
@@ -4920,6 +4976,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     # ============================================================================
@@ -4977,6 +5034,7 @@ class TangoClient:
             results=results,
             cursor=data.get("cursor"),
             page_metadata=data.get("page_metadata"),
+            meta=data.get("meta"),
         )
 
     def list_agency_awarding_contracts(

tango/models.py

@@ -1044,7 +1044,15 @@ class PaginatedResponse[T]:
         previous: URL for the previous page of results (None if first page)
         results: List of result items (type depends on shape parameter)
         cursor: Cursor token for cursor-based pagination (None if not available)
-        page_metadata: Optional metadata about the current page
+        meta: Response-level metadata the API attached to this page, when present.
+            Currently carries agency-filter diagnostics: ``resolved_filters`` maps
+            each agency filter to the organizations its ``|``-separated tokens
+            resolved to (or ``None``), and ``warnings`` lists human-readable notes
+            about tokens that were dropped or matched loosely. See
+            :meth:`agency_warnings` and :meth:`unresolved_agency_tokens`.
+        page_metadata: Always ``None`` — the API has never emitted a
+            ``page_metadata`` key. Retained so existing attribute access keeps
+            working; use ``meta`` instead.
 
     Examples:
         >>> from tango import TangoClient, ShapeConfig
@@ -1063,8 +1071,92 @@ class PaginatedResponse[T]:
     previous: str | None
     results: list[T]
     cursor: str | None = None
+    meta: dict[str, Any] | None = None
     page_metadata: dict[str, Any] | None = None
 
+    @property
+    def agency_warnings(self) -> list[str]:
+        """Warnings the API raised about agency filters on this request.
+
+        Empty when every supplied agency token resolved cleanly. A non-empty list
+        means part of the filter did not apply, so a small or empty ``results`` is
+        not evidence that no such records exist.
+
+        Examples:
+            >>> response = client.list_contracts(awarding_agency="GSA|NOTANAGENCY")
+            >>> for warning in response.agency_warnings:
+            ...     print(warning)
+            Agency filter 'awarding_agency': 'NOTANAGENCY' did not match any organization and was ignored.
+        """
+        if not self.meta:
+            return []
+        warnings = self.meta.get("warnings")
+        return list(warnings) if isinstance(warnings, list) else []
+
+    @property
+    def unresolved_agency_tokens(self) -> dict[str, list[str]]:
+        """Agency tokens that matched no organization, keyed by filter name.
+
+        Empty when everything resolved. Use this to fail loudly in a pipeline
+        rather than treating a silently-narrowed result set as an answer.
+
+        Examples:
+            >>> response = client.list_contracts(awarding_agency="GSA|NOTANAGENCY")
+            >>> response.unresolved_agency_tokens
+            {'awarding_agency': ['NOTANAGENCY']}
+        """
+        if not self.meta:
+            return {}
+        resolved = self.meta.get("resolved_filters")
+        if not isinstance(resolved, dict):
+            return {}
+        dropped: dict[str, list[str]] = {}
+        for filter_name, entries in resolved.items():
+            if not isinstance(entries, list):
+                continue
+            tokens = [
+                entry["token"]
+                for entry in entries
+                if isinstance(entry, dict)
+                and entry.get("resolved") is None
+                and entry.get("token") is not None
+            ]
+            if tokens:
+                dropped[filter_name] = tokens
+        return dropped
+
+    @property
+    def resolved_agencies(self) -> dict[str, list[dict[str, Any]]]:
+        """What each agency token actually resolved to, keyed by filter name.
+
+        Agency resolution is fuzzy, so a token can match an organization the caller
+        did not intend and scope the query to that subtree instead. Checking the
+        resolved ``name`` is the only way to catch that from the client side — an
+        unresolved-token check cannot, because nothing was dropped.
+
+        Examples:
+            >>> response = client.list_contracts(awarding_agency="HUD")
+            >>> [org["name"] for org in response.resolved_agencies["awarding_agency"]]
+            ['Department of Housing and Urban Development']
+        """
+        if not self.meta:
+            return {}
+        resolved = self.meta.get("resolved_filters")
+        if not isinstance(resolved, dict):
+            return {}
+        matched: dict[str, list[dict[str, Any]]] = {}
+        for filter_name, entries in resolved.items():
+            if not isinstance(entries, list):
+                continue
+            orgs = [
+                entry["resolved"]
+                for entry in entries
+                if isinstance(entry, dict) and isinstance(entry.get("resolved"), dict)
+            ]
+            if orgs:
+                matched[filter_name] = orgs
+        return matched
+
 
 class ShapeConfig:
     """Predefined response shape configurations used as defaults for API methods