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

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

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 1.3.0
+Version: 1.4.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

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

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

{tango_python-1.3.0 → tango_python-1.4.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.4.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.4.0}/tango/__init__.py

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

{tango_python-1.3.0 → tango_python-1.4.0}/tango/client.py

@@ -2540,6 +2540,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 +2570,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 +2596,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:
@@ -4445,8 +4448,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,6 +4462,8 @@ 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)),