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

{tango_python-1.1.1 → tango_python-1.1.3}/.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.3}/.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.3}/.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.3}/.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.3}/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.3] - 2026-06-04
+
+### Added
+- Reference-data list/get methods now accept `shape` (and the associated
+  `flat` / `flat_lists`) parameters, matching the underlying API which has
+  always supported the shape system via `ShapeOnDemandMixin`. Affected:
+  `list_naics` / `get_naics`, `list_psc` / `get_psc`,
+  `list_assistance_listings` / `get_assistance_listing`,
+  `list_business_types` / `get_business_type`,
+  `list_mas_sins` / `get_mas_sin`. When `shape` is omitted, behavior is
+  unchanged — the API applies its own per-resource default.
+  `list_business_types` returns raw dicts (instead of `BusinessType`
+  instances) when a `shape` is supplied so the caller gets exactly the
+  shape requested.
+
+## [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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 1.1.1
+Version: 1.1.3
 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.3}/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.3}/pyproject.toml

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

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

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

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

@@ -1923,15 +1923,37 @@ class TangoClient:
         )
 
     # Business Types endpoints
-    def list_business_types(self, page: int = 1, limit: int = 25) -> PaginatedResponse:
-        """List business types"""
-        params = {"page": page, "limit": min(limit, 100)}
+    def list_business_types(
+        self,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> PaginatedResponse:
+        """List business types.
+
+        When ``shape`` is omitted the API applies its own default
+        (``name,code``) and results are returned as :class:`BusinessType`
+        instances. When ``shape`` is provided, raw dicts are returned so the
+        caller can rely on the exact shape requested.
+        """
+        params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
         data = self._get("/api/business_types/", params)
+        results: list[Any] = (
+            list(data["results"]) if shape else [BusinessType(**btype) for btype in data["results"]]
+        )
         return PaginatedResponse(
             count=data["count"],
             next=data.get("next"),
             previous=data.get("previous"),
-            results=[BusinessType(**btype) for btype in data["results"]],
+            results=results,
         )
 
     def list_naics(
@@ -1945,8 +1967,17 @@ class TangoClient:
         revenue_limit_gte: int | None = None,
         revenue_limit_lte: int | None = None,
         search: str | None = None,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
     ) -> PaginatedResponse:
-        """List NAICS codes (`/api/naics/`)."""
+        """List NAICS codes (`/api/naics/`).
+
+        When ``shape`` is omitted the API applies its own default. Passing any
+        of the ``revenue_limit*`` / ``employee_limit*`` filters causes the API
+        to widen the default shape to include ``size_standards`` and
+        ``federal_obligations``.
+        """
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
         if employee_limit is not None:
             params["employee_limit"] = employee_limit
@@ -1962,6 +1993,12 @@ class TangoClient:
             params["revenue_limit_lte"] = revenue_limit_lte
         if search is not None:
             params["search"] = search
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
         data = self._get("/api/naics/", params)
         return PaginatedResponse(
             count=data.get("count", 0),
@@ -2081,11 +2118,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(
@@ -3319,9 +3381,22 @@ class TangoClient:
             raise TangoValidationError("Department code is required")
         return self._get(f"/api/departments/{code}/")
 
-    def list_psc(self, page: int = 1, limit: int = 25) -> PaginatedResponse[dict[str, Any]]:
+    def list_psc(
+        self,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> PaginatedResponse[dict[str, Any]]:
         """List Product Service Codes (`/api/psc/`)."""
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
         data = self._get("/api/psc/", params)
         return PaginatedResponse(
             count=int(data.get("count", 0)),
@@ -3330,11 +3405,24 @@ class TangoClient:
             results=list(data.get("results") or []),
         )
 
-    def get_psc(self, code: str) -> dict[str, Any]:
+    def get_psc(
+        self,
+        code: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> dict[str, Any]:
         """Get a Product Service Code by code (`/api/psc/{code}/`)."""
         if not code:
             raise TangoValidationError("PSC code is required")
-        return self._get(f"/api/psc/{code}/")
+        params: dict[str, Any] = {}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                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]:
         """Get rolling PSC metrics (`/api/psc/{code}/metrics/{months}/{period_grouping}/`).
@@ -3349,11 +3437,24 @@ class TangoClient:
             raise TangoValidationError("PSC code is required")
         return self._get(f"/api/psc/{code}/metrics/{months}/{period_grouping}/")
 
-    def get_naics(self, code: str) -> dict[str, Any]:
+    def get_naics(
+        self,
+        code: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> dict[str, Any]:
         """Get a NAICS code by code (`/api/naics/{code}/`)."""
         if not code:
             raise TangoValidationError("NAICS code is required")
-        return self._get(f"/api/naics/{code}/")
+        params: dict[str, Any] = {}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                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}/`)."""
@@ -3361,17 +3462,41 @@ class TangoClient:
             raise TangoValidationError("NAICS code is required")
         return self._get(f"/api/naics/{code}/metrics/{months}/{period_grouping}/")
 
-    def get_business_type(self, code: str) -> dict[str, Any]:
+    def get_business_type(
+        self,
+        code: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> dict[str, Any]:
         """Get a business type by code (`/api/business_types/{code}/`)."""
         if not code:
             raise TangoValidationError("Business type code is required")
-        return self._get(f"/api/business_types/{code}/")
+        params: dict[str, Any] = {}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
+        return self._get(f"/api/business_types/{code}/", params)
 
     def list_assistance_listings(
-        self, page: int = 1, limit: int = 25
+        self,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
     ) -> PaginatedResponse[dict[str, Any]]:
         """List Assistance Listings (CFDA programs) (`/api/assistance_listings/`)."""
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
         data = self._get("/api/assistance_listings/", params)
         return PaginatedResponse(
             count=int(data.get("count", 0)),
@@ -3380,22 +3505,44 @@ class TangoClient:
             results=list(data.get("results") or []),
         )
 
-    def get_assistance_listing(self, number: str) -> dict[str, Any]:
+    def get_assistance_listing(
+        self,
+        number: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> dict[str, Any]:
         """Get an Assistance Listing by CFDA number (`/api/assistance_listings/{number}/`)."""
         if not number:
             raise TangoValidationError("Assistance listing number is required")
-        return self._get(f"/api/assistance_listings/{number}/")
+        params: dict[str, Any] = {}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
+        return self._get(f"/api/assistance_listings/{number}/", params)
 
     def list_mas_sins(
         self,
         page: int = 1,
         limit: int = 25,
         search: str | None = None,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
     ) -> PaginatedResponse[dict[str, Any]]:
         """List GSA MAS SINs (`/api/mas_sins/`)."""
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
         if search is not None:
             params["search"] = search
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
         data = self._get("/api/mas_sins/", params)
         return PaginatedResponse(
             count=int(data.get("count", 0)),
@@ -3404,11 +3551,24 @@ class TangoClient:
             results=list(data.get("results") or []),
         )
 
-    def get_mas_sin(self, sin: str) -> dict[str, Any]:
+    def get_mas_sin(
+        self,
+        sin: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+    ) -> dict[str, Any]:
         """Get a MAS SIN by code (`/api/mas_sins/{sin}/`)."""
         if not sin:
             raise TangoValidationError("MAS SIN is required")
-        return self._get(f"/api/mas_sins/{sin}/")
+        params: dict[str, Any] = {}
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
+        return self._get(f"/api/mas_sins/{sin}/", params)
 
     # ============================================================================
     # Entity sub-resources