tango-python 1.14.0__tar.gz → 1.15.0__tar.gz

{tango_python-1.14.0 → tango_python-1.15.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.15.0] - 2026-10-06
+
+### Added
+
+- **`matched_by` on agency-filter diagnostics** (Tango API 5.9.0). Each entry of `PaginatedResponse.meta["resolved_filters"][<filter name>]` that resolved now says how its token matched: `key` (an organization UUID), `code` (a 3-digit CGAC or 4-digit FPDS code), `name` (the organization's name, including a department's everyday name, a spelling variant or a rename), `alias` (an abbreviation or the organization's own alias) or `fuzzy` (a looser text match, worth checking against the resolved name). An entry that did not resolve has no `matched_by`. `meta` is passed through as the API sends it, so no code change was needed to receive the field; this release documents it and pins it with a test. `agency_warnings`, `unresolved_agency_tokens` and `resolved_agencies` are unchanged.
+- **File and link counts on opportunities and notices** (Tango API 5.9.0). An attachment's `type` is `file` (a document attached to the notice; only files have extracted text) or `link` (a URL the notice lists), and the new fields count each: `meta.files_count` and `meta.links_count` on opportunities, `file_count` and `link_count` on notices. The existing `meta.attachments_count` and `attachment_count` still count every attachment, links included, and an attachment of any other type counts only there, so files plus links need not equal the total. The new fields are `None` until a record has been counted, so treat `None` as unknown, not zero. All four are accepted in custom shapes, as is `opportunity(meta(files_count,links_count))` on vehicles; no default SDK shape names them.
+
+### Changed
+
+- Re-vendored `contracts/filter_shape_contract.json` (Tango API 5.9.0) and regenerated `tango/shapes/generated_overlay.py`.
+
 ## [1.14.0] - 2026-10-02
 
 ### Added

{tango_python-1.14.0 → tango_python-1.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tango-python
-Version: 1.14.0
+Version: 1.15.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
@@ -219,6 +219,15 @@ for warning in response.agency_warnings:
     print(warning)
 ```
 
+Each entry of `response.meta["resolved_filters"][<filter name>]` that resolved also says how its token matched, in `matched_by` (Tango API 5.9.0+): `key` (an organization UUID), `code` (a 3-digit CGAC or 4-digit FPDS code), `name` (the organization's name, including a department's everyday name, a spelling variant or a rename), `alias` (an abbreviation or the organization's own alias) or `fuzzy` (a looser text match).
+A `fuzzy` match is the one worth checking against the resolved name:
+
+```python
+for entry in response.meta["resolved_filters"].get("awarding_agency", []):
+    if entry.get("matched_by") == "fuzzy":
+        print(f"{entry['token']!r} loosely matched {entry['resolved']['name']}")
+```
+
 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.
 

{tango_python-1.14.0 → tango_python-1.15.0}/README.md

@@ -165,6 +165,15 @@ for warning in response.agency_warnings:
     print(warning)
 ```
 
+Each entry of `response.meta["resolved_filters"][<filter name>]` that resolved also says how its token matched, in `matched_by` (Tango API 5.9.0+): `key` (an organization UUID), `code` (a 3-digit CGAC or 4-digit FPDS code), `name` (the organization's name, including a department's everyday name, a spelling variant or a rename), `alias` (an abbreviation or the organization's own alias) or `fuzzy` (a looser text match).
+A `fuzzy` match is the one worth checking against the resolved name:
+
+```python
+for entry in response.meta["resolved_filters"].get("awarding_agency", []):
+    if entry.get("matched_by") == "fuzzy":
+        print(f"{entry['token']!r} loosely matched {entry['resolved']['name']}")
+```
+
 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.
 

{tango_python-1.14.0 → tango_python-1.15.0}/docs/API_REFERENCE.md

@@ -981,6 +981,27 @@ awarded = client.list_opportunities(
 - The `awarded` and `awardee_uei` filters search every opportunity, not just active ones, so pass `active=True` to narrow to open opportunities.
 - Notices accept `award_date`, `award_amount`, `awardee` and `awardee_uei` in `shape` too.
 
+**Attachment counts — `meta(attachments_count, files_count, links_count)`:**
+
+Tango API 5.9.0 splits an opportunity's attachment count by attachment `type`.
+A `file` is a document attached to the notice, and only files have extracted text; a `link` is a URL the notice lists.
+
+```python
+opp = client.get_opportunity(
+    opportunity_id,
+    shape="opportunity_id,title,meta(attachments_count,files_count,links_count)",
+)
+files = opp["meta"]["files_count"]
+if files is None:
+    print("not counted yet")
+```
+
+- `meta.files_count` counts the files and `meta.links_count` counts the links.
+- `meta.attachments_count` still counts every attachment, links included. An attachment of any other type counts only there, so `files_count + links_count` need not equal it.
+- **`None` means unknown, not zero.** Both new fields are null until the record has been counted.
+- None of the three is in the SDK's default shape, so name the ones you want.
+- The opportunity embedded in a vehicle accepts them too: `opportunity(meta(files_count,links_count))`.
+
 ---
 
 ## Notices
@@ -1053,6 +1074,23 @@ for notice in notices.results:
 - `posted_date` - Date posted
 - `naics_code` - Industry code
 
+**Attachment counts — `attachment_count`, `file_count`, `link_count`:**
+
+Tango API 5.9.0 splits a notice's attachment count by attachment `type`.
+A `file` is a document attached to the notice, and only files have extracted text; a `link` is a URL the notice lists.
+
+```python
+notices = client.list_notices(
+    agency="GSA",
+    shape="notice_id,title,attachment_count,file_count,link_count",
+)
+```
+
+- `file_count` counts the files and `link_count` counts the links.
+- `attachment_count` still counts every attachment, links included. An attachment of any other type counts only there, so `file_count + link_count` need not equal it.
+- **`None` means unknown, not zero.** Both new fields are null until the notice has been counted.
+- The API returns all three when no `shape` is sent, but the SDK's default `NOTICES_MINIMAL` shape does not name them, so ask for them.
+
 ---
 
 ## Grants

{tango_python-1.14.0 → tango_python-1.15.0}/pyproject.toml

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

{tango_python-1.14.0 → tango_python-1.15.0}/tango/__init__.py

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

{tango_python-1.14.0 → tango_python-1.15.0}/tango/models.py

@@ -571,6 +571,12 @@ class Opportunity:
     The award fields (``award_date``, ``award_amount``, ``awardee``, ``awardee_uei``) are filled only where SAM.gov posted an award notice, and ``award_amount`` is the text SAM.gov published, not a number.
     SAM.gov often posts an award as its own opportunity; when that award notice references its solicitation, ``solicitation_opportunity_id`` points back to it, and the solicitation's ``awards(...)`` expand lists up to ten of the most recent linked awards, with ``award_count`` giving the full count.
     An award notice that does not reference its solicitation is not linked.
+
+    The ``meta(...)`` expand counts an opportunity's attachments three ways (Tango API 5.9.0).
+    An attachment's ``type`` is ``file`` (a document attached to the notice; only files have extracted text) or ``link`` (a URL the notice lists).
+    ``meta.files_count`` and ``meta.links_count`` count each, and ``meta.attachments_count`` counts every attachment, links included.
+    An attachment of any other type counts only in the total, so files plus links need not equal it.
+    ``files_count`` and ``links_count`` are null until the record has been counted, so treat null as unknown, not zero.
     """
 
     opportunity_id: str
@@ -600,6 +606,10 @@ class Notice:
     Both must be named, e.g. ``attachments(name,url,doc_role,doc_role_alt)``, because ``attachments(*)`` does not include them.
     An attachment Tango has not classified omits both keys rather than returning null, so read them with ``.get()``.
     A Free-plan request that names them gets the response without them, plus an entry in ``meta.upgrade_hints``.
+
+    ``file_count`` and ``link_count`` (Tango API 5.9.0) split ``attachment_count`` by attachment ``type``: ``file`` is a document attached to the notice (only files have extracted text) and ``link`` is a URL the notice lists.
+    ``attachment_count`` still counts every attachment, links included, and an attachment of any other type counts only there, so files plus links need not equal it.
+    ``file_count`` and ``link_count`` are null until the notice has been counted, so treat null as unknown, not zero.
     """
 
     notice_id: str
@@ -613,6 +623,9 @@ class Notice:
     award_amount: str | None = None
     awardee: str | None = None
     awardee_uei: str | None = None
+    attachment_count: int | None = None
+    file_count: int | None = None
+    link_count: int | None = None
 
 
 @dataclass
@@ -1454,11 +1467,10 @@ class PaginatedResponse[T]:
         results: List of result items (type depends on shape parameter)
         cursor: Cursor token for cursor-based pagination (None if not available)
         meta: Response-level metadata the API attached to this page, when present.
-            Currently carries agency-filter diagnostics: ``resolved_filters`` maps
-            each agency filter to the organizations its ``|``-separated tokens
-            resolved to (or ``None``), and ``warnings`` lists human-readable notes
-            about tokens that were dropped or matched loosely. See
-            :meth:`agency_warnings` and :meth:`unresolved_agency_tokens`.
+            Currently carries agency-filter diagnostics: ``resolved_filters`` maps each agency filter to the organizations its ``|``-separated tokens resolved to (or ``None``), and ``warnings`` lists human-readable notes about tokens that were dropped or matched loosely.
+            Each ``resolved_filters`` entry that resolved also carries ``matched_by`` (Tango API 5.9.0+), saying how the token matched: ``"key"`` (an organization UUID), ``"code"`` (a 3-digit CGAC or 4-digit FPDS code), ``"name"`` (the organization's name, including a department's everyday name, a spelling variant or a rename), ``"alias"`` (an abbreviation or the organization's own alias) or ``"fuzzy"`` (a looser text match, worth checking against the resolved ``name``).
+            An entry that did not resolve has no ``matched_by``.
+            See :meth:`agency_warnings`, :meth:`unresolved_agency_tokens` and :meth:`resolved_agencies`.
         page_metadata: Always ``None`` — the API has never emitted a
             ``page_metadata`` key. Retained so existing attribute access keeps
             working; use ``meta`` instead.

{tango_python-1.14.0 → tango_python-1.15.0}/tango/shapes/generated_overlay.py

@@ -641,6 +641,8 @@ META2_SCHEMA: dict[str, FieldSchema] = {
     "attachments_count": FieldSchema(
         name="attachments_count", type=int, is_optional=True, is_list=False
     ),
+    "files_count": FieldSchema(name="files_count", type=int, is_optional=True, is_list=False),
+    "links_count": FieldSchema(name="links_count", type=int, is_optional=True, is_list=False),
     "notice_type": FieldSchema(
         name="notice_type", type=dict, is_optional=True, is_list=False, nested_model="NoticeType"
     ),
@@ -2252,6 +2254,8 @@ GENERATED_OVERLAY: dict[str, dict[str, FieldSchema]] = {
         "award_date": FieldSchema(name="award_date", type=date, is_optional=True, is_list=False),
         "awardee": FieldSchema(name="awardee", type=str, is_optional=True, is_list=False),
         "awardee_uei": FieldSchema(name="awardee_uei", type=str, is_optional=True, is_list=False),
+        "file_count": FieldSchema(name="file_count", type=int, is_optional=True, is_list=False),
+        "link_count": FieldSchema(name="link_count", type=int, is_optional=True, is_list=False),
         "meta": FieldSchema(
             name="meta", type=dict, is_optional=True, is_list=False, nested_model="Meta"
         ),

{tango_python-1.14.0 → tango_python-1.15.0}/tests/test_client.py

@@ -2292,6 +2292,22 @@ class TestAgencyFilterDiagnostics:
 
         assert response.meta == meta
 
+    @patch("tango.client.httpx.Client.request")
+    def test_matched_by_reaches_the_caller_and_leaves_the_accessors_unchanged(self, mock_request):
+        entries = [
+            {"token": "HUD", "matched_by": "alias", "resolved": self.HUD},
+            {"token": "Housing and Urban Developmnt", "matched_by": "fuzzy", "resolved": self.HUD},
+            {"token": "HUDD", "resolved": None},
+        ]
+        client = self._mock(mock_request, {"resolved_filters": {"awarding_agency": entries}})
+
+        response = client.list_contracts(awarding_agency="HUD|Housing and Urban Developmnt|HUDD")
+
+        returned = response.meta["resolved_filters"]["awarding_agency"]
+        assert [entry.get("matched_by") for entry in returned] == ["alias", "fuzzy", None]
+        assert response.unresolved_agency_tokens == {"awarding_agency": ["HUDD"]}
+        assert response.resolved_agencies == {"awarding_agency": [self.HUD, self.HUD]}
+
     @patch("tango.client.httpx.Client.request")
     def test_dropped_tokens_are_reported_per_filter(self, mock_request):
         client = self._mock(

tango_python-1.15.0/tests/test_opportunity_attachments.py

@@ -0,0 +1,166 @@
+"""The `attachments(...)` expand on opportunities and notices, including the Pro-plan document-role fields, and the attachment, file and link counts."""
+
+from unittest.mock import Mock, patch
+
+import pytest
+
+from tango import TangoClient
+from tango.models import Notice, Opportunity, Vehicle
+from tango.shapes import SchemaRegistry
+from tango.shapes.parser import ShapeParser
+
+ROLE_SHAPE = "title,attachments(name,doc_role,doc_role_alt)"
+OPPORTUNITY_COUNT_SHAPE = "opportunity_id,meta(attachments_count,files_count,links_count)"
+NOTICE_COUNT_SHAPE = "notice_id,attachment_count,file_count,link_count"
+
+
+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 _attachments():
+    return [
+        {"name": "sow.pdf", "doc_role": "requirement", "doc_role_alt": None},
+        {"name": "pricing.xlsx", "doc_role": "pricing", "doc_role_alt": "terms"},
+        {"name": "unclassified.docx"},
+    ]
+
+
+class TestAttachmentShapes:
+    @pytest.mark.parametrize("model", [Opportunity, Notice])
+    @pytest.mark.parametrize(
+        "shape",
+        [
+            ROLE_SHAPE,
+            "title,attachments(name,url,extracted_text)",
+            "title,attachments(*)",
+        ],
+    )
+    def test_attachment_shape_validates(self, model, shape):
+        parser = ShapeParser(cache_enabled=False)
+        parser.validate(parser.parse(shape), model)
+
+
+class TestAttachmentRoles:
+    @pytest.mark.parametrize("method", ["get_opportunity", "get_notice"])
+    @patch("tango.client.httpx.Client.request")
+    def test_detail_returns_document_roles(self, mock_request, method):
+        _mock(mock_request, {"title": "Base ops support", "attachments": _attachments()})
+        row = getattr(TangoClient(api_key="k"), method)("abc", shape=ROLE_SHAPE)
+        assert [a.get("doc_role") for a in row["attachments"]] == ["requirement", "pricing", None]
+        assert row["attachments"][1]["doc_role_alt"] == "terms"
+
+    @pytest.mark.parametrize("method", ["list_opportunities", "list_notices"])
+    @patch("tango.client.httpx.Client.request")
+    def test_list_returns_document_roles(self, mock_request, method):
+        _mock(
+            mock_request,
+            {
+                "count": 1,
+                "next": None,
+                "previous": None,
+                "results": [{"title": "Amendment 1", "attachments": _attachments()}],
+            },
+        )
+        page = getattr(TangoClient(api_key="k"), method)(shape=ROLE_SHAPE)
+        assert mock_request.call_args.kwargs["params"]["shape"] == ROLE_SHAPE
+        assert [a.get("doc_role") for a in page.results[0]["attachments"]] == [
+            "requirement",
+            "pricing",
+            None,
+        ]
+
+
+class TestAttachmentCountShapes:
+    @pytest.mark.parametrize(
+        ("shape", "model"),
+        [
+            (OPPORTUNITY_COUNT_SHAPE, Opportunity),
+            (NOTICE_COUNT_SHAPE, Notice),
+            ("uuid,opportunity(opportunity_id,meta(files_count,links_count))", Vehicle),
+        ],
+    )
+    def test_count_shape_validates(self, shape, model):
+        parser = ShapeParser(cache_enabled=False)
+        parser.validate(parser.parse(shape), model)
+
+    @pytest.mark.parametrize(
+        ("model", "path"),
+        [
+            (Opportunity, ("meta", "files_count")),
+            (Opportunity, ("meta", "links_count")),
+            (Notice, ("file_count",)),
+            (Notice, ("link_count",)),
+        ],
+    )
+    def test_count_is_typed_as_nullable_int(self, model, path):
+        registry = SchemaRegistry()
+        schema = registry.get_schema(model)
+        for name in path[:-1]:
+            schema = registry.get_schema(schema[name].nested_model)
+        field = schema[path[-1]]
+        assert (field.type, field.is_optional, field.is_list) == (int, True, False)
+
+
+class TestAttachmentCounts:
+    @patch("tango.client.httpx.Client.request")
+    def test_get_opportunity_returns_file_and_link_counts(self, mock_request):
+        _mock(
+            mock_request,
+            {
+                "opportunity_id": "abc",
+                "meta": {"attachments_count": 6, "files_count": 3, "links_count": 2},
+            },
+        )
+        row = TangoClient(api_key="k").get_opportunity("abc", shape=OPPORTUNITY_COUNT_SHAPE)
+        assert mock_request.call_args.kwargs["params"]["shape"] == OPPORTUNITY_COUNT_SHAPE
+        assert row["meta"] == {"attachments_count": 6, "files_count": 3, "links_count": 2}
+
+    @patch("tango.client.httpx.Client.request")
+    def test_get_opportunity_keeps_uncounted_as_none(self, mock_request):
+        _mock(
+            mock_request,
+            {
+                "opportunity_id": "abc",
+                "meta": {"attachments_count": 4, "files_count": None, "links_count": None},
+            },
+        )
+        row = TangoClient(api_key="k").get_opportunity("abc", shape=OPPORTUNITY_COUNT_SHAPE)
+        assert row["meta"]["attachments_count"] == 4
+        assert row["meta"]["files_count"] is None
+        assert row["meta"]["links_count"] is None
+
+    @patch("tango.client.httpx.Client.request")
+    def test_list_notices_returns_file_and_link_counts(self, mock_request):
+        _mock(
+            mock_request,
+            {
+                "count": 2,
+                "next": None,
+                "previous": None,
+                "results": [
+                    {"notice_id": "n1", "attachment_count": 6, "file_count": 3, "link_count": 2},
+                    {
+                        "notice_id": "n2",
+                        "attachment_count": 1,
+                        "file_count": None,
+                        "link_count": None,
+                    },
+                ],
+            },
+        )
+        page = TangoClient(api_key="k").list_notices(shape=NOTICE_COUNT_SHAPE)
+        assert mock_request.call_args.kwargs["params"]["shape"] == NOTICE_COUNT_SHAPE
+        counted, uncounted = page.results
+        assert (counted["attachment_count"], counted["file_count"], counted["link_count"]) == (
+            6,
+            3,
+            2,
+        )
+        assert uncounted["attachment_count"] == 1
+        assert uncounted["file_count"] is None
+        assert uncounted["link_count"] is None

tango_python-1.14.0/tests/test_opportunity_attachments.py

@@ -1,72 +0,0 @@
-"""The `attachments(...)` expand on opportunities and notices, including the Pro-plan document-role fields."""
-
-from unittest.mock import Mock, patch
-
-import pytest
-
-from tango import TangoClient
-from tango.models import Notice, Opportunity
-from tango.shapes.parser import ShapeParser
-
-ROLE_SHAPE = "title,attachments(name,doc_role,doc_role_alt)"
-
-
-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 _attachments():
-    return [
-        {"name": "sow.pdf", "doc_role": "requirement", "doc_role_alt": None},
-        {"name": "pricing.xlsx", "doc_role": "pricing", "doc_role_alt": "terms"},
-        {"name": "unclassified.docx"},
-    ]
-
-
-class TestAttachmentShapes:
-    @pytest.mark.parametrize("model", [Opportunity, Notice])
-    @pytest.mark.parametrize(
-        "shape",
-        [
-            ROLE_SHAPE,
-            "title,attachments(name,url,extracted_text)",
-            "title,attachments(*)",
-        ],
-    )
-    def test_attachment_shape_validates(self, model, shape):
-        parser = ShapeParser(cache_enabled=False)
-        parser.validate(parser.parse(shape), model)
-
-
-class TestAttachmentRoles:
-    @pytest.mark.parametrize("method", ["get_opportunity", "get_notice"])
-    @patch("tango.client.httpx.Client.request")
-    def test_detail_returns_document_roles(self, mock_request, method):
-        _mock(mock_request, {"title": "Base ops support", "attachments": _attachments()})
-        row = getattr(TangoClient(api_key="k"), method)("abc", shape=ROLE_SHAPE)
-        assert [a.get("doc_role") for a in row["attachments"]] == ["requirement", "pricing", None]
-        assert row["attachments"][1]["doc_role_alt"] == "terms"
-
-    @pytest.mark.parametrize("method", ["list_opportunities", "list_notices"])
-    @patch("tango.client.httpx.Client.request")
-    def test_list_returns_document_roles(self, mock_request, method):
-        _mock(
-            mock_request,
-            {
-                "count": 1,
-                "next": None,
-                "previous": None,
-                "results": [{"title": "Amendment 1", "attachments": _attachments()}],
-            },
-        )
-        page = getattr(TangoClient(api_key="k"), method)(shape=ROLE_SHAPE)
-        assert mock_request.call_args.kwargs["params"]["shape"] == ROLE_SHAPE
-        assert [a.get("doc_role") for a in page.results[0]["attachments"]] == [
-            "requirement",
-            "pricing",
-            None,
-        ]