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

tango_python-1.4.0/.github/workflows/lint.yml

@@ -0,0 +1,110 @@
+name: Linting
+
+# Lint gate runs on every PR and push to main.
+#
+# - ruff format + ruff check are HARD gates (block the PR).
+# - mypy is a HARD gate: the package type-checks cleanly under strict mypy.
+#   (The earlier ~28-error burn-down is complete.)
+# - The SDK filter/shape conformance check is a HARD gate: it runs against the
+#   vendored contract at contracts/filter_shape_contract.json on every run (no
+#   secrets needed, works on forks). A second, token-gated step compares the
+#   vendored contract against the tango repo's HEAD and emits a staleness
+#   notice (never a failure — tango HEAD may carry unreleased changes).
+#   Refresh the vendored contract with scripts/refresh_contract.py.
+# - Reverse shape-coverage is a HARD gate: check_shape_coverage.py fails when
+#   Tango's shape trees expose a field/expand the SDK schema doesn't capture and
+#   it isn't in contracts/shape_coverage_baseline.json. Also offline (vendored
+#   contract), so it runs on forks. Burn the baseline down with the generator.
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Check formatting with ruff
+      run: uv run ruff format --check tango/
+
+    - name: Lint with ruff
+      run: uv run ruff check tango/
+
+    - name: Type check with mypy
+      run: uv run mypy tango/
+
+  conformance:
+    # Hard gate against the vendored contract (contracts/filter_shape_contract.json).
+    # Runs unconditionally — no secrets required, so forks and tokenless runs
+    # get the full check instead of a silent skip.
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v8.1.0
+      with:
+        version: "latest"
+
+    - name: Set up Python
+      run: uv python install 3.12
+
+    - name: Install dependencies
+      run: uv sync --all-extras
+
+    - name: Check SDK filter/shape conformance (vendored contract)
+      run: uv run python scripts/check_filter_shape_conformance.py
+
+    - name: Check reverse shape coverage (Tango exposes -> SDK captures)
+      # Complements the conformance check with the OTHER direction: fails when
+      # Tango's shape trees expose a field/expand the SDK schema doesn't capture
+      # and it isn't in contracts/shape_coverage_baseline.json. Also offline
+      # against the vendored contract — no secrets, works on forks.
+      run: uv run python scripts/check_shape_coverage.py
+
+    # --- Staleness notice (best-effort, never fails the job) ---------------
+    - name: Determine token availability
+      id: gate
+      env:
+        TANGO_API_REPO_ACCESS_TOKEN: ${{ secrets.TANGO_API_REPO_ACCESS_TOKEN }}
+      run: |
+        if [ -n "$TANGO_API_REPO_ACCESS_TOKEN" ]; then
+          echo "ready=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "ready=false" >> "$GITHUB_OUTPUT"
+          echo "::notice::Contract staleness check skipped — TANGO_API_REPO_ACCESS_TOKEN not configured."
+        fi
+
+    - name: Checkout tango API repo (contract source)
+      if: steps.gate.outputs.ready == 'true'
+      uses: actions/checkout@v6
+      with:
+        repository: makegov/tango
+        path: tango-api
+        token: ${{ secrets.TANGO_API_REPO_ACCESS_TOKEN }}
+
+    - name: Compare vendored contract against tango HEAD
+      if: steps.gate.outputs.ready == 'true'
+      run: |
+        if ! diff -q contracts/filter_shape_contract.json tango-api/contracts/filter_shape_contract.json >/dev/null; then
+          echo "::warning::Vendored contract differs from makegov/tango HEAD. Refresh with: uv run python scripts/refresh_contract.py"
+        else
+          echo "Vendored contract matches makegov/tango HEAD."
+        fi

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

@@ -7,6 +7,133 @@ 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
+- **DIBBS, exclusions, and SBIR/STTR endpoint support.** Six endpoint families
+  Tango shipped in v4.16–v4.18 had no SDK support at all — no models, no methods.
+  Added `list_dibbs_rfqs`/`get_dibbs_rfq`, `list_dibbs_rfps`/`get_dibbs_rfp`,
+  `list_dibbs_awards`/`get_dibbs_award`, `list_exclusions`/`get_exclusion`,
+  `list_sbir_topics`/`get_sbir_topic`, and
+  `list_sbir_solicitations`/`get_sbir_solicitation`, with all 85 filter params,
+  shape schemas, and `ShapeConfig` defaults. New models: `DibbsRfq`, `DibbsRfp`,
+  `DibbsAward`, `Exclusion`, `SbirTopic`, `SbirSolicitation`.
+
+  Two API behaviors are worth knowing. `is_open` (DIBBS) and
+  `is_currently_excluded` (exclusions) are derived at query time, so filter with
+  the `open` / `active` kwargs rather than shaping on those fields. And DIBBS
+  `total_contract_price` is the *order* total repeated on every line item —
+  never sum it across rows; deduplicate on award + delivery-order number first.
+- **Reverse shape-coverage: the SDK now captures every field and expand the API
+  returns.** The conformance check only validated one direction — that the SDK's
+  shape constants reference *allowed* fields. Nothing checked the reverse, so the
+  hand-maintained `tango/shapes/explicit_schemas.py` had silently fallen ~200+
+  fields behind the API: 209 leaf fields, 41 whole nested expand branches, and 3
+  resources (naics, psc, mas_sins) the typed shape API could not request at all.
+  A new generated overlay (`tango/shapes/generated_overlay.py`, produced by
+  `scripts/generate_shape_overlay.py` and merged over the base by `SchemaRegistry`)
+  closes all of them, with types resolved from live-API sampling rather than
+  guessed. Notable now-shapeable data: contract/IDV acquisition attributes
+  (`fair_opportunity_limited_sources`, `subcontracting_plan`, …), `contracts.officers`
+  and `period_of_performance`, the full `organizations` hierarchy
+  (`obligation_rank`, `l1..l8_fh_key`, `budget_appropriation`, `children`/`parent`),
+  `otas`/`otidvs` `transactions`, and the deep `vehicles.awardees[.orders]` tree.
+  Code-object expands (`set_aside`, `award_type`, `idv_type`, …), previously
+  modeled inconsistently as `str`/bare `dict`, now uniformly resolve to
+  `{code, description}`.
+- **Reverse shape-coverage gate.** `scripts/check_shape_coverage.py` walks Tango's
+  shape trees (from the vendored contract) against the SDK schemas and fails when
+  the SDK misses anything the API exposes and it isn't in
+  `contracts/shape_coverage_baseline.json`. Offline against the vendored contract —
+  no token, runs on forks — and wired into the `lint.yml` conformance job.
+  Regenerate the overlay with `scripts/generate_shape_overlay.py` (from the vendored
+  contract + `contracts/observed_shape_types.json`, no API key); refresh the type
+  observations with `scripts/probe_shape_types.py` (maintainer-run, needs a key).
+- **Contract-first conformance system.** The canonical API filter/shape
+  contract is now vendored at `contracts/filter_shape_contract.json` (refresh
+  with the new `scripts/refresh_contract.py`), so the conformance check runs
+  out of the box — locally, in CI, and on forks — with no tango checkout or
+  access token. `scripts/check_filter_shape_conformance.py` gained three new
+  checks on top of filter coverage: **staleness** (an SDK filter argument the
+  API no longer accepts is an error — it would silently no-op), **types**
+  (each argument's annotation is validated against the contract's
+  `schema_version: 2` per-filter type metadata), and a **known-gaps baseline**
+  (`contracts/conformance_baseline.json`) that downgrades accepted missing
+  params from errors to warnings so backlog is tracked instead of silent. A
+  new `--suggest` flag prints ready-to-paste typed parameter scaffolds for
+  any missing filters. The first run against the current API surface found 7
+  real coverage gaps, now baselined: `key` on contracts/IDVs/OTAs/OTIDVs,
+  `cage` on entities, `id` on forecasts, and `opportunity_id` on
+  opportunities.
+- `TangoValidationError` now exposes the API's structured validation details
+  directly: `.issues` (the list of `{"path": ..., "reason": ...}` entries the
+  server returns for shape errors) and `.available_fields` (the endpoint's
+  valid field set, when included). Both were previously reachable only by
+  digging through `.response_data`. ([#45](https://github.com/makegov/tango-python/issues/45))
+
+### Changed
+- The CI conformance job (`lint.yml`) now runs unconditionally against the
+  vendored contract instead of silently skipping when
+  `TANGO_API_REPO_ACCESS_TOKEN` is absent; the token is only used for a
+  best-effort staleness notice comparing the vendored contract to tango HEAD.
+  `scripts/pr_review.py` likewise defaults its conformance step to the
+  vendored contract (override with `TANGO_CONTRACT_MANIFEST`).
+- 400 error messages now name the rejected field(s) and reason when the API
+  returns structured `issues` — e.g.
+  `Invalid request parameters: Invalid shape: tradeoff_process (unknown_field)`
+  instead of just `Invalid request parameters: Invalid shape`. ([#45](https://github.com/makegov/tango-python/issues/45))
+
+### Fixed
+- **`docs/WEBHOOKS.md` listed only five of the eight webhook alert types.** It
+  was missing `alerts.exclusion.match`, `alerts.dibbs_rfq.match`, and
+  `alerts.dibbs_rfp.match`. No SDK change was needed — event types are served by
+  the API and never hardcoded, so the new types already worked — but the
+  hand-written list had gone stale. Also documents two things that surprise
+  people: DIBBS *awards* are not alertable, and nothing fires when a record
+  merely lapses (an exclusion hitting its termination date, or an RFQ/RFP
+  passing its close date, emits no event). A production smoke test now asserts
+  every live event type appears in the doc, so the list cannot silently fall
+  behind again.
+- **Refreshed the vendored API contract, which had gone stale by seven
+  resources.** It tracked 25 resources against Tango's current 32, so the
+  conformance and coverage checks were validating against out-of-date truth and
+  could not see DIBBS, exclusions, SBIR, or `budget/accounts` at all. Refreshing
+  it also surfaced 72 additional fields on existing resources, now covered.
+  Nested routes are keyed with a slash (`budget/accounts`), which silently broke
+  the old `budget_accounts` mapping — both keys are now accepted.
+- **`check_filter_shape_conformance.py` no longer reports false stale params.**
+  It resolved SDK arguments to API params only through an explicit
+  `api_param_mapping` dict, so methods that express the translation as tuple
+  tables — `("account_title__icontains", account_title)` and
+  `range_filters = (("apportioned", apportioned, apportioned_gte, ...))` — looked
+  like they exposed dozens of params the API rejects. They do not:
+  `list_budget_accounts` correctly sends `apportioned__gte`, `fiscal_year__lte`,
+  and `account_title__icontains`. The checker now understands both tuple forms
+  (in `Assign`, `AnnAssign`, and inline `for` iterables), with an explicit
+  `api_param_mapping` still taking precedence. This let `budget/accounts` be
+  conformance-checked for the first time; its genuinely missing lookup variants
+  (`agency_code__in`, `bureau_name__icontains`, …) are now baselined.
+
 ## [1.2.0] - 2026-06-05
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 1.2.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.2.0 → tango_python-1.4.0}/docs/WEBHOOKS.md

@@ -84,8 +84,25 @@ tango webhooks list-event-types
 # alerts.entity.match        Entity matched a saved alert
 # alerts.grant.match         Grant matched a saved alert
 # alerts.forecast.match      Forecast matched a saved alert
+# alerts.exclusion.match     SAM.gov exclusion matched a saved alert
+# alerts.dibbs_rfq.match     DLA DIBBS RFQ matched a saved alert
+# alerts.dibbs_rfp.match     DLA DIBBS RFP matched a saved alert
 ```
 
+This list is served by the API, so it is always current — the SDK does not hardcode
+event types anywhere. Always trust `list-event-types` over any list written down
+here.
+
+Two things that surprise people:
+
+- **DIBBS awards are not alertable.** There is no `alerts.dibbs_award.match`;
+  only RFQs and RFPs emit alerts.
+- **Nothing fires when a record merely lapses.** An exclusion reaching its
+  termination date, or an RFQ/RFP passing its close date, emits no event.
+  Alerts fire on a record matching your saved search, not on the passage of
+  time. Poll with `list_exclusions(active=...)` / `list_dibbs_rfqs(open=...)`
+  if you need to observe expiry.
+
 ### 2. See what a payload looks like
 
 ```bash

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

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

tango_python-1.4.0/scripts/README.md

@@ -0,0 +1,114 @@
+# Development Scripts
+
+This directory contains utility scripts used during development and maintenance of the tango-python library.
+
+## Scripts
+
+### Schema and API Tools
+
+- **`fetch_api_schema.py`** - Fetches the OpenAPI schema from the Tango API and saves it locally
+- **`generate_schemas_from_api.py`** - Generates schema definitions from the API reference (outputs to stdout)
+
+### Testing and Validation
+
+- **`test_production.py`** - Runs production API smoke tests against the live API
+- **`pr_review.py`** - Runs configurable validation checks for PR review (linting, type checking, tests, conformance)
+- **`check_filter_shape_conformance.py`** - Validates SDK filter and shape conformance (see [Filter and shape conformance](#filter-and-shape-conformance))
+- **`check_shape_coverage.py`** - Reverse shape-coverage gate: fails when Tango's shape trees expose a field/expand the SDK schema doesn't capture and it isn't in `contracts/shape_coverage_baseline.json`. Offline against the vendored contract (no API key; runs on forks)
+- **`generate_shape_overlay.py`** - Regenerates `tango/shapes/generated_overlay.py` (the schema additions that close the coverage gaps) from the vendored contract + `contracts/observed_shape_types.json`. No API key needed; `--report` prints the gaps without writing
+- **`probe_shape_types.py`** - Samples the live API to derive ground-truth shape types (types + list-ness the contract can't express) into `contracts/observed_shape_types.json`. Maintainer-run; requires `TANGO_API_KEY`
+
+## Usage
+
+These scripts are primarily for maintainers and are not part of the public API.
+
+### Production API Testing
+
+Run smoke tests against the production API:
+
+```bash
+# Requires TANGO_API_KEY environment variable
+uv run python scripts/test_production.py
+```
+
+This runs fast smoke tests (~30-60 seconds) that validate core SDK functionality against the live production API.
+
+### PR Review Validation
+
+Run validation checks for PR review. **Automatically detects PR context** from GitHub Actions, GitHub CLI, or git branch.
+
+```bash
+# Auto-detect PR and run validation (default: production mode)
+uv run python scripts/pr_review.py
+
+# Review a specific PR number
+uv run python scripts/pr_review.py --pr-number 123
+
+# Smoke tests only
+uv run python scripts/pr_review.py --mode smoke
+
+# Quick validation (linting + type checking, no tests)
+uv run python scripts/pr_review.py --mode quick
+
+# Full validation (all checks including all tests)
+uv run python scripts/pr_review.py --mode full
+
+# Check only changed files (auto-enabled when PR is detected)
+uv run python scripts/pr_review.py --mode production --changed-files-only
+```
+
+**Validation Modes:**
+- `smoke` - Production API smoke tests only
+- `quick` - Linting + type checking (no tests)
+- `full` - All checks (linting + type checking + filter/shape conformance + all tests)
+- `production` - Linting + type checking + filter/shape conformance + production API smoke tests (default)
+
+Both `full` and `production` run the [filter and shape conformance](#filter-and-shape-conformance) check against the vendored contract (`contracts/filter_shape_contract.json`, overridable via `TANGO_CONTRACT_MANIFEST`). If the contract is missing, that step is skipped with a warning.
+
+**PR Detection:**
+The script automatically detects PR information from:
+- GitHub Actions environment variables (`GITHUB_EVENT_PATH`, `GITHUB_PR_NUMBER`)
+- GitHub CLI (`gh pr view` - requires `gh auth login`)
+- Current git branch
+
+When a PR is detected, the script displays PR information and automatically:
+- Detects the base branch from the PR
+- Checks only changed files
+- Shows PR URL in summary
+
+### Filter and shape conformance
+
+The SDK is validated against the canonical API contract — vendored at
+`contracts/filter_shape_contract.json` and refreshed with
+`scripts/refresh_contract.py` — for **filter conformance**, and against its own
+schemas for **shape conformance**:
+
+1. **Filter coverage** – Every list/get method exposes the filter parameters defined in the contract (explicit argument or `api_param_mapping`). Missing params are errors unless accepted in `contracts/conformance_baseline.json`, where each entry is tracked backlog (remove the entry in the same PR that adds the param). Methods that use `**kwargs` for filters are reported as warnings because their filter names cannot be verified.
+2. **Staleness** – Every filter-like SDK argument resolves to a param the API actually accepts. A stale param silently no-ops for users, so this is always an error.
+3. **Types** – With a `schema_version >= 2` contract, each SDK argument's annotation must be compatible with the contract value type (e.g. a `date` param must be `str`, a `boolean` must be `bool`).
+4. **Shape conformance** – Every `ShapeConfig` constant (e.g. `CONTRACTS_MINIMAL`, `IDVS_MINIMAL`) parses correctly and only references fields that exist in the SDK’s explicit schemas for that model. Invalid or unknown fields in default shapes are reported as errors.
+
+This script runs in CI on every push/PR (see [Lint workflow](.github/workflows/lint.yml)) against the vendored contract — no secrets or sibling checkout needed.
+
+```bash
+# Full check (filter + shape) against the vendored contract.
+uv run python scripts/check_filter_shape_conformance.py
+
+# Ready-to-paste typed parameter scaffolds for any missing filters
+uv run python scripts/check_filter_shape_conformance.py --suggest
+
+# List resources that have no matching SDK method (for implementation checklist)
+uv run python scripts/check_filter_shape_conformance.py --list-unmapped
+
+# Refresh the vendored contract (sibling ../tango checkout, or GitHub via gh)
+uv run python scripts/refresh_contract.py
+```
+
+**Output:** JSON with `manifest`, `errors`, and `warnings`. Exit code 1 if there are any errors (missing or stale filters, type mismatches, invalid shapes, or missing SDK methods for manifest resources).
+
+**Local runs:** The vendored contract makes the full check work out of the box. To check against a different contract (e.g. an unreleased tango branch), pass `--manifest /path/to/filter_shape_contract.json` or set `TANGO_CONTRACT_MANIFEST` (honored by `pr_review.py`).
+
+## Requirements
+
+- `TANGO_API_KEY` environment variable (required for production API tests)
+- All dependencies installed: `uv sync --all-extras`