feat: tango-python 1.0.0 — API parity, webhook overhaul, docs auto-pull, packaging guardrails

[makegov-hal]

Status (2026-05-13): This PR now ships as tango-python 1.0.0. The scope grew significantly past the original "API parity" framing — full release notes below. Outstanding Copilot threads on this PR have all been addressed or replied to as stale; the Windows CI flake on test_receiver_404s_on_unknown_path is fixed.

1.0.0 release notes (additions since this PR was opened)

This PR was originally scoped to the API parity work captured below. Over the last week it absorbed three additional changesets and a packaging hardening pass, which collectively justify the major-version bump from 0.6.x → 1.0.0:

• Webhook signature scheme change (224878e, tango#2252) — generate_signature(body, secret) now returns the canonical "sha256=<hex>" wire form instead of bare hex. Breaking for receivers that consumed the bare hex directly. verify_signature still accepts both forms.
• Subject-based webhook subscription surface removed (7ede733, tango#2275) — list_webhook_subscriptions / get_webhook_subscription / create_webhook_subscription / update_webhook_subscription / delete_webhook_subscription and the WebhookSubscription / WebhookSubjectTypeDefinition dataclasses are gone. Subject filtering migrates to create_webhook_alert(...) and the alerts API.
• Shape validator agrees with server on naics(...) / psc(...) expansions (7b233c5, tango#2266) — ShapeParser.validate() now mirrors the server's _EXPAND_ALIASES table; naics_code(...) and psc_code(...) aliases are rewritten to the canonical form at parse time. Closes the parser-vs-server divergence flagged in tango#2266.
• create_webhook_endpoint(name=...) is now required, not deprecated (132641f, addresses Copilot review). 0.7.0 was going to emit a DeprecationWarning; since 0.7.0 never publicly released, 1.0.0 makes it a hard TangoValidationError instead. The server enforces unique(user, name) so the warn-then-400 path was strictly worse DX.
• _post / _patch raise on json_data=+json= collision (132641f) — previously silently preferred json_data. Now raises TangoValidationError to surface caller bugs.
• Doc port + auto-pull (42d760d, makegov/docs#16) — new docs/ERRORS.md, docs/PAGINATION.md, docs/CLIENT.md ported from docs.makegov.com/sdks/python/ so the docs-site auto-pull (makegov/docs#15) can replace the hand-maintained pages.
• docs-dispatch CI workflow (401207e, makegov/docs#15) — fires on push to main for docs/**, README.md, CHANGELOG.md. Triggers a rebuild of docs.makegov.com when the SDK content changes.
• Packaging guardrails (06e7feb) — explicit [tool.hatch.build.targets.sdist] whitelist. Even from a developer laptop, uv publish can no longer bundle .mg-tools/, .claude/, CLAUDE.md, ROADMAP.md, work diaries, scratch reports, or .coverage to PyPI. CI publishing was already clean; this closes the local-publish foot-gun.
• Windows webhook-receiver test fix (132641f) — do_POST now drains the request body before returning a 404, fixing WinError 10053 on windows-latest runners.

CHANGELOG [1.0.0] section reflects everything above. [Unreleased] is empty.

---

Summary

Brings tango-python to full API parity with Tango: 30+ new methods, signature fixes for write paths, ordering kwargs on list endpoints that were silently missing them, and four new typed response models. 278 unit tests pass, 45/45 smoke checks pass against a running Tango instance, 80% line coverage across the package.

Branch: 5 commits on feat/api-parity off main.

What's new

Resolve / Validate utilities (typed wrappers)

Two new top-level methods replace the prior client._post("/api/resolve/", ...) workaround:

• resolve(name, target_type, ...) — POST /api/resolve/. Returns a typed ResolveResult with ResolveCandidate entries (identifier, display_name, match_tier on Pro+). Optional context: state, city, context string. Backed by new dataclasses exported from the package root.
• validate(identifier_type, value) — POST /api/validate/. Returns ValidateResult.

Webhook alerts CRUD parity

The convenience layer over /api/webhooks/alerts/ (filter subscriptions) was previously create-only. Full CRUD now:

• list_webhook_alerts(...)
• get_webhook_alert(id)
• create_webhook_alert(name=, query_type=, filters=, frequency=, cron_expression=)
• update_webhook_alert(id, ...)
• delete_webhook_alert(id)

WebhookAlert dataclass exported from tango.

Webhook write-method signatures, completed

The SDK's write methods were missing fields that the Tango API has required since multi-endpoint support landed. Catching up:

• create_webhook_endpoint now accepts name= (keyword-only). Required by the server; omitting it emits a DeprecationWarning and will become an error in a future major version.
• create_webhook_subscription accepts endpoint=, subscription_type=, query_type=, filter_definition=, frequency=, cron_expression=, is_active= — covers both subject and filter subscription patterns through the canonical /api/webhooks/subscriptions/ API.
• update_webhook_subscription accepts frequency=, cron_expression=, is_active=.
• update_webhook_endpoint accepts name= for renames.

Reference data

list_departments, get_department, list_psc, get_psc, get_psc_metrics, get_naics, get_naics_metrics, get_business_type, list_assistance_listings, get_assistance_listing, list_mas_sins, get_mas_sin.

Entity sub-resources

list_entity_contracts, list_entity_idvs, list_entity_otas, list_entity_otidvs, list_entity_subawards, list_entity_lcats, get_entity_metrics. All shape-aware where the underlying endpoint supports shaping.

IDV + agency sub-resources

• list_idv_lcats
• list_agency_awarding_contracts, list_agency_funding_contracts

Misc

• search_opportunity_attachments(q, top_k, include_extracted_text) for /api/opportunities/attachment-search/
• get_version() for /api/version/
• list_api_keys() for /api/api-keys/

ordering parameter where the API supports it

Seven list methods now accept ordering= and pass it through:

list_forecasts, list_grants, list_subawards, list_gsa_elibrary_contracts, list_opportunities, list_notices, list_protests. Prefix with - for descending. This closes parity gaps where the API documented ?ordering= but the SDK silently rejected the kwarg.

Fixed

• TangoClient._post() and _patch() now accept both json_data= (positional, original) and json= (kwarg). Internal callers and docs examples that use json= no longer fail with TypeError.

Testing

• pytest: 412 passed, 31 skipped — was 238 before this branch; +40 new tests in tests/test_api_parity.py.
• 80% line coverage across tango/ (pytest --cov).
• mypy clean on changed code; ruff clean.
• Smoke (scripts/smoke_api_parity.py against http://localhost:8000): 45/45 pass. Three blocks SKIPped for environmental reasons (/attachment-search/ 404 locally, /funding-contracts/ 504 on the test agency, create_webhook_alert skipped when the test account has multiple endpoints — see makegov/tango#2256).
• All smoke-test webhook resources cleaned up — zero leftover endpoints/subs/alerts.

Decisions worth flagging

• Kept uuid= on vehicle methods (list_vehicle_awardees, list_vehicle_orders). Matches the existing get_vehicle(uuid) path-param convention. SDK convention: IDVs use key=, vehicles use uuid=.

Known issues uncovered during parity work (tracked separately on tango)

• makegov/tango#2252 — Webhooks v2 inconsistency: /subscriptions/ POST uses field endpoint; /endpoints/test-delivery/ uses endpoint_id.
• makegov/tango#2254 — OpenAPI advertises ordering on /notices/, /protests/, /subawards/ but viewsets reject most values.
• makegov/tango#2256 — Multi-endpoint accounts can't use /api/webhooks/alerts/; backend needs to accept an explicit endpoint field on the alert create serializer before the SDKs can paper over the limitation.

Risks

• No breaking changes to existing public methods. New kwargs are keyword-only with safe defaults; backward-compatible across the board.
• DeprecationWarning on create_webhook_endpoint without name= may surface in user logs — intentional, since the API will eventually reject name-less requests outright.

Sibling work

Companion PR in tango-node covers the same parity work for the Node SDK. Docs are updated to reflect both SDKs' new surfaces in makegov/docs#9.

– Hal 🤖