tango-python 1.4.0__tar.gz → 1.5.0__tar.gz

{tango_python-1.4.0 → tango_python-1.5.0}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-08-04
+
+### Added
+- **`relationships(type, source)` on entities.** Tango API 4.20.0 added two keys to each entry in the entity `relationships` expand: `type`, the stable relationship-type code (`prime_sub`, `parent_subsidiary`, `ultimate_parent`, `predecessor`), and `source`, where the tie came from (`sam`, `subawards`). Both are shape-selectable, so `shape="uei,relationships(type,source,uei)"` now resolves against the SDK's schema. Re-vendored the contract and regenerated the shape overlay; the coverage gate reports 0 gaps.
+- `PaginatedResponse.meta` now carries the response-level `meta` block the API returns, with three accessors over it: `unresolved_agency_tokens` (agency tokens that matched nothing, per filter), `resolved_agencies` (the organization each token *did* match), and `agency_warnings` (the API's human-readable notes). Agency values resolve fuzzily, so a token can match an organization the caller did not intend and quietly scope the query to that subtree — and a token that resolves to nothing was previously dropped with no signal at all. Both cases were indistinguishable from "no such records exist". The API now reports both; until now the SDK read the envelope key-by-key and dropped `meta` on the floor, so SDK users were the one group that could not see it. `resolved_agencies` is the accessor that matters for the wrong-organization case: nothing is dropped there, so an unresolved-token check cannot detect it. All accessors return empty rather than raising when `meta` is absent (most responses) or malformed.
+- A fully-unresolvable agency filter now raises `TangoValidationError` naming the offending value instead of returning an empty page. This needed no SDK change — the existing 400 handler already reads the API's `error` key — but it is new behavior for callers of `list_subawards()`, `list_opportunities()`, `list_notices()`, and `list_vehicles()`, which previously returned an empty result set. Contracts, IDVs, OTAs, and OTIDVs already behaved this way.
+
+### Changed
+- **The `relation` value vocabulary changed upstream — match on `type` instead.** In Tango API 4.20.0 the `relation` label stopped collapsing to `affiliate` for subcontracting and corporate-succession ties and now names the partner's role: `subcontractor` / `prime`, `predecessor` / `successor`, and `descendant` (rather than `child`) on the far side of an ultimate-parent tie. `affiliate` survives only as a fallback for a type the API doesn't recognize. This affects the large majority of relationship entries.
+
+  No SDK code change is required — `relation` was and remains a `str`. But if you have application code branching on the string `affiliate`, switch it to `type`, which is stable and won't churn again. See the [entities data dictionary](https://docs.makegov.com/data-dictionary/entities/#relationships) for the full vocabulary table.
+
+### Notes
+- `PaginatedResponse.page_metadata` is documented as always `None`: the API has never emitted a `page_metadata` key, so the field has only ever read a value that does not exist. It is retained so existing attribute access keeps working. Use `meta`.
+
 ## [1.4.0] - 2026-07-20
 
 ### Added

{tango_python-1.4.0 → tango_python-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 1.4.0
+Version: 1.5.0
 Summary: Python SDK for the Tango API
 Project-URL: Homepage, https://github.com/makegov/tango-python
 Project-URL: Documentation, https://docs.makegov.com/tango-python
@@ -191,9 +191,37 @@ contracts = client.list_contracts(
 - `expiring_gte`, `expiring_lte` - Contract expiration date range
 
 **Party Filters:**
-- `awarding_agency`, `funding_agency` - Agency codes
+- `awarding_agency`, `funding_agency` - Agency codes, names, abbreviations, or organization UUIDs. Multi-value OR via `|`.
 - `recipient_name`, `recipient_uei` - Vendor/recipient filters
 
+### Checking how agency filters resolved
+
+Agency values are resolved fuzzily, so a token can match an organization you did not
+intend — which silently scopes the query to that organization's subtree. A short result
+set is then indistinguishable from "no such records exist". Responses expose what
+actually happened:
+
+```python
+response = client.list_contracts(awarding_agency="HUD|HUDD")
+
+# Tokens that matched nothing and were ignored.
+if response.unresolved_agency_tokens:
+    raise SystemExit(f"dropped: {response.unresolved_agency_tokens}")
+    # {'awarding_agency': ['HUDD']}
+
+# What the tokens that DID match resolved to — the only way to catch a
+# plausible-but-wrong match, where nothing was dropped at all.
+for org in response.resolved_agencies.get("awarding_agency", []):
+    print(org["name"], org["cgac"])
+    # Department of Housing and Urban Development 086
+
+for warning in response.agency_warnings:
+    print(warning)
+```
+
+If *every* token for a filter fails to resolve, the API returns `400` and the SDK raises
+`TangoValidationError` naming the offending value, rather than an empty page.
+
 **Classification:**
 - `naics_code`, `psc_code` - Industry/product codes
 - `set_aside_type` - Set-aside type

{tango_python-1.4.0 → tango_python-1.5.0}/README.md

@@ -137,9 +137,37 @@ contracts = client.list_contracts(
 - `expiring_gte`, `expiring_lte` - Contract expiration date range
 
 **Party Filters:**
-- `awarding_agency`, `funding_agency` - Agency codes
+- `awarding_agency`, `funding_agency` - Agency codes, names, abbreviations, or organization UUIDs. Multi-value OR via `|`.
 - `recipient_name`, `recipient_uei` - Vendor/recipient filters
 
+### Checking how agency filters resolved
+
+Agency values are resolved fuzzily, so a token can match an organization you did not
+intend — which silently scopes the query to that organization's subtree. A short result
+set is then indistinguishable from "no such records exist". Responses expose what
+actually happened:
+
+```python
+response = client.list_contracts(awarding_agency="HUD|HUDD")
+
+# Tokens that matched nothing and were ignored.
+if response.unresolved_agency_tokens:
+    raise SystemExit(f"dropped: {response.unresolved_agency_tokens}")
+    # {'awarding_agency': ['HUDD']}
+
+# What the tokens that DID match resolved to — the only way to catch a
+# plausible-but-wrong match, where nothing was dropped at all.
+for org in response.resolved_agencies.get("awarding_agency", []):
+    print(org["name"], org["cgac"])
+    # Department of Housing and Urban Development 086
+
+for warning in response.agency_warnings:
+    print(warning)
+```
+
+If *every* token for a filter fails to resolve, the API returns `400` and the SDK raises
+`TangoValidationError` naming the offending value, rather than an empty page.
+
 **Classification:**
 - `naics_code`, `psc_code` - Industry/product codes
 - `set_aside_type` - Set-aside type

{tango_python-1.4.0 → tango_python-1.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "1.4.0"
+version = "1.5.0"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"

{tango_python-1.4.0 → tango_python-1.5.0}/tango/__init__.py

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

{tango_python-1.4.0 → tango_python-1.5.0}/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(
@@ -2614,6 +2640,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_protest(
@@ -2750,6 +2777,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_dibbs_rfq(
@@ -2869,6 +2897,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_dibbs_rfp(
@@ -3006,6 +3035,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_dibbs_award(
@@ -3151,6 +3181,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_exclusion(
@@ -3278,6 +3309,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_sbir_topic(
@@ -3398,6 +3430,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_sbir_solicitation(
@@ -3772,6 +3805,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_budget_account(
@@ -3823,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(
@@ -3850,6 +3885,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=data.get("results") or [],
+            meta=data.get("meta"),
         )
 
     # Grant endpoints
@@ -3943,6 +3979,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def get_grant(
@@ -4035,6 +4072,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def create_webhook_endpoint(
@@ -4219,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:
@@ -4433,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]:
@@ -4470,6 +4510,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     def get_psc(
@@ -4570,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(
@@ -4616,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(
@@ -4685,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(
@@ -4860,6 +4904,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=results,
+            meta=data.get("meta"),
         )
 
     def list_entity_lcats(
@@ -4890,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]:
@@ -4930,6 +4976,7 @@ class TangoClient:
             next=data.get("next"),
             previous=data.get("previous"),
             results=list(data.get("results") or []),
+            meta=data.get("meta"),
         )
 
     # ============================================================================
@@ -4987,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_python-1.4.0 → tango_python-1.5.0}/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

{tango_python-1.4.0 → tango_python-1.5.0}/tango/shapes/generated_overlay.py

@@ -716,6 +716,8 @@ PRIMARY_CONTACT_SCHEMA: dict[str, FieldSchema] = {
 RELATIONSHIPS_SCHEMA: dict[str, FieldSchema] = {
     "display_name": FieldSchema(name="display_name", type=str, is_optional=True, is_list=False),
     "relation": FieldSchema(name="relation", type=str, is_optional=True, is_list=False),
+    "source": FieldSchema(name="source", type=str, is_optional=True, is_list=False),
+    "type": FieldSchema(name="type", type=str, is_optional=True, is_list=False),
     "uei": FieldSchema(name="uei", type=str, is_optional=True, is_list=False),
 }