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

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

@@ -7,6 +7,41 @@ 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
+- `list_protests()` now accepts `naics_code`, filtering protests by the solicitation's NAICS code. The API has always supported it (verified live: 15,027 protests unfiltered, 12 for `541519`, 2 for `336411`), but `protests` was absent from the conformance checker's resource-to-method map, so the gap was never reported.
+- `list_psc()` now accepts `has_awards`, restricting results to codes with contract award history (2,526 PSC codes unfiltered, 2,243 with awards). `False` is sent explicitly rather than dropped, since the API distinguishes the two. This param has always worked but was invisible to the contract until [makegov/tango#2948](https://github.com/makegov/tango/pull/2948) added the `view_handled_params` declaration for params a viewset reads straight from `query_params`. That PR also fixed a truthiness bug where `has_awards=false` filtered identically to `true`, and is deployed — verified live at 2,526 for `False` and 2,243 for `True`.
+
+  One caveat that is not an SDK issue: `/api/psc/` responses are cached for 30 days per query-param key, so any `?has_awards=` key requested *before* that deploy still serves the old awards-only result until its entry expires or is invalidated.
+
+### Fixed
+- **The reverse shape-coverage gate was blind to seven resources, and the SDK's schemas had silently drifted behind four of them.** The gate skipped any resource whose contract shape tree was falsy (`if not shape: continue`). Tango published `"shape": null` for `entities`, `opportunities`, `notices`, `protests`, `itdashboard`, `events`, and `news` — five of them because its contract generator crashed on tier-aware viewsets ([makegov/tango#2944](https://github.com/makegov/tango/pull/2944)) — so the gate reported full coverage while checking nothing for them. Re-vendoring the fixed contract surfaced **69 real gaps** (36 fields, 20 expands, 13 flattened expands) across entities, notices, protests, and itdashboard, all now closed by a regenerated overlay.
+
+  The user-visible consequence was worse than missing schema entries. Because `ShapeParser` validates client-side, the SDK *rejected* 13 fields the API accepts, before ever issuing a request — `list_entities(shape="display_name")` raised `ShapeValidationError` against an endpoint that returns 200 for it. Affected: `Entity`'s `display_name`, `entity_type`, `entity_structure`, `organization_structure`, `profit_structure`, `purpose_of_registration`, `country_of_incorporation`, `past_performance`, `registered`, `sba_business_types`, and `Protest`'s `decisions`, `resolved_agency`, `resolved_protester`. All 13 now validate. Note that `registered` and `sba_business_types` regressed *in 1.3.0* — they validated under 1.1.1 — so the overlay generation had narrowed `Entity` while nothing was watching.
+
+  The gate no longer skips silently: a resource declaring `shape_supported: true` with no shape tree is now a hard finding (`contract_missing_shape`) reported as an upstream contract defect rather than an SDK one. Contracts predating `schema_version: 2` omit the key, where a null tree stays genuinely ambiguous and skipping remains correct.
+- **Seven resources with working SDK methods were never conformance-checked at all.** `RESOURCE_TO_METHOD` omitted `protests`, `psc`, `mas_sins`, `departments`, `business_types`, and `assistance_listings` entirely, and mapped `offices` to `None` as "not yet implemented" even though `list_offices` exists. Their filter coverage had never been validated. Wiring them up found one real gap (`protests.naics_code`, above); the other six were already complete. `events` and `news` stay mapped to `None` — genuinely absent from the SDK, now with a note explaining that `list_webhook_event_types` is unrelated.
+- **`refresh_contract.py` + `probe_shape_types.py` re-run against the corrected contract.** `contracts/observed_shape_types.json` gained live-sampled types for the five newly-visible resources (entities alone contributes 136 observed paths), so the regenerated overlay resolves their types from real API responses rather than name heuristics.
+
+### Changed
+- `CONTRACT_OMITTED_PARAMS` now warns when an entry is no longer needed, mirroring how baseline entries are burned down, and the list is now **empty** — which is the goal state. It briefly held `mas_sins: search`, added because the API applies it (330 results unfiltered, 0 for a nonsense term, 32 for `office`) while the contract recorded `filter_params: []`, so the checker would otherwise have flagged a working parameter as a silent no-op and invited its removal. Both that entry and `budget/accounts: search` were retired by the new warning once [makegov/tango#2944](https://github.com/makegov/tango/pull/2944) and [#2948](https://github.com/makegov/tango/pull/2948) taught the contract generator to publish them. The carve-out mechanism stays for the next such case.
+
 ## [1.3.0] - 2026-07-19
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 1.3.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.3.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.3.0 → tango_python-1.5.0}/pyproject.toml

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

{tango_python-1.3.0 → tango_python-1.5.0}/scripts/check_filter_shape_conformance.py

@@ -74,21 +74,35 @@ RESOURCE_TO_METHOD: dict[str, str | None] = {
     "exclusions": "list_exclusions",
     "sbir/topics": "list_sbir_topics",
     "sbir/solicitations": "list_sbir_solicitations",
-    # Resources not yet implemented in SDK
-    "offices": None,
+    "protests": "list_protests",
+    "offices": "list_offices",
+    "psc": "list_psc",
+    "mas_sins": "list_mas_sins",
+    "departments": "list_departments",
+    "business_types": "list_business_types",
+    "assistance_listings": "list_assistance_listings",
+    # Genuinely absent from the SDK. Both are content endpoints with no shaping
+    # and no list method; `list_webhook_event_types` is unrelated to `events`.
+    "events": None,
+    "news": None,
 }
 
 # Params the API genuinely accepts but the contract omits, so they would read as
-# stale (a silent no-op) when they in fact work. Tango surfaces view-handled
-# search params for filtersets that declare `min_length_params`; where it does
-# not, the param is absent from the contract even though the endpoint honors it.
+# stale (a silent no-op) when they in fact work. Tango's generator surfaces
+# view-handled search params only for filtersets declaring `min_length_params`
+# and DRF `SearchFilter` backends declaring `search_fields`; a resource that
+# implements search another way is absent from the contract even though the
+# endpoint honors it.
+#
 # Each entry must be verified against the live API before being added, and
-# removed once Tango's contract generator surfaces it.
-#   budget/accounts `search`: verified 2026-07-19 — 21,170 results unfiltered vs
-#   0 for a nonsense term, so the endpoint clearly applies it.
-CONTRACT_OMITTED_PARAMS: dict[str, frozenset[str]] = {
-    "budget/accounts": frozenset({"search"}),
-}
+# removed once Tango's generator surfaces it — `check_conformance` warns when an
+# entry is no longer needed, so this list cannot quietly rot.
+#
+# Currently empty, and that is the goal state. Two entries have come and gone:
+# budget/accounts `search` (published by makegov/tango#2944's SearchFilter
+# extraction) and mas_sins `search` (published by makegov/tango#2948's
+# `view_handled_params` declaration). Both were retired by the warning above.
+CONTRACT_OMITTED_PARAMS: dict[str, frozenset[str]] = {}
 
 # SDK-level conveniences that never correspond to API filter params.
 # `sort`/`order` compose into the API's `ordering`; `filters` is the legacy
@@ -395,11 +409,22 @@ def run_check(manifest_path: Path) -> tuple[list[str], list[str]]:
             )
 
         # Direction 2 — staleness: SDK sends it, API no longer accepts it.
+        omitted = CONTRACT_OMITTED_PARAMS.get(resource_name, frozenset())
+
+        # A carve-out is only justified while the contract still omits the param.
+        # Once Tango publishes it, the entry hides real staleness — warn so it
+        # gets removed, mirroring how baseline entries are burned down above.
+        redundant = sorted(omitted & runtime_filters)
+        if redundant:
+            warnings.append(
+                f"{resource_name}: CONTRACT_OMITTED_PARAMS entries no longer needed "
+                f"(the contract now publishes them): {', '.join(redundant)}"
+            )
+
         stale = sorted(
             f"{arg} (sends `{api_param}`)" if arg != api_param else arg
             for arg, api_param in exposed.items()
-            if api_param not in runtime_filters
-            and api_param not in CONTRACT_OMITTED_PARAMS.get(resource_name, frozenset())
+            if api_param not in runtime_filters and api_param not in omitted
         )
         if stale:
             errors.append(

{tango_python-1.3.0 → tango_python-1.5.0}/scripts/check_shape_coverage.py

@@ -171,8 +171,29 @@ def collect_gaps(contract: dict[str, Any], registry: Any, models: Any) -> list[d
             walk(resource, child_path, enode, child_schema)
 
     for rkey, r in contract.get("resources", {}).items():
-        shape = (r.get("runtime") or {}).get("shape")
+        runtime = r.get("runtime") or {}
+        shape = runtime.get("shape")
         if not shape:
+            # A null tree used to be an unconditional skip, which made this gate
+            # blind to exactly the resources it most needed to check. Tango
+            # published null for entities/opportunities/notices/protests/
+            # itdashboard because its generator crashed on tier-aware viewsets
+            # (makegov/tango#2944), and this gate reported full coverage while
+            # the SDK's Entity and Protest schemas drifted 13 fields behind.
+            #
+            # Contracts at schema_version >= 2 declare shape_supported, so a
+            # null tree on a shaping resource is now a hard finding. Older
+            # contracts omit the key; there `None` is genuinely ambiguous and
+            # skipping stays the only safe read.
+            if runtime.get("shape_supported"):
+                findings.append(
+                    {
+                        "kind": "contract_missing_shape",
+                        "resource": rkey,
+                        "path": "(root)",
+                        "name": runtime.get("shape_error") or "no shape tree published",
+                    }
+                )
             continue
         model_name = RESOURCE_TO_MODEL.get(rkey)
         model = getattr(models, model_name, None) if model_name else None
@@ -305,6 +326,19 @@ def main() -> int:
         print("\nNo new shape-coverage drift. ✓")
         return 0
 
+    contract_gaps = [f for f in new if f["kind"] == "contract_missing_shape"]
+    if contract_gaps:
+        print(
+            "\n*** CONTRACT DEFECT — these resources support shaping but publish no shape tree ***"
+        )
+        _print_grouped("RESOURCES WITH NO SHAPE TREE", contract_gaps)
+        print(
+            "\n  This is an upstream problem, not an SDK one: the vendored contract understates\n"
+            "  the API, so coverage cannot be checked for these resources at all. Refresh the\n"
+            "  contract (scripts/refresh_contract.py); if it persists, the generator is failing\n"
+            "  to extract them — see makegov/tango contracts/README.md."
+        )
+
     print("\n*** NEW shape-coverage drift (Tango exposes these; the SDK schema does not) ***")
     _print_grouped("MISSING FIELDS", [f for f in new if f["kind"] == "missing_field"])
     _print_grouped("MISSING EXPANDS", [f for f in new if f["kind"] == "missing_expand"])

{tango_python-1.3.0 → tango_python-1.5.0}/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",