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

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

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.19.0] - 2026-10-21
+
+### Added
+
+- **`group_by`, `fiscal_year` and `rolling` on `get_entity_metrics()`, `get_naics_metrics()` and `get_psc_metrics()`.** The metrics endpoints have always accepted these query parameters, but the SDK built only the path, so callers could not split obligations by funding `"agency"` or `"department"` or bucket them by federal fiscal year. Each is optional; existing calls send the same request as before.
+
+## [1.18.2] - 2026-10-19
+
+### Fixed
+
+- **`TangoRateLimitError.limit_type` no longer reports a daily lockout as `burst`.** It matched "minute" anywhere in the API's detail, and a daily 429 reads `Rate limit exceeded for daily. Please try again in 16 hours, 58 minutes.`, so callers were told to retry a burst limit they could not clear until midnight UTC. It now reads the rate's name from `exceeded for <name>` and checks for daily first.
+
 ## [1.18.1] - 2026-10-19
 
 ### Fixed

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

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

@@ -2071,6 +2071,16 @@ psc = client.get_psc("D302")
 metrics = client.get_psc_metrics(code="D302", months=12, period_grouping="month")
 ```
 
+**Parameters:**
+- `code` (str): PSC code. Required.
+- `months` (int): Trailing window in months.
+- `period_grouping` (str): `"month"`, `"quarter"` or `"year"`.
+- `group_by` (`"agency"` | `"department"` | list | None): Split each period by funding organization. `agency` is an L2 short code such as `"2100"`; `department` is the CGAC code as an int, e.g. `97` for DoD.
+- `fiscal_year` (bool): Bucket by federal fiscal year instead of calendar periods. Default `False`.
+- `rolling` (bool): Add rolling averages. The API skips them, with a `warning`, when `group_by` is set. Default `False`.
+
+`get_naics_metrics()` and `get_entity_metrics()` take the same options.
+
 ---
 
 ## MAS SINs
@@ -2203,8 +2213,14 @@ lcats = client.list_entity_lcats("ABCDEF123456", limit=25)
 
 ```python
 metrics = client.get_entity_metrics("ABCDEF123456", months=12, period_grouping="month")
+# five fiscal years of obligations, split by funding department
+by_dept = client.get_entity_metrics(
+    "ABCDEF123456", months=60, period_grouping="year", group_by="department", fiscal_year=True
+)
 ```
 
+Takes the same `group_by`, `fiscal_year` and `rolling` options as [`get_psc_metrics()`](#get_psc_metrics).
+
 ### get_entity_budget_flows()
 
 Get budget flows for an entity (`/api/entities/{uei}/budget-flows/`) — the federal accounts that funded contracts and assistance awarded to this entity.

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

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

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

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

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

@@ -100,6 +100,10 @@ def _error_reason(error_data: dict[str, Any]) -> str | None:
     return None
 
 
+# Funding-organization keys the metrics endpoints accept in `group_by`.
+MetricsGroupBy = Literal["agency", "department"]
+
+
 class TangoClient:
     """Tango API Client"""
 
@@ -5615,7 +5619,15 @@ class TangoClient:
                 params["flat_lists"] = "true"
         return self._get(f"/api/psc/{code}/", params)
 
-    def get_psc_metrics(self, code: str, months: int, period_grouping: str) -> dict[str, Any]:
+    def get_psc_metrics(
+        self,
+        code: str,
+        months: int,
+        period_grouping: str,
+        group_by: MetricsGroupBy | list[MetricsGroupBy] | None = None,
+        fiscal_year: bool = False,
+        rolling: bool = False,
+    ) -> dict[str, Any]:
         """Get rolling PSC metrics (`/api/psc/{code}/metrics/{months}/{period_grouping}/`).
 
         Args:
@@ -5623,10 +5635,32 @@ class TangoClient:
             months: Window size in months (e.g. 6, 12, 24, 36).
             period_grouping: ``"month"``, ``"quarter"``, or ``"year"`` (the
                 values the API accepts on the path segment).
+            group_by: Split each period by the funding ``"agency"`` (an L2 short code such as ``"2100"``) or ``"department"`` (the CGAC code as an int, e.g. ``97`` for DoD), or both.
+            fiscal_year: Bucket by federal fiscal year (October-September) instead of calendar periods.
+            rolling: Add rolling averages. The API skips them, with a ``warning``, when ``group_by`` is set.
         """
         if not code:
             raise TangoValidationError("PSC code is required")
-        return self._get(f"/api/psc/{code}/metrics/{months}/{period_grouping}/")
+        return self._get(
+            f"/api/psc/{code}/metrics/{months}/{period_grouping}/",
+            self._metrics_params(group_by, fiscal_year, rolling),
+        )
+
+    @staticmethod
+    def _metrics_params(
+        group_by: MetricsGroupBy | list[MetricsGroupBy] | None,
+        fiscal_year: bool,
+        rolling: bool,
+    ) -> dict[str, Any]:
+        """Query params shared by the entity, NAICS and PSC metrics endpoints."""
+        params: dict[str, Any] = {}
+        if group_by:
+            params["group_by"] = group_by if isinstance(group_by, str) else ",".join(group_by)
+        if fiscal_year:
+            params["fiscal_year"] = "true"
+        if rolling:
+            params["rolling"] = "true"
+        return params
 
     def get_naics(
         self,
@@ -5647,11 +5681,25 @@ class TangoClient:
                 params["flat_lists"] = "true"
         return self._get(f"/api/naics/{code}/", params)
 
-    def get_naics_metrics(self, code: str, months: int, period_grouping: str) -> dict[str, Any]:
-        """Get rolling NAICS metrics (`/api/naics/{code}/metrics/{months}/{period_grouping}/`)."""
+    def get_naics_metrics(
+        self,
+        code: str,
+        months: int,
+        period_grouping: str,
+        group_by: MetricsGroupBy | list[MetricsGroupBy] | None = None,
+        fiscal_year: bool = False,
+        rolling: bool = False,
+    ) -> dict[str, Any]:
+        """Get rolling NAICS metrics (`/api/naics/{code}/metrics/{months}/{period_grouping}/`).
+
+        Takes the same ``group_by``, ``fiscal_year`` and ``rolling`` options as :meth:`get_psc_metrics`.
+        """
         if not code:
             raise TangoValidationError("NAICS code is required")
-        return self._get(f"/api/naics/{code}/metrics/{months}/{period_grouping}/")
+        return self._get(
+            f"/api/naics/{code}/metrics/{months}/{period_grouping}/",
+            self._metrics_params(group_by, fiscal_year, rolling),
+        )
 
     def get_business_type(
         self,
@@ -6026,13 +6074,26 @@ class TangoClient:
             meta=data.get("meta"),
         )
 
-    def get_entity_metrics(self, uei: str, months: int, period_grouping: str) -> dict[str, Any]:
+    def get_entity_metrics(
+        self,
+        uei: str,
+        months: int,
+        period_grouping: str,
+        group_by: MetricsGroupBy | list[MetricsGroupBy] | None = None,
+        fiscal_year: bool = False,
+        rolling: bool = False,
+    ) -> dict[str, Any]:
         """Get rolling metrics for an entity
         (`/api/entities/{uei}/metrics/{months}/{period_grouping}/`).
+
+        Takes the same ``group_by``, ``fiscal_year`` and ``rolling`` options as :meth:`get_psc_metrics`.
         """
         if not uei:
             raise TangoValidationError("UEI is required")
-        return self._get(f"/api/entities/{uei}/metrics/{months}/{period_grouping}/")
+        return self._get(
+            f"/api/entities/{uei}/metrics/{months}/{period_grouping}/",
+            self._metrics_params(group_by, fiscal_year, rolling),
+        )
 
     # ============================================================================
     # IDV sub-resources

{tango_python-1.18.1 → tango_python-1.19.0}/tango/exceptions.py

@@ -1,7 +1,11 @@
 """Tango API exceptions"""
 
+import re
 from typing import Any
 
+# The API names the tripped rate in its 429 detail: "Rate limit exceeded for daily. Please try again in 16 hours, 58 minutes."
+_RATE_NAME = re.compile(r"exceeded for ([\w-]+)", re.IGNORECASE)
+
 
 class TangoAPIError(Exception):
     """Base exception for Tango API errors"""
@@ -88,11 +92,13 @@ class TangoRateLimitError(TangoAPIError):
         d = self.detail
         if not d:
             return None
-        lower = d.lower()
-        if "burst" in lower or "minute" in lower:
-            return "burst"
-        if "daily" in lower or "day" in lower:
+        # Read the rate's name, not the whole sentence: a daily lockout's wait reads "16 hours, 58 minutes", which a match on "minute" took for burst.
+        match = _RATE_NAME.search(d)
+        text = match.group(1).lower() if match else d.lower()
+        if "daily" in text or re.search(r"\bday\b", text):
             return "daily"
+        if "burst" in text or "minute" in text:
+            return "burst"
         return None
 
 

{tango_python-1.18.1 → tango_python-1.19.0}/tests/test_api_parity.py

@@ -372,6 +372,23 @@ class TestReferenceData:
         client = TangoClient(api_key="x", base_url="https://t.example")
         client.get_psc_metrics("R425", 12, "month")
         assert mock_request.call_args[1]["url"].endswith("/api/psc/R425/metrics/12/month/")
+        assert not mock_request.call_args[1]["params"]
+
+    def test_metrics_query_params(self, mock_request: Mock) -> None:
+        mock_request.return_value = _mock_response({"results": []})
+        client = TangoClient(api_key="x", base_url="https://t.example")
+        client.get_psc_metrics("R425", 12, "year", group_by="department", fiscal_year=True)
+        assert mock_request.call_args[1]["params"] == {
+            "group_by": "department",
+            "fiscal_year": "true",
+        }
+        client.get_naics_metrics(
+            "541511", 12, "year", group_by=["agency", "department"], rolling=True
+        )
+        assert mock_request.call_args[1]["params"] == {
+            "group_by": "agency,department",
+            "rolling": "true",
+        }
 
     def test_get_naics(self, mock_request: Mock) -> None:
         mock_request.return_value = _mock_response({"code": "541511"})
@@ -409,6 +426,15 @@ class TestEntitySubResources:
         client.get_entity_metrics("UEI1", 24, "quarter")
         assert mock_request.call_args[1]["url"].endswith("/api/entities/UEI1/metrics/24/quarter/")
 
+    def test_get_entity_metrics_by_department(self, mock_request: Mock) -> None:
+        mock_request.return_value = _mock_response({"results": []})
+        client = TangoClient(api_key="x", base_url="https://t.example")
+        client.get_entity_metrics("UEI1", 60, "year", group_by="department", fiscal_year=True)
+        assert mock_request.call_args[1]["params"] == {
+            "group_by": "department",
+            "fiscal_year": "true",
+        }
+
     def test_list_entity_lcats(self, mock_request: Mock) -> None:
         mock_request.return_value = _mock_response(
             {"count": 0, "next": None, "previous": None, "results": []}

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

@@ -1502,6 +1502,22 @@ class TestErrorHandling:
         assert exc_info.value.limit_type == "daily"
         assert exc_info.value.wait_in_seconds == 3600
 
+    @pytest.mark.parametrize(
+        ("detail", "expected"),
+        [
+            # The API's own wording, with its waits as convert_seconds_to_human_readable_wait_time renders them.
+            ("Rate limit exceeded for daily. Please try again in 16 hours, 58 minutes.", "daily"),
+            ("Rate limit exceeded for daily. Please try again in 1 minute.", "daily"),
+            ("Rate limit exceeded for burst. Please try again in 45 seconds.", "burst"),
+            ("Rate limit exceeded for burst. Please try again in 1 minute.", "burst"),
+            ("Too many requests.", None),
+        ],
+    )
+    def test_limit_type_reads_the_rate_name_not_the_wait(self, detail, expected):
+        error = TangoRateLimitError("Rate limit exceeded", 429, {"detail": detail})
+
+        assert error.limit_type == expected
+
     @patch("tango.client.httpx.Client.request")
     def test_429_empty_body(self, mock_request):
         """Test 429 with no content body still works"""