tango-python 1.17.0__tar.gz → 1.18.1__tar.gz

{tango_python-1.17.0 → tango_python-1.18.1}/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.18.1] - 2026-10-19
+
+### Fixed
+
+- **API errors now carry the server's reason.** A 403 or other non-2xx response the SDK had no dedicated exception for raised `TangoAPIError("API request failed with status 403")` and threw the response body away, so a caller refused for a G2X-only shape field or a plan-gated filter couldn't tell why. The message now ends with the API's own explanation (`API request failed with status 403: G2X shape fields are not allowed for your account.`), and the parsed body is on `response_data`. Non-JSON bodies, such as a proxy's 502 page, keep the old message.
+
+## [1.18.0] - 2026-10-19
+
+### Added
+
+- **`obligations_by_fiscal_year(fiscal_year, obligated)` shape expand on contracts, IDVs, OTAs and OTIDVs** (Tango API 5.11.0). Returns the award's obligations per federal fiscal year, each rounded to cents, with `fiscal_year` parsed as `int` and `obligated` as `Decimal`. It is always `None` on IDVs and OTIDVs, whose transactions report a running lifetime total.
+- **`attachments(extraction_status)` shape field on opportunities and notices** (Tango API 5.11.0). Reports `pending`, `extracting`, `completed`, `failed` or `unsupported` for each attachment, so you can tell why `extracted_text` is missing.
+
+### Changed
+
+- Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.11.0) and regenerated the shape overlay.
+- Documented that `recipient_uei` on `list_contracts()` (and `uei` on the IDV, OTA and OTIDV lists) accepts several UEIs joined by `|` (Tango API 5.11.0); the SDK already passed the value through unchanged.
+
 ## [1.17.0] - 2026-10-16
 
 ### Added

{tango_python-1.17.0 → tango_python-1.18.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tango-python
-Version: 1.17.0
+Version: 1.18.1
 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.17.0 → tango_python-1.18.1}/docs/API_REFERENCE.md

@@ -285,7 +285,7 @@ contracts = client.list_contracts(
 - `awarding_agency` - Agency code (e.g., "4700" for GSA)
 - `funding_agency` - Funding agency code
 - `recipient_name` - Vendor/recipient name (mapped to 'recipient' API param)
-- `recipient_uei` - Vendor UEI (mapped to 'uei' API param)
+- `recipient_uei` - Vendor UEI (mapped to 'uei' API param). Several UEIs joined by `|` match awards to any of them, up to 500 (Tango API 5.11.0).
 
 **Classification:**
 - `naics_code` - NAICS industry code (mapped to 'naics' API param)
@@ -381,6 +381,22 @@ contracts = client.list_contracts(
 - `psc` - Product/service code (nested)
 - `place_of_performance` - Location (nested)
 
+**Obligations by fiscal year — `obligations_by_fiscal_year(fiscal_year, obligated)`** (Tango API 5.11.0):
+
+```python
+contracts = client.list_contracts(
+    shape="key,piid,obligated,obligations_by_fiscal_year(fiscal_year,obligated)",
+    piid="SOME_PIID",
+)
+for year in contracts.results[0]["obligations_by_fiscal_year"] or []:
+    print(year["fiscal_year"], year["obligated"])  # int, Decimal
+```
+
+- Sums the award's transactions per federal fiscal year (October 1 starts the next fiscal year), oldest year first, each rounded to cents. A de-obligation nets against its own year, so a year can be zero or negative.
+- Returned only when named: no default shape includes it.
+- The same expand works on `list_otas()`, `list_idvs()`, `list_otidvs()` and the `get_*` methods. On IDVs and OTIDVs it is always `None`, because their transactions report a running lifetime total rather than each action's obligation.
+- `None` on a contract or OTA with no dated transactions.
+
 ---
 
 ## OTAs

{tango_python-1.17.0 → tango_python-1.18.1}/pyproject.toml

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

{tango_python-1.17.0 → tango_python-1.18.1}/tango/__init__.py

@@ -62,7 +62,7 @@ from .webhooks import (
 )
 from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "1.17.0"
+__version__ = "1.18.1"
 __all__ = [
     "TangoClient",
     "TangoAPIError",

{tango_python-1.17.0 → tango_python-1.18.1}/tango/client.py

@@ -75,6 +75,31 @@ from tango.shapes import (
 _COUNT_TYPE_KEY = "_tango_count_type"
 
 
+def _error_body(response: httpx.Response) -> dict[str, Any]:
+    """The JSON object an error response carries, or {} for an empty, non-JSON (a proxy's HTML page) or non-object body."""
+    try:
+        data = response.json() if response.content else {}
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _error_reason(error_data: dict[str, Any]) -> str | None:
+    """The server's own explanation from an error body, e.g. why a 403 refused the request.
+
+    The API sends either ``{"detail": "..."}`` or a structured body such as a tier gate's ``{"error": "...", "code": "tier_required", ...}``, sometimes nested under ``detail``.
+    """
+    for body in (error_data, error_data.get("detail")):
+        if isinstance(body, str) and body:
+            return body
+        if isinstance(body, dict):
+            for key in ("error", "message", "detail"):
+                value = body.get(key)
+                if isinstance(value, str) and value:
+                    return value
+    return None
+
+
 class TangoClient:
     """Tango API Client"""
 
@@ -232,8 +257,13 @@ class TangoClient:
             detail = error_data.get("detail", "Rate limit exceeded")
             raise TangoRateLimitError(detail, response.status_code, error_data)
         elif not response.is_success:
+            error_data = _error_body(response)
+            reason = _error_reason(error_data)
+            message = f"API request failed with status {response.status_code}"
             raise TangoAPIError(
-                f"API request failed with status {response.status_code}", response.status_code
+                f"{message}: {reason}" if reason else message,
+                response.status_code,
+                error_data,
             )
 
     def _get(self, endpoint: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
@@ -695,7 +725,7 @@ class TangoClient:
             naics_code: NAICS code (mapped to 'naics' API param)
             psc_code: PSC code (mapped to 'psc' API param)
             recipient_name: Vendor/recipient name (mapped to 'recipient' API param)
-            recipient_uei: Vendor UEI (mapped to 'uei' API param)
+            recipient_uei: Vendor UEI (mapped to 'uei' API param); join several with `|` for OR, up to 500
             set_aside_type: Set-aside type (mapped to 'set_aside' API param)
             sort: Field to sort by (combined with 'order' to produce 'ordering')
             order: Sort order ('asc' or 'desc', default 'asc')

{tango_python-1.17.0 → tango_python-1.18.1}/tango/models.py

@@ -281,6 +281,17 @@ class AwardTransaction:
     obligated: Decimal | None = None
 
 
+@dataclass
+class FiscalYearObligation:
+    """Schema definition for FiscalYearObligation (not used for instances).
+
+    One entry of an award's ``obligations_by_fiscal_year``: the obligations dated in one federal fiscal year, rounded to cents.
+    """
+
+    fiscal_year: int
+    obligated: Decimal
+
+
 @dataclass
 class OrganizationOfficePayload:
     """Schema definition for OrganizationOfficePayload (not used for instances).

{tango_python-1.17.0 → tango_python-1.18.1}/tango/shapes/explicit_schemas.py

@@ -197,6 +197,12 @@ TRANSACTION_SCHEMA: dict[str, FieldSchema] = {
 }
 
 
+FISCAL_YEAR_OBLIGATION_SCHEMA: dict[str, FieldSchema] = {
+    "fiscal_year": FieldSchema(name="fiscal_year", type=int, is_optional=False, is_list=False),
+    "obligated": FieldSchema(name="obligated", type=Decimal, is_optional=False, is_list=False),
+}
+
+
 DEPARTMENT_SCHEMA: dict[str, FieldSchema] = {
     "abbreviation": FieldSchema(name="abbreviation", type=str, is_optional=True, is_list=False),
     "code": FieldSchema(name="code", type=int, is_optional=True, is_list=False),
@@ -432,6 +438,13 @@ CONTRACT_SCHEMA: dict[str, FieldSchema] = {
         is_list=False,
         nested_model="Vehicle",
     ),
+    "obligations_by_fiscal_year": FieldSchema(
+        name="obligations_by_fiscal_year",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="FiscalYearObligation",
+    ),
 }
 
 
@@ -1290,6 +1303,13 @@ IDV_SCHEMA: dict[str, FieldSchema] = {
     "idv_contracts_value": FieldSchema(
         name="idv_contracts_value", type=Decimal, is_optional=True, is_list=False
     ),
+    "obligations_by_fiscal_year": FieldSchema(
+        name="obligations_by_fiscal_year",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="FiscalYearObligation",
+    ),
 }
 
 
@@ -1439,6 +1459,13 @@ OTA_SCHEMA: dict[str, FieldSchema] = {
         is_list=False,
         nested_model="RecipientProfile",
     ),
+    "obligations_by_fiscal_year": FieldSchema(
+        name="obligations_by_fiscal_year",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="FiscalYearObligation",
+    ),
 }
 
 # OTIDV (Other Transaction IDV) - IDV-like
@@ -1459,6 +1486,13 @@ OTIDV_SCHEMA: dict[str, FieldSchema] = {
         is_list=False,
         nested_model="RecipientProfile",
     ),
+    "obligations_by_fiscal_year": FieldSchema(
+        name="obligations_by_fiscal_year",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="FiscalYearObligation",
+    ),
 }
 
 # Subaward (prime/sub awards)
@@ -1707,6 +1741,7 @@ EXPLICIT_SCHEMAS: dict[str, dict[str, FieldSchema]] = {
     "LegislativeMandates": LEGISLATIVE_MANDATES_SCHEMA,
     "SubawardsSummary": SUBAWARDS_SUMMARY_SCHEMA,
     "Transaction": TRANSACTION_SCHEMA,
+    "FiscalYearObligation": FISCAL_YEAR_OBLIGATION_SCHEMA,
     "Department": DEPARTMENT_SCHEMA,
     "Contact": CONTACT_SCHEMA,
     "RecipientProfile": RECIPIENT_PROFILE_SCHEMA,

{tango_python-1.17.0 → tango_python-1.18.1}/tango/shapes/generated_overlay.py

@@ -85,6 +85,9 @@ ATTACHMENTS_SCHEMA: dict[str, FieldSchema] = {
     "doc_role": FieldSchema(name="doc_role", type=str, is_optional=True, is_list=False),
     "doc_role_alt": FieldSchema(name="doc_role_alt", type=str, is_optional=True, is_list=False),
     "extracted_text": FieldSchema(name="extracted_text", type=str, is_optional=True, is_list=False),
+    "extraction_status": FieldSchema(
+        name="extraction_status", type=str, is_optional=True, is_list=False
+    ),
     "file_size": FieldSchema(name="file_size", type=int, is_optional=True, is_list=False),
     "mime_type": FieldSchema(name="mime_type", type=str, is_optional=True, is_list=False),
     "name": FieldSchema(name="name", type=str, is_optional=True, is_list=False),
@@ -99,6 +102,9 @@ ATTACHMENTS2_SCHEMA: dict[str, FieldSchema] = {
     "doc_role": FieldSchema(name="doc_role", type=str, is_optional=True, is_list=False),
     "doc_role_alt": FieldSchema(name="doc_role_alt", type=str, is_optional=True, is_list=False),
     "extracted_text": FieldSchema(name="extracted_text", type=str, is_optional=True, is_list=False),
+    "extraction_status": FieldSchema(
+        name="extraction_status", type=str, is_optional=True, is_list=False
+    ),
     "file_size": FieldSchema(name="file_size", type=int, is_optional=True, is_list=False),
     "mime_type": FieldSchema(name="mime_type", type=str, is_optional=True, is_list=False),
     "name": FieldSchema(name="name", type=str, is_optional=True, is_list=False),
@@ -135,6 +141,9 @@ ATTACHMENTS3_SCHEMA: dict[str, FieldSchema] = {
 
 ATTACHMENTS4_SCHEMA: dict[str, FieldSchema] = {
     "attachment_id": FieldSchema(name="attachment_id", type=str, is_optional=True, is_list=False),
+    "extraction_status": FieldSchema(
+        name="extraction_status", type=str, is_optional=True, is_list=False
+    ),
     "file_size": FieldSchema(name="file_size", type=str, is_optional=True, is_list=False),
     "mime_type": FieldSchema(name="mime_type", type=str, is_optional=True, is_list=False),
     "name": FieldSchema(name="name", type=str, is_optional=True, is_list=False),
@@ -149,6 +158,9 @@ ATTACHMENTS5_SCHEMA: dict[str, FieldSchema] = {
     "doc_role": FieldSchema(name="doc_role", type=str, is_optional=True, is_list=False),
     "doc_role_alt": FieldSchema(name="doc_role_alt", type=str, is_optional=True, is_list=False),
     "extracted_text": FieldSchema(name="extracted_text", type=str, is_optional=True, is_list=False),
+    "extraction_status": FieldSchema(
+        name="extraction_status", type=str, is_optional=True, is_list=False
+    ),
     "file_size": FieldSchema(name="file_size", type=str, is_optional=True, is_list=False),
     "mime_type": FieldSchema(name="mime_type", type=str, is_optional=True, is_list=False),
     "name": FieldSchema(name="name", type=str, is_optional=True, is_list=False),
@@ -758,6 +770,11 @@ NOTICE_TYPE_SCHEMA: dict[str, FieldSchema] = {
     "type": FieldSchema(name="type", type=str, is_optional=True, is_list=False),
 }
 
+OBLIGATIONS_BY_FISCAL_YEAR_SCHEMA: dict[str, FieldSchema] = {
+    "fiscal_year": FieldSchema(name="fiscal_year", type=str, is_optional=True, is_list=False),
+    "obligated": FieldSchema(name="obligated", type=str, is_optional=True, is_list=False),
+}
+
 OFFICERS_SCHEMA: dict[str, FieldSchema] = {
     "highly_compensated_officer_1_amount": FieldSchema(
         name="highly_compensated_officer_1_amount", type=Decimal, is_optional=True, is_list=False
@@ -1161,6 +1178,7 @@ GENERATED_NESTED: dict[str, dict[str, FieldSchema]] = {
     "NoticeHistory": NOTICE_HISTORY_SCHEMA,
     "NoticeHistory2": NOTICE_HISTORY2_SCHEMA,
     "NoticeType": NOTICE_TYPE_SCHEMA,
+    "ObligationsByFiscalYear": OBLIGATIONS_BY_FISCAL_YEAR_SCHEMA,
     "Officers": OFFICERS_SCHEMA,
     "Opportunity": OPPORTUNITY_SCHEMA,
     "Opportunity2": OPPORTUNITY2_SCHEMA,

{tango_python-1.17.0 → tango_python-1.18.1}/tests/test_client.py

@@ -1572,6 +1572,63 @@ class TestErrorHandling:
         assert exc_info.value.status_code == 500
         assert "500" in str(exc_info.value)
 
+    @staticmethod
+    def _error_response(status, body=None, content=b"{}"):
+        response = Mock()
+        response.is_success = False
+        response.status_code = status
+        response.content = content
+        response.json.return_value = body
+        return response
+
+    @patch("tango.client.httpx.Client.request")
+    def test_403_carries_the_server_reason(self, mock_request):
+        body = {"detail": "G2X shape fields are not allowed for your account."}
+        mock_request.return_value = self._error_response(403, body)
+
+        with pytest.raises(TangoAPIError) as exc_info:
+            TangoClient(api_key="test-key").list_agencies()
+
+        assert (
+            str(exc_info.value)
+            == "API request failed with status 403: G2X shape fields are not allowed for your account."
+        )
+        assert exc_info.value.status_code == 403
+        assert exc_info.value.response_data == body
+
+    @pytest.mark.parametrize(
+        "body",
+        [
+            {"error": "The 'psc' filter requires a Small plan or higher.", "code": "tier_required"},
+            {
+                "detail": {
+                    "error": "The 'psc' filter requires a Small plan or higher.",
+                    "code": "tier_required",
+                }
+            },
+        ],
+    )
+    @patch("tango.client.httpx.Client.request")
+    def test_403_tier_gate_reason_flat_or_nested(self, mock_request, body):
+        mock_request.return_value = self._error_response(403, body)
+
+        with pytest.raises(
+            TangoAPIError, match=r"status 403: The 'psc' filter requires a Small plan"
+        ):
+            TangoClient(api_key="test-key").list_agencies()
+
+    @patch("tango.client.httpx.Client.request")
+    def test_non_json_error_body_keeps_the_bare_message(self, mock_request):
+        response = self._error_response(502, content=b"<html>Bad Gateway</html>")
+        response.json.side_effect = ValueError("not JSON")
+        mock_request.return_value = response
+
+        with pytest.raises(TangoAPIError) as exc_info:
+            TangoClient(api_key="test-key").list_agencies()
+
+        assert str(exc_info.value) == "API request failed with status 502"
+        assert exc_info.value.response_data == {}
+
     @patch("tango.client.httpx.Client.request")
     def test_network_error(self, mock_request):
         """Test network errors raise TangoAPIError"""

tango_python-1.18.1/tests/test_obligations_by_fiscal_year.py

@@ -0,0 +1,88 @@
+"""The `obligations_by_fiscal_year(...)` expand on contracts, IDVs, OTAs and OT IDVs."""
+
+from decimal import Decimal
+from unittest.mock import Mock, patch
+
+import pytest
+
+from tango import TangoClient
+from tango.models import IDV, OTA, OTIDV, Contract, Notice, Opportunity
+from tango.shapes.parser import ShapeParser
+
+SHAPE = "key,obligations_by_fiscal_year(fiscal_year,obligated)"
+
+
+def _mock(mock_request, payload):
+    response = Mock()
+    response.is_success = True
+    response.json.return_value = payload
+    response.content = b"{}"
+    mock_request.return_value = response
+
+
+def _page(rows):
+    return {"count": len(rows), "next": None, "previous": None, "results": rows}
+
+
+class TestObligationsByFiscalYearShape:
+    @pytest.mark.parametrize("model", [Contract, IDV, OTA, OTIDV])
+    @pytest.mark.parametrize(
+        "shape",
+        [
+            SHAPE,
+            "key,obligations_by_fiscal_year(*)",
+            "key,obligations_by_fiscal_year",
+        ],
+    )
+    def test_shape_validates(self, model, shape):
+        parser = ShapeParser(cache_enabled=False)
+        parser.validate(parser.parse(shape), model)
+
+    @pytest.mark.parametrize("model", [Contract, OTA])
+    def test_unknown_sub_field_is_rejected(self, model):
+        parser = ShapeParser(cache_enabled=False)
+        with pytest.raises(Exception, match="amount"):
+            parser.validate(parser.parse("key,obligations_by_fiscal_year(amount)"), model)
+
+
+class TestObligationsByFiscalYearResponses:
+    @pytest.mark.parametrize("method", ["list_contracts", "list_otas"])
+    @patch("tango.client.httpx.Client.request")
+    def test_list_parses_each_year(self, mock_request, method):
+        _mock(
+            mock_request,
+            _page(
+                [
+                    {
+                        "key": "K1",
+                        "obligations_by_fiscal_year": [
+                            {"fiscal_year": 2023, "obligated": 1000.0},
+                            {"fiscal_year": 2024, "obligated": -250.5},
+                        ],
+                    }
+                ]
+            ),
+        )
+
+        (row,) = getattr(TangoClient(api_key="k"), method)(shape=SHAPE).results
+
+        years = row["obligations_by_fiscal_year"]
+        assert [y["fiscal_year"] for y in years] == [2023, 2024]
+        assert [y["obligated"] for y in years] == [Decimal("1000.0"), Decimal("-250.5")]
+        assert all(isinstance(y["obligated"], Decimal) for y in years)
+
+    @pytest.mark.parametrize("method", ["list_idvs", "list_otidvs"])
+    @patch("tango.client.httpx.Client.request")
+    def test_cumulative_award_types_return_none(self, mock_request, method):
+        _mock(mock_request, _page([{"key": "K1", "obligations_by_fiscal_year": None}]))
+
+        (row,) = getattr(TangoClient(api_key="k"), method)(shape=SHAPE).results
+
+        assert row["obligations_by_fiscal_year"] is None
+
+
+class TestAttachmentExtractionStatusShape:
+    @pytest.mark.parametrize("model", [Opportunity, Notice])
+    def test_shape_validates(self, model):
+        parser = ShapeParser(cache_enabled=False)
+        parser.validate(parser.parse("title,attachments(name,extraction_status)"), model)