Added in /grants endpoint and method

Author: vdavez

README.md

@@ -6,7 +6,7 @@ A modern Python SDK for the [Tango API](https://tango.makegov.com) by MakeGov, f
 
 - **Dynamic Response Shaping** - Request only the fields you need, reducing payload sizes by 60-80%
 - **Full Type Safety** - Runtime-generated TypedDict types with accurate type hints for IDE autocomplete
-- **Comprehensive API Coverage** - All major Tango API endpoints (contracts, entities, forecasts, opportunities, notices) [Note: the current version does NOT implement all endpoints, we will be adding them incrementally]
+- **Comprehensive API Coverage** - All major Tango API endpoints (contracts, entities, forecasts, opportunities, notices, grants) [Note: the current version does NOT implement all endpoints, we will be adding them incrementally]
 - **Flexible Data Access** - Dictionary-based response objects with validation
 - **Modern Python** - Built for Python 3.12+ using modern async-ready patterns
 - **Production-Ready** - Comprehensive test suite with VCR.py-based integration tests
@@ -175,6 +175,16 @@ notices = client.list_notices(
 )
 ```
 
+### Grants
+
+```python
+# List grant opportunities
+grants = client.list_grants(
+    agency_code="HHS",
+    limit=25
+)
+```
+
 ### Business Types
 
 ```python
@@ -360,39 +370,63 @@ uv run ruff format tango/ && uv run ruff check tango/ && uv run mypy tango/
 
 ```
 tango-python/
-├── tango/
+├── tango/                    # Main SDK package
 │   ├── __init__.py          # Public API exports
 │   ├── client.py            # TangoClient implementation
 │   ├── models.py            # Data models and shape configs
 │   ├── exceptions.py        # Exception classes
 │   └── shapes/              # Dynamic model system
+│       ├── __init__.py      # Shapes package exports
 │       ├── parser.py        # Shape string parser
 │       ├── generator.py     # TypedDict generator
 │       ├── factory.py       # Instance factory
 │       ├── schema.py        # Schema registry
-│       ├── explicit_schemas.py  # Predefined schemas
+│       ├── explicit_schemas.py  # Predefined schemas (Contract, Entity, Grant, etc.)
+│       ├── models.py        # Shape specification models
 │       └── types.py         # TypedDict exports
-├── tests/
-│   ├── test_client.py       # Unit tests
+├── tests/                    # Test suite
+│   ├── __init__.py
+│   ├── conftest.py          # Pytest configuration
+│   ├── test_client.py       # Unit tests for client
 │   ├── test_models.py       # Model tests
 │   ├── test_shapes.py       # Shape system tests
+│   ├── cassettes/           # VCR.py HTTP cassettes
 │   └── integration/         # Integration tests
+│       ├── __init__.py
 │       ├── README.md        # Integration test docs
-│       ├── conftest.py      # Test fixtures
+│       ├── conftest.py      # Integration test fixtures
 │       ├── validation.py    # Validation utilities
-│       └── test_*.py        # Integration test files
-├── docs/
+│       ├── test_agencies_integration.py
+│       ├── test_contracts_integration.py
+│       ├── test_entities_integration.py
+│       ├── test_forecasts_integration.py
+│       ├── test_grants_integration.py
+│       ├── test_notices_integration.py
+│       ├── test_opportunities_integration.py
+│       ├── test_reference_data_integration.py
+│       └── test_edge_cases_integration.py
+├── docs/                     # Documentation
+│   ├── API_REFERENCE.md     # Complete API reference
+│   ├── DEVELOPERS.md        # Developer guide
 │   ├── SHAPES.md            # Shape system guide
-│   ├── API_REFERENCE.md     # API reference
-│   └── DYNAMIC_MODELS.md    # Dynamic models docs
-└── pyproject.toml           # Project configuration
+│   └── quick_start.ipynb    # Interactive quick start
+├── scripts/                  # Utility scripts
+│   ├── README.md
+│   ├── fetch_api_schema.py
+│   └── generate_schemas_from_api.py
+├── pyproject.toml           # Project configuration
+├── uv.lock                  # Dependency lock file
+├── LICENSE                  # MIT License
+├── CHANGELOG.md            # Version history
+└── README.md               # This file
 ```
 
 ## Documentation
 
 - [Shape System Guide](docs/SHAPES.md) - Comprehensive guide to response shaping
 - [API Reference](docs/API_REFERENCE.md) - Detailed API documentation
-- [Dynamic Models](docs/DYNAMIC_MODELS.md) - Technical documentation on the dynamic model system
+- [Developer Guide](docs/DEVELOPERS.md) - Technical documentation for developers
+- [Quick Start Notebook](docs/quick_start.ipynb) - Interactive Jupyter notebook with examples
 
 ## Requirements
 

docs/API_REFERENCE.md

@@ -11,6 +11,7 @@ Complete reference for all Tango Python SDK methods and functionality.
 - [Forecasts](#forecasts)
 - [Opportunities](#opportunities)
 - [Notices](#notices)
+- [Grants](#grants)
 - [Business Types](#business-types)
 - [Response Objects](#response-objects)
 - [Error Handling](#error-handling)
@@ -461,6 +462,83 @@ for notice in notices.results:
 
 ---
 
+## Grants
+
+Federal grant opportunities and assistance listings.
+
+### list_grants()
+
+List grant opportunities.
+
+```python
+grants = client.list_grants(
+    page=1,
+    limit=25,
+    shape=None,
+    flat=False,
+    flat_lists=False,
+    # Additional filters
+    agency_code=None,
+)
+```
+
+**Parameters:**
+- `page` (int): Page number
+- `limit` (int): Results per page (max 100)
+- `shape` (str): Response shape string (defaults to minimal shape).
+               Use None to disable shaping, ShapeConfig.GRANTS_MINIMAL for minimal,
+               or provide custom shape string
+- `flat` (bool): Flatten nested objects in shaped response
+- `flat_lists` (bool): Flatten arrays using indexed keys
+- `agency_code` (str): Filter by agency code
+
+**Returns:** [PaginatedResponse](#paginatedresponse) with grant dictionaries
+
+**Example:**
+```python
+grants = client.list_grants(agency_code="HHS", limit=20)
+
+for grant in grants.results:
+    print(f"{grant['title']}")
+    print(f"Opportunity: {grant.get('opportunity_number', 'N/A')}")
+    print(f"Status: {grant.get('status', {}).get('description', 'N/A')}")
+```
+
+**Common Grant Fields:**
+- `grant_id` - Grant identifier
+- `opportunity_number` - Opportunity number
+- `title` - Grant title
+- `status` - Status information (nested object with code and description)
+- `agency_code` - Agency code
+- `description` - Description
+- `last_updated` - Last updated timestamp
+- `cfda_numbers` - CFDA numbers (list of objects with number and title)
+- `applicant_types` - Applicant types (list of objects with code and description)
+- `funding_categories` - Funding categories (list of objects with code and description)
+- `funding_instruments` - Funding instruments (list of objects with code and description)
+- `category` - Category (object with code and description)
+- `important_dates` - Important dates (list)
+- `attachments` - Attachments (list of objects)
+
+**Example with Expanded Fields:**
+```python
+# Get grants with expanded status and CFDA numbers
+grants = client.list_grants(
+    shape="grant_id,title,opportunity_number,status(*),cfda_numbers(number,title)",
+    limit=10
+)
+
+for grant in grants.results:
+    print(f"Grant: {grant['title']}")
+    if grant.get('status'):
+        print(f"Status: {grant['status'].get('description')}")
+    if grant.get('cfda_numbers'):
+        for cfda in grant['cfda_numbers']:
+            print(f"CFDA: {cfda.get('number')} - {cfda.get('title')}")
+```
+
+---
+
 ## Business Types
 
 Business type classifications.

tango/client.py

@@ -21,6 +21,7 @@
     Contract,
     Entity,
     Forecast,
+    Grant,
     Location,
     Notice,
     Opportunity,
@@ -749,3 +750,55 @@ def list_notices(
             previous=data.get("previous"),
             results=results,
         )
+
+    # Grant endpoints
+    def list_grants(
+        self,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+        **filters,
+    ) -> PaginatedResponse:
+        """
+        List grants
+
+        Args:
+            page: Page number
+            limit: Results per page (max 100)
+            shape: Response shape string (defaults to minimal shape).
+                   Use None to disable shaping, ShapeConfig.GRANTS_MINIMAL for minimal,
+                   or provide custom shape string
+            flat: If True, flatten nested objects in shaped response
+            flat_lists: If True, flatten arrays using indexed keys
+            **filters: Additional filter parameters
+        """
+        params = {"page": page, "limit": min(limit, 100)}
+
+        # Add shape parameter with default minimal shape
+        if shape is None:
+            shape = ShapeConfig.GRANTS_MINIMAL
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+            if flat_lists:
+                params["flat_lists"] = "true"
+
+        params.update(filters)
+
+        data = self._get("/api/grants/", params)
+
+        # Always use dynamic parsing
+        results = [
+            self._parse_response_with_shape(grant, shape, Grant, flat, flat_lists)
+            for grant in data["results"]
+        ]
+
+        return PaginatedResponse(
+            count=data["count"],
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=results,
+        )

tango/models.py

@@ -415,3 +415,6 @@ class ShapeConfig:
 
     # Default for list_notices()
     NOTICES_MINIMAL: Final = "notice_id,title,solicitation_number,posted_date"
+
+    # Default for list_grants()
+    GRANTS_MINIMAL: Final = "grant_id,opportunity_number,title,status(*),agency_code"

tango/shapes/explicit_schemas.py

@@ -588,6 +588,98 @@
 }
 
 
+# Nested schemas for Grant fields
+CFDA_NUMBER_SCHEMA: dict[str, FieldSchema] = {
+    "number": FieldSchema(name="number", type=str, is_optional=True, is_list=False),
+    "title": FieldSchema(name="title", type=str, is_optional=True, is_list=False),
+}
+
+CODE_DESCRIPTION_SCHEMA: dict[str, FieldSchema] = {
+    "code": FieldSchema(name="code", type=str, is_optional=True, is_list=False),
+    "description": FieldSchema(name="description", type=str, is_optional=True, is_list=False),
+}
+
+GRANT_ATTACHMENT_SCHEMA: dict[str, FieldSchema] = {
+    "attachment_id": FieldSchema(name="attachment_id", 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),
+    "posted_date": FieldSchema(name="posted_date", type=datetime, is_optional=True, is_list=False),
+    "resource_id": FieldSchema(name="resource_id", type=str, is_optional=True, is_list=False),
+    "type": FieldSchema(name="type", type=str, is_optional=True, is_list=False),
+    "url": FieldSchema(name="url", type=str, is_optional=True, is_list=False),
+}
+
+GRANT_SCHEMA: dict[str, FieldSchema] = {
+    "agency_code": FieldSchema(name="agency_code", type=str, is_optional=True, is_list=False),
+    "applicant_eligibility_description": FieldSchema(
+        name="applicant_eligibility_description", type=str, is_optional=True, is_list=False
+    ),
+    "description": FieldSchema(name="description", type=str, is_optional=True, is_list=False),
+    "funding_activity_category_description": FieldSchema(
+        name="funding_activity_category_description", type=str, is_optional=True, is_list=False
+    ),
+    "grant_id": FieldSchema(name="grant_id", type=int, is_optional=False, is_list=False),
+    "grantor_contact": FieldSchema(
+        name="grantor_contact", type=dict, is_optional=True, is_list=True
+    ),
+    "last_updated": FieldSchema(
+        name="last_updated", type=datetime, is_optional=True, is_list=False
+    ),
+    "opportunity_number": FieldSchema(
+        name="opportunity_number", type=str, is_optional=False, is_list=False
+    ),
+    "status": FieldSchema(
+        name="status", type=dict, is_optional=True, is_list=False, nested_model="CodeDescription"
+    ),
+    "title": FieldSchema(name="title", type=str, is_optional=False, is_list=False),
+    # Expanded fields
+    "cfda_numbers": FieldSchema(
+        name="cfda_numbers",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="CFDANumber",
+    ),
+    "applicant_types": FieldSchema(
+        name="applicant_types",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="CodeDescription",
+    ),
+    "category": FieldSchema(
+        name="category", type=dict, is_optional=True, is_list=False, nested_model="CodeDescription"
+    ),
+    "funding_categories": FieldSchema(
+        name="funding_categories",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="CodeDescription",
+    ),
+    "funding_details": FieldSchema(
+        name="funding_details", type=dict, is_optional=True, is_list=True
+    ),
+    "funding_instruments": FieldSchema(
+        name="funding_instruments",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="CodeDescription",
+    ),
+    "important_dates": FieldSchema(
+        name="important_dates", type=dict, is_optional=True, is_list=True
+    ),
+    "attachments": FieldSchema(
+        name="attachments",
+        type=dict,
+        is_optional=True,
+        is_list=True,
+        nested_model="GrantAttachment",
+    ),
+}
+
+
 # ============================================================================
 # SCHEMA REGISTRY MAPPING
 # ============================================================================
@@ -610,6 +702,11 @@
     "Opportunity": OPPORTUNITY_SCHEMA,
     "Notice": NOTICE_SCHEMA,
     "Agency": AGENCY_SCHEMA,
+    "Grant": GRANT_SCHEMA,
+    # Nested schemas for Grant fields
+    "CFDANumber": CFDA_NUMBER_SCHEMA,
+    "CodeDescription": CODE_DESCRIPTION_SCHEMA,
+    "GrantAttachment": GRANT_ATTACHMENT_SCHEMA,
 }
 
 

tango/shapes/factory.py

@@ -640,6 +640,18 @@ def _resolve_nested_model(self, nested_model: type | str) -> type:
             ModelInstantiationError: If model cannot be resolved
         """
         if isinstance(nested_model, str):
+            # First check if it's in the schema registry (for schema-only models)
+            schema = self.schema_registry.get_schema(nested_model)
+            if schema:
+                # Create a simple type to represent this schema-only model
+                # We'll use a dynamically created type that the schema registry can work with
+                class_name = nested_model
+                model_type = type(class_name, (object,), {"__name__": class_name})
+                # Register it with the schema registry if not already registered
+                if not self.schema_registry.is_registered(model_type):
+                    self.schema_registry._schemas[model_type] = schema
+                return model_type
+
             # Try to import the model from tango.models
             try:
                 from tango import models