tango-python 1.1.1__tar.gz → 1.1.2__tar.gz

{tango_python-1.1.1 → tango_python-1.1.2}/.github/workflows/docs-dispatch.yml

@@ -30,7 +30,7 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 2
 

{tango_python-1.1.1 → tango_python-1.1.2}/.github/workflows/lint.yml

@@ -3,9 +3,8 @@ name: Linting
 # Lint gate runs on every PR and push to main.
 #
 # - ruff format + ruff check are HARD gates (block the PR).
-# - mypy is ADVISORY for now (continue-on-error): the package carries ~28
-#   pre-existing type errors that predate CI enforcement. Tracked for burn-down
-#   in makegov/tango-python; flip `continue-on-error` off once that's clear.
+# - 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 needs the canonical manifest from the
 #   private makegov/tango repo, which requires a TANGO_API_REPO_ACCESS_TOKEN
 #   secret the public CI does not have. The conformance job SKIPS cleanly when
@@ -23,10 +22,10 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
 
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         version: "latest"
 
@@ -42,8 +41,7 @@ jobs:
     - name: Lint with ruff
       run: uv run ruff check tango/
 
-    - name: Type check with mypy (advisory)
-      continue-on-error: true
+    - name: Type check with mypy
       run: uv run mypy tango/
 
   conformance:
@@ -66,12 +64,12 @@ jobs:
           echo "::notice::Skipping SDK conformance check — TANGO_API_REPO_ACCESS_TOKEN not configured."
         fi
 
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       if: steps.gate.outputs.ready == 'true'
 
     - name: Checkout tango API repo (manifest source)
       if: steps.gate.outputs.ready == 'true'
-      uses: actions/checkout@v4
+      uses: actions/checkout@v6
       with:
         repository: makegov/tango
         path: tango-api
@@ -79,7 +77,7 @@ jobs:
 
     - name: Install uv
       if: steps.gate.outputs.ready == 'true'
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         version: "latest"
 

{tango_python-1.1.1 → tango_python-1.1.2}/.github/workflows/publish.yml

@@ -10,10 +10,10 @@ jobs:
     runs-on: ubuntu-latest
     
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         version: 'latest'
     

{tango_python-1.1.1 → tango_python-1.1.2}/.github/workflows/test.yml

@@ -20,10 +20,10 @@ jobs:
       if: matrix.os == 'windows-latest'
       run: git config --global core.longpaths true
     
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
     
     - name: Install uv
-      uses: astral-sh/setup-uv@v4
+      uses: astral-sh/setup-uv@v8.1.0
       with:
         version: "latest"
     
@@ -37,8 +37,8 @@ jobs:
       run: uv run pytest
     
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v5
       with:
-        file: ./coverage.xml
+        files: ./coverage.xml
         flags: unittests
         name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}

{tango_python-1.1.1 → tango_python-1.1.2}/CHANGELOG.md

@@ -7,6 +7,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.2] - 2026-06-04
+
+### Changed
+- `get_entity_budget_flows()` now exposes the backend's standard page/limit
+  pagination and `fiscal_year` filter, and returns
+  `PaginatedResponse[dict[str, Any]]` instead of a raw dict. The backend has
+  always paginated this endpoint via `StandardResultsSetPagination`; the
+  previous signature gave callers no way to reach pages beyond the first or
+  to narrow by fiscal year. Callers that were indexing `result["results"]`
+  on the old return value should switch to `result.results` (and can now use
+  `result.next` / `page=` to walk further pages).
+- Completed the strict-`mypy` burn-down across `tango/shapes/` (parser,
+  generator, factory, schema). All changes are type-annotation/typing
+  corrections with no runtime behavior change, except:
+  - `FieldSchema.nested_model` is now typed `type | str | None` (it always
+    accepted string model names from the explicit schemas; the annotation was
+    wrong). `ModelFactory.validate_data` and `ShapeParser._validate_field_spec`
+    likewise accept `type | str` for the model argument.
+  - Removed two dead `elif field_spec.is_wildcard:` branches (in
+    `TypeGenerator.generate_type` and `ModelFactory.create_instance`) and the
+    now-orphaned `_parse_nested_wildcard` helper. These were unreachable —
+    wildcard field specs are fully handled by the top-of-loop branch that
+    `continue`s before reaching them — so removal is behavior-preserving.
+
+### Docs
+- `docs/API_REFERENCE.md` now documents the Budget surface that shipped in
+  v1.1.0: a new `## Budget` section covering `list_budget_accounts`,
+  `get_budget_account`, `get_budget_account_quarters`, and
+  `get_budget_account_recipients`; a `get_entity_budget_flows()` entry under
+  Entity Sub-resources; a `BUDGET_ACCOUNTS_MINIMAL` row in the ShapeConfig
+  table; and a Budget entry in the table of contents.
+
+### CI
+- Bumped GitHub Actions off the deprecated Node 20 runtime (forced off
+  2026-06-02): `actions/checkout` v4→v6, `astral-sh/setup-uv` v4→v8.1.0
+  (pinned exact — no floating `v8` major tag is published yet), and
+  `codecov/codecov-action` v3→v5 (with the renamed `files:` input).
+- `mypy` is now a **hard gate** in `lint.yml` (no longer advisory). The
+  `tango/` package type-checks cleanly under strict mypy.
+
 ## [1.1.1] - 2026-05-29
 
 ### Removed

{tango_python-1.1.1 → tango_python-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 1.1.1
+Version: 1.1.2
 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.1.1 → tango_python-1.1.2}/docs/API_REFERENCE.md

@@ -21,6 +21,7 @@ Complete reference for all Tango Python SDK methods and functionality.
 - [Grants](#grants)
 - [GSA eLibrary Contracts](#gsa-elibrary-contracts)
 - [Protests](#protests)
+- [Budget](#budget)
 - [Business Types](#business-types)
 - [NAICS](#naics)
 - [Webhooks](#webhooks)
@@ -1212,6 +1213,118 @@ protest = client.get_protest(
 
 ---
 
+## Budget
+
+Federal account × fiscal year budget rollups, covering the full budget lifecycle (requested → enacted → apportioned → obligated → outlayed), pre-computed ratios and trends, the contract / assistance / unlinked breakdown, and request-vs-actual spend.
+
+### list_budget_accounts()
+
+List budget accounts. One row per `(federal_account_symbol, fiscal_year)`.
+
+```python
+accounts = client.list_budget_accounts(
+    page=1,
+    limit=25,
+    shape=ShapeConfig.BUDGET_ACCOUNTS_MINIMAL,
+    # Filter parameters (all optional)
+    federal_account_symbol=None,
+    fiscal_year=None,
+    fiscal_year_gte=None,
+    fiscal_year_lte=None,
+    agency_code=None,
+    bureau_name=None,
+    account_title=None,
+    bea_category=None,
+    on_off_budget=None,
+    subfunction_code=None,
+    search=None,
+    ordering=None,
+)
+```
+
+**Filter Parameters:**
+- `federal_account_symbol` - Exact federal account symbol (e.g., `"097-0100"`)
+- `fiscal_year` - Fiscal year (exact)
+- `fiscal_year_gte` / `fiscal_year_lte` - Fiscal year range
+- `agency_code` - Agency code (exact)
+- `bureau_name` - Bureau name (exact)
+- `account_title` - Account title (case-insensitive substring match)
+- `bea_category` - BEA category (exact)
+- `on_off_budget` - On/off budget flag (exact)
+- `subfunction_code` - Subfunction code (exact)
+- `search` - Full-text search over `account_title`, `agency_name`, `bureau_name`
+- `ordering` - Sort field; prefix with `-` for descending
+
+**Returns:** [PaginatedResponse](#paginatedresponse) of `BudgetAccount` records (see [ShapeConfig](#shapeconfig-predefined-shapes) for the default shape).
+
+**Example:**
+```python
+accounts = client.list_budget_accounts(
+    agency_code="097",
+    fiscal_year_gte=2023,
+    ordering="-enacted_ba",
+    limit=10,
+)
+
+for acct in accounts.results:
+    print(f"{acct.federal_account_symbol} FY{acct.fiscal_year}: "
+          f"enacted ${acct.enacted_ba:,}")
+```
+
+### get_budget_account()
+
+Get a single budget account by id.
+
+```python
+account = client.get_budget_account(
+    12345,
+    shape=ShapeConfig.BUDGET_ACCOUNTS_MINIMAL,
+)
+```
+
+**Parameters:**
+- `id` (str | int): Budget account id.
+- `shape` (str, optional): Response shape. Defaults to `BUDGET_ACCOUNTS_MINIMAL`.
+- `flat` / `flat_lists` / `joiner`: See [Shaping Guide](SHAPES.md).
+
+**Returns:** A `BudgetAccount` record.
+
+### get_budget_account_quarters()
+
+Get quarterly TAS-grain flow for a budget account. FY21+ only.
+
+```python
+quarters = client.get_budget_account_quarters(12345, limit=25)
+```
+
+**Parameters:**
+- `id` (str | int): Budget account id.
+- `tas` (str, optional): Narrow to a single Treasury Account Symbol.
+- `limit` (int): Results per page (max 100).
+
+**Returns:** [PaginatedResponse](#paginatedresponse) of quarterly flow records.
+
+### get_budget_account_recipients()
+
+Get funding-office × recipient contract-flow detail for a budget account.
+
+```python
+recipients = client.get_budget_account_recipients(
+    12345,
+    funding_organization_id=None,
+    limit=25,
+)
+```
+
+**Parameters:**
+- `id` (str | int): Budget account id.
+- `funding_organization_id` (str, optional): Narrow to a single funding office (Organization UUID).
+- `limit` (int): Results per page (max 100).
+
+**Returns:** [PaginatedResponse](#paginatedresponse) of `(funding_office, recipient)` flow records.
+
+---
+
 ## Business Types
 
 Business type classifications.
@@ -1461,6 +1574,26 @@ lcats = client.list_entity_lcats("ABCDEF123456", limit=25)
 metrics = client.get_entity_metrics("ABCDEF123456", months=12, period_grouping="month")
 ```
 
+### 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.
+
+```python
+flows = client.get_entity_budget_flows("ABCDEF123456", fiscal_year=2024)
+for row in flows.results:
+    print(row["federal_account_symbol"], row["contract_obligated"])
+# next page
+more = client.get_entity_budget_flows("ABCDEF123456", page=2, fiscal_year=2024)
+```
+
+**Parameters:**
+- `uei` (str): Entity UEI. Required.
+- `page` (int): Page number. Default 1.
+- `limit` (int): Results per page. Default 25, max 100.
+- `fiscal_year` (int | None): Optional fiscal year filter.
+
+**Returns:** `PaginatedResponse[dict[str, Any]]` — standard `count / next / previous / results`. Result rows are raw dicts from the API (not shape-controlled).
+
 ---
 
 ## IDV LCATs
@@ -1875,6 +2008,7 @@ entity = client.get_entity("UEI_KEY", shape=ShapeConfig.ENTITIES_COMPREHENSIVE)
 | `SUBAWARDS_MINIMAL` | `list_subawards` | award_key, prime_recipient(uei,display_name), subaward_recipient(uei,display_name) |
 | `GSA_ELIBRARY_CONTRACTS_MINIMAL` | `list_gsa_elibrary_contracts` | uuid, contract_number, schedule, recipient(display_name,uei), idv(key,award_date) |
 | `PROTESTS_MINIMAL` | `list_protests` | case_id, case_number, title, source_system, outcome, filed_date |
+| `BUDGET_ACCOUNTS_MINIMAL` | `list_budget_accounts`, `get_budget_account` | id, federal_account_symbol, fiscal_year, agency_code/name, bureau_name, account_title, bea_category, on_off_budget, subfunction_code, lifecycle (requested/enacted/apportioned/obligated/outlayed/unobligated), contract & assistance rollups, key ratios, next-year growth |
 | `VEHICLE_ORDERS_MINIMAL` | `list_vehicle_orders` | key, piid, award_date, recipient(display_name,uei), total_contract_value, obligated |
 | `ITDASHBOARD_INVESTMENTS_MINIMAL` | `list_itdashboard_investments` | Minimal IT Dashboard investment fields |
 | `ITDASHBOARD_INVESTMENTS_COMPREHENSIVE` | `get_itdashboard_investment` | Full investment fields: uii, agency_code, agency_name, bureau_code, bureau_name, investment_title, type_of_investment, part_of_it_portfolio, updated_time, url |

{tango_python-1.1.1 → tango_python-1.1.2}/pyproject.toml

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

{tango_python-1.1.1 → tango_python-1.1.2}/tango/__init__.py

@@ -44,7 +44,7 @@ from .webhooks import (
 )
 from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "1.1.1"
+__version__ = "1.1.2"
 __all__ = [
     "TangoClient",
     "TangoAPIError",

{tango_python-1.1.1 → tango_python-1.1.2}/tango/client.py

@@ -2081,11 +2081,36 @@ class TangoClient:
         data = self._get(f"/api/entities/{key}/", params)
         return self._parse_response_with_shape(data, shape, Entity, flat, flat_lists)
 
-    def get_entity_budget_flows(self, uei: str) -> dict[str, Any]:
-        """Get budget flows for an entity (`/api/entities/{uei}/budget-flows/`)."""
+    def get_entity_budget_flows(
+        self,
+        uei: str,
+        page: int = 1,
+        limit: int = 25,
+        fiscal_year: int | None = None,
+    ) -> PaginatedResponse[dict[str, Any]]:
+        """Get budget flows for an entity (`/api/entities/{uei}/budget-flows/`).
+
+        Standard page/limit pagination (default 25, max 100). Each result row
+        is a hand-built dict from the backend (no shape system).
+
+        Args:
+            uei: Entity UEI. Required.
+            page: Page number.
+            limit: Results per page (max 100).
+            fiscal_year: Optional fiscal year filter.
+        """
         if not uei:
             raise TangoValidationError("UEI is required")
-        return self._get(f"/api/entities/{uei}/budget-flows/")
+        params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+        if fiscal_year is not None:
+            params["fiscal_year"] = fiscal_year
+        data = self._get(f"/api/entities/{uei}/budget-flows/", params)
+        return PaginatedResponse(
+            count=int(data.get("count", 0)),
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=list(data.get("results") or []),
+        )
 
     # Forecast endpoints
     def list_forecasts(

{tango_python-1.1.1 → tango_python-1.1.2}/tango/shapes/factory.py

@@ -23,7 +23,7 @@ import logging
 from collections.abc import Callable
 from datetime import date, datetime
 from decimal import Decimal
-from typing import Any
+from typing import Any, cast
 
 from tango.exceptions import ModelInstantiationError
 from tango.shapes.generator import TypeGenerator
@@ -542,38 +542,6 @@ class ModelFactory:
                             # Value is not a dict - might be a primitive or None
                             result[result_field_name] = value
 
-                elif field_spec.is_wildcard:
-                    # Wildcard on nested field - use full model type
-                    # This is handled at the top level, but we need to handle it here too
-                    # for nested wildcards like recipient(*)
-                    if field_schema.nested_model:
-                        if field_schema.is_list:
-                            if isinstance(value, list):
-                                nested_instances = []
-                                for item in value:
-                                    if isinstance(item, dict):
-                                        # Parse all fields from the nested model
-                                        nested_instance = self._parse_nested_wildcard(
-                                            item, field_schema.nested_model
-                                        )
-                                        nested_instances.append(nested_instance)
-                                    else:
-                                        nested_instances.append(item)
-                                result[result_field_name] = nested_instances
-                            else:
-                                result[result_field_name] = value
-                        else:
-                            if isinstance(value, dict):
-                                nested_instance = self._parse_nested_wildcard(
-                                    value, field_schema.nested_model
-                                )
-                                result[result_field_name] = nested_instance
-                            else:
-                                result[result_field_name] = value
-                    else:
-                        # Not a nested model, just use the value
-                        result[result_field_name] = value
-
                 else:
                     # Simple field - parse using appropriate parser
                     parsed_value = self._parse_field(
@@ -661,7 +629,7 @@ class ModelFactory:
                     raise ModelInstantiationError(
                         f"Could not resolve nested model '{nested_model}'"
                     )
-                return model_class
+                return cast(type, model_class)
             except ImportError as err:
                 raise ModelInstantiationError(
                     f"Could not import models module to resolve '{nested_model}'"
@@ -704,41 +672,6 @@ class ModelFactory:
         # Recursively create nested instance
         return self.create_instance(data, nested_shape, resolved_model, nested_type)
 
-    def _parse_nested_wildcard(
-        self, data: dict[str, Any], nested_model: type | str
-    ) -> dict[str, Any]:
-        """Parse nested object with wildcard (all fields)
-
-        Args:
-            data: Nested object data
-            nested_model: Model class or string name for the nested object
-
-        Returns:
-            Dictionary with all parsed fields
-        """
-        # Resolve nested model if it's a string
-        resolved_model = self._resolve_nested_model(nested_model)
-
-        # Ensure model is registered
-        if not self.schema_registry.is_registered(resolved_model):
-            self.schema_registry.register(resolved_model)
-
-        # Get model schema
-        model_schema = self.schema_registry.get_schema(resolved_model)
-
-        # Parse all fields
-        result: dict[str, Any] = {}
-        for field_name, value in data.items():
-            if field_name in model_schema:
-                field_schema = model_schema[field_name]
-                parsed_value = self._parse_field(field_name, value, field_schema.type, field_schema)
-                result[field_name] = parsed_value
-            else:
-                # Field not in schema, include as-is
-                result[field_name] = value
-
-        return result
-
     def _parse_field(self, field_name: str, value: Any, field_type: type, field_schema: Any) -> Any:
         """Parse a single field value using appropriate parser
 
@@ -778,7 +711,7 @@ class ModelFactory:
         return value
 
     def validate_data(
-        self, data: dict[str, Any], shape_spec: ShapeSpec, base_model: type
+        self, data: dict[str, Any], shape_spec: ShapeSpec, base_model: type | str
     ) -> list[str]:
         """Validate that data matches the shape specification
 
@@ -803,11 +736,15 @@ class ModelFactory:
         errors: list[str] = []
 
         if not isinstance(data, dict):
-            errors.append(f"Expected dictionary data, got {type(data).__name__}")
+            errors.append(  # type: ignore[unreachable]
+                f"Expected dictionary data, got {type(data).__name__}"
+            )
             return errors
 
-        # Ensure model is registered
-        if not self.schema_registry.is_registered(base_model):
+        # Ensure model is registered. String model names are expected to be
+        # pre-registered (explicit schemas); only concrete classes can be
+        # auto-registered via introspection.
+        if isinstance(base_model, type) and not self.schema_registry.is_registered(base_model):
             self.schema_registry.register(base_model)
 
         # Get model schema
@@ -826,9 +763,8 @@ class ModelFactory:
 
             # Check if field exists in schema
             if field_spec.name not in model_schema:
-                errors.append(
-                    f"Field '{field_spec.name}' does not exist in {base_model.__name__} schema"
-                )
+                model_name = base_model.__name__ if isinstance(base_model, type) else base_model
+                errors.append(f"Field '{field_spec.name}' does not exist in {model_name} schema")
                 continue
 
             field_schema = model_schema[field_spec.name]

{tango_python-1.1.1 → tango_python-1.1.2}/tango/shapes/generator.py

@@ -20,7 +20,7 @@ Examples:
 import logging
 import threading
 from collections import OrderedDict
-from typing import Any, get_args, get_origin, get_type_hints
+from typing import Any, cast, get_args, get_origin, get_type_hints
 
 from tango.exceptions import TypeGenerationError
 from tango.shapes.models import ShapeSpec
@@ -250,7 +250,10 @@ class TypeGenerator:
 
                 field_schema = model_schema[field_spec.name]
 
-                # Determine field type
+                # Determine field type. The value is a heterogeneous mix of type
+                # objects, parameterized generics (list[...]), and union objects,
+                # so it is intentionally typed as Any.
+                field_type: Any
                 if field_spec.nested_fields:
                     # Generate nested type
                     if not field_schema.nested_model:
@@ -275,25 +278,7 @@ class TypeGenerator:
 
                     # Handle optional types
                     if field_schema.is_optional:
-                        field_type = field_type | None  # type: ignore
-
-                    annotations[field_name] = field_type
-
-                elif field_spec.is_wildcard:
-                    # Wildcard on nested field - use full model type
-                    if field_schema.nested_model:
-                        # Resolve nested model if it's a string
-                        field_type = self._resolve_nested_model(field_schema.nested_model)
-                    else:
-                        field_type = field_schema.type
-
-                    # Handle list types
-                    if field_schema.is_list:
-                        field_type = list[field_type]  # type: ignore
-
-                    # Handle optional types
-                    if field_schema.is_optional:
-                        field_type = field_type | None  # type: ignore
+                        field_type = field_type | None
 
                     annotations[field_name] = field_type
 
@@ -303,11 +288,11 @@ class TypeGenerator:
 
                     # Handle list types
                     if field_schema.is_list:
-                        field_type = list[field_type]  # type: ignore
+                        field_type = list[field_type]
 
                     # Handle optional types
                     if field_schema.is_optional:
-                        field_type = field_type | None  # type: ignore
+                        field_type = field_type | None
 
                     annotations[field_name] = field_type
 
@@ -329,7 +314,7 @@ class TypeGenerator:
                     field_type = field_schema.type
                     # Handle optional types
                     if field_schema.is_optional:
-                        field_type = field_type | None  # type: ignore
+                        field_type = field_type | None
                     annotations[auto_field] = field_type
 
             # Create TypedDict dynamically
@@ -414,7 +399,7 @@ class TypeGenerator:
                 model_class = getattr(models, nested_model, None)
                 if model_class is None:
                     raise TypeGenerationError(f"Could not resolve nested model '{nested_model}'")
-                return model_class
+                return cast(type, model_class)
             except ImportError as err:
                 raise TypeGenerationError(
                     f"Could not import models module to resolve '{nested_model}'"
@@ -555,7 +540,7 @@ class TypeGenerator:
 
         # Handle basic types
         if hasattr(type_annotation, "__name__"):
-            type_name = type_annotation.__name__
+            type_name = str(type_annotation.__name__)
         else:
             type_name = str(type_annotation)
 
@@ -576,7 +561,7 @@ class TypeGenerator:
                 if args:
                     formatted_args = [self._format_type_annotation(arg) for arg in args]
                     return f"{origin.__name__}[{', '.join(formatted_args)}]"
-                return origin.__name__
+                return str(origin.__name__)
 
         return type_name