tango-python 0.2.0__tar.gz → 0.4.0__tar.gz

{tango_python-0.2.0 → tango_python-0.4.0}/.github/workflows/lint.yml

@@ -12,6 +12,12 @@ jobs:
     
     steps:
     - uses: actions/checkout@v4
+
+    - name: Checkout tango API repo (manifest source)
+      uses: actions/checkout@v4
+      with:
+        repository: makegov/tango
+        path: tango-api
     
     - name: Install uv
       uses: astral-sh/setup-uv@v4
@@ -29,3 +35,6 @@ jobs:
     
     - name: Lint with ruff
       run: uv run ruff check tango/
+
+    - name: Check SDK filter/shape conformance
+      run: uv run python scripts/check_filter_shape_conformance.py --manifest tango-api/contracts/filter_shape_contract.json

{tango_python-0.2.0 → tango_python-0.4.0}/.github/workflows/publish.yml

@@ -3,6 +3,7 @@ name: Publish to PyPI
 on:
   release:
     types: [published]
+  workflow_dispatch:
 
 jobs:
   build-and-publish:
@@ -24,5 +25,5 @@ jobs:
     
     - name: Publish to PyPI
       env:
-        UV_PUBLISH_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+        UV_PUBLISH_TOKEN: ${{ secrets.TANGO_PYPI_TOKEN }}
       run: uv publish

{tango_python-0.2.0 → tango_python-0.4.0}/.gitignore

@@ -145,4 +145,8 @@ dmypy.json
 .DS_Store
 Thumbs.db
 
-.cursor/*
+# Other
+yoni/
+.cursor/*
+
+examples/

tango_python-0.4.0/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.4.0] - 2026-02-24
+
+### Added
+- Offices, Organizations, OTAs, OTIDVs, Subawards, NAICS, and Assistance endpoints.
+- Filter/shape conformance tooling and documentation.
+
+### Changed
+- CI lint workflow runs filter/shape conformance when the manifest is available.
+
+## [0.3.0] - 2026-02-09
+
+### Added
+- Vehicles endpoints: `list_vehicles`, `get_vehicle`, and `list_vehicle_awardees` (supports shaping + flattening). (refs `makegov/tango#1328`)
+- IDV endpoints: `list_idvs`, `get_idv`, `list_idv_awards`, `list_idv_child_idvs`, `list_idv_transactions`, `get_idv_summary`, `list_idv_summary_awards`. (refs `makegov/tango#1328`)
+- Webhooks v2 client support: event type discovery, subscription CRUD, endpoint management, test delivery, and sample payload helpers. (refs `makegov/tango#1274`)
+
+### Changed
+- Expanded explicit schemas to support common IDV shaping expansions (award offices, officers, period of performance, etc.).
+- HTTP client now supports PATCH/DELETE helpers for webhook management endpoints.
+
+## [0.2.0] - 2025-11-16
+
+- Entirely refactored SDK

{tango_python-0.2.0 → tango_python-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tango-python
-Version: 0.2.0
+Version: 0.4.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
@@ -61,7 +61,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, grants) [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, webhooks) [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
@@ -487,8 +487,10 @@ tango-python/
 │   └── quick_start.ipynb    # Interactive quick start
 ├── scripts/                  # Utility scripts
 │   ├── README.md
+│   ├── check_filter_shape_conformance.py  # Filter + shape conformance (CI)
 │   ├── fetch_api_schema.py
-│   └── generate_schemas_from_api.py
+│   ├── generate_schemas_from_api.py
+│   └── pr_review.py          # PR validation (lint, types, tests, conformance)
 ├── pyproject.toml           # Project configuration
 ├── uv.lock                  # Dependency lock file
 ├── LICENSE                  # MIT License
@@ -526,7 +528,12 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Run tests (`uv run pytest`)
-4. Commit your changes (`git commit -m 'Add amazing feature'`)
-5. Push to the branch (`git push origin feature/amazing-feature`)
-6. Open a Pull Request
+3. Run lint and format: `uv run ruff format tango/ && uv run ruff check tango/`
+4. Run type checking: `uv run mypy tango/`
+5. Run tests: `uv run pytest`
+6. (Optional) Run [filter and shape conformance](scripts/README.md#filter-and-shape-conformance) if you have the tango API manifest; CI will run it on push/PR
+7. Commit your changes (`git commit -m 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+For a single command that runs formatting, linting, type checking, and tests (and conformance when the manifest is present), use: `uv run python scripts/pr_review.py --mode full`

{tango_python-0.2.0 → tango_python-0.4.0}/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, grants) [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, webhooks) [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
@@ -432,8 +432,10 @@ tango-python/
 │   └── quick_start.ipynb    # Interactive quick start
 ├── scripts/                  # Utility scripts
 │   ├── README.md
+│   ├── check_filter_shape_conformance.py  # Filter + shape conformance (CI)
 │   ├── fetch_api_schema.py
-│   └── generate_schemas_from_api.py
+│   ├── generate_schemas_from_api.py
+│   └── pr_review.py          # PR validation (lint, types, tests, conformance)
 ├── pyproject.toml           # Project configuration
 ├── uv.lock                  # Dependency lock file
 ├── LICENSE                  # MIT License
@@ -471,7 +473,12 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Run tests (`uv run pytest`)
-4. Commit your changes (`git commit -m 'Add amazing feature'`)
-5. Push to the branch (`git push origin feature/amazing-feature`)
-6. Open a Pull Request
+3. Run lint and format: `uv run ruff format tango/ && uv run ruff check tango/`
+4. Run type checking: `uv run mypy tango/`
+5. Run tests: `uv run pytest`
+6. (Optional) Run [filter and shape conformance](scripts/README.md#filter-and-shape-conformance) if you have the tango API manifest; CI will run it on push/PR
+7. Commit your changes (`git commit -m 'Add amazing feature'`)
+8. Push to the branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+For a single command that runs formatting, linting, type checking, and tests (and conformance when the manifest is present), use: `uv run python scripts/pr_review.py --mode full`

tango_python-0.4.0/ROADMAP.md

@@ -0,0 +1,22 @@
+# ROADMAP
+
+## Now
+
+- [X] Align existing API to the SDK
+- [ ] Better Filter DX
+    - [ ] Dataclasses for search validation and typing
+- [ ] Docs improvements
+    - [ ] Document each endpoint separately to allow for easier information
+    - [ ] Some more targeted examples
+
+## Next
+
+- Better support for MCPs
+
+## Later
+
+- 
+
+## Maybe Someday
+
+- CLI support

{tango_python-0.2.0 → tango_python-0.4.0}/docs/API_REFERENCE.md

@@ -7,13 +7,17 @@ Complete reference for all Tango Python SDK methods and functionality.
 - [Client Initialization](#client-initialization)
 - [Agencies](#agencies)
 - [Contracts](#contracts)
+- [IDVs](#idvs)
+- [Vehicles](#vehicles)
 - [Entities](#entities)
 - [Forecasts](#forecasts)
 - [Opportunities](#opportunities)
 - [Notices](#notices)
 - [Grants](#grants)
 - [Business Types](#business-types)
+- [Webhooks](#webhooks)
 - [Response Objects](#response-objects)
+- [ShapeConfig (predefined shapes)](#shapeconfig-predefined-shapes)
 - [Error Handling](#error-handling)
 
 ## Client Initialization
@@ -271,6 +275,119 @@ contracts = client.list_contracts(
 
 ---
 
+## Vehicles
+
+Vehicles provide a solicitation-centric way to discover groups of related IDVs and (optionally) expand into the underlying awards via shaping.
+
+### list_vehicles()
+
+List vehicles with optional vehicle-level full-text search.
+
+```python
+vehicles = client.list_vehicles(
+    page=1,
+    limit=25,
+    search="GSA schedule",
+    shape=ShapeConfig.VEHICLES_MINIMAL,
+    flat=False,
+    flat_lists=False,
+)
+```
+
+**Parameters:**
+- `page` (int): Page number (default: 1)
+- `limit` (int): Results per page (default: 25, max: 100)
+- `search` (str, optional): Vehicle-level search term
+- `shape` (str, optional): Shape string (defaults to `ShapeConfig.VEHICLES_MINIMAL`)
+- `flat` (bool): Flatten nested objects in shaped response
+- `flat_lists` (bool): Flatten arrays using indexed keys
+- `joiner` (str): Joiner used when `flat=True` (default: `"."`)
+
+**Returns:** [PaginatedResponse](#paginatedresponse) with vehicle dictionaries
+
+### get_vehicle()
+
+Get a single vehicle by UUID.
+
+```python
+vehicle = client.get_vehicle(
+    uuid="00000000-0000-0000-0000-000000000001",
+    shape=ShapeConfig.VEHICLES_COMPREHENSIVE,
+)
+```
+
+**Notes:**
+- On the vehicle detail endpoint, `search` filters **expanded awardees** when your `shape` includes `awardees(...)` (it does not filter the vehicle itself).
+
+### list_vehicle_awardees()
+
+List the IDV awardees for a vehicle.
+
+```python
+awardees = client.list_vehicle_awardees(
+    uuid="00000000-0000-0000-0000-000000000001",
+    shape=ShapeConfig.VEHICLE_AWARDEES_MINIMAL,
+)
+```
+
+---
+
+## IDVs
+
+IDVs (indefinite delivery vehicles) are the parent “vehicle award” records that can have child awards/orders under them.
+
+### list_idvs()
+
+```python
+idvs = client.list_idvs(
+    limit=25,
+    cursor=None,
+    shape=ShapeConfig.IDVS_MINIMAL,
+    awarding_agency="4700",
+)
+```
+
+Notes:
+
+- This endpoint uses **keyset pagination** (`cursor` + `limit`) rather than page numbers.
+
+### get_idv()
+
+```python
+idv = client.get_idv("SOME_IDV_KEY", shape=ShapeConfig.IDVS_COMPREHENSIVE)
+```
+
+### list_idv_awards()
+
+Lists child awards (contracts) under an IDV.
+
+```python
+awards = client.list_idv_awards("SOME_IDV_KEY", limit=25)
+```
+
+### list_idv_child_idvs()
+
+Lists child IDVs under an IDV.
+
+```python
+children = client.list_idv_child_idvs("SOME_IDV_KEY", limit=25)
+```
+
+### list_idv_transactions()
+
+```python
+tx = client.list_idv_transactions("SOME_IDV_KEY", limit=100)
+```
+
+### get_idv_summary() / list_idv_summary_awards()
+
+```python
+summary = client.get_idv_summary("SOLICITATION_IDENTIFIER")
+awards = client.list_idv_summary_awards("SOLICITATION_IDENTIFIER", limit=25)
+```
+
+---
+
 ## Entities
 
 Vendors, recipients, and organizations doing business with the government.
@@ -606,6 +723,135 @@ for biz_type in business_types.results:
 
 ---
 
+## Webhooks
+
+Webhook APIs let **Large / Enterprise** users manage subscription filters for outbound Tango webhooks.
+
+### list_webhook_event_types()
+
+Discover supported `event_type` values and subject types.
+
+```python
+info = client.list_webhook_event_types()
+print(info.event_types[0].event_type)
+```
+
+### list_webhook_subscriptions()
+
+```python
+subs = client.list_webhook_subscriptions(page=1, page_size=25)
+```
+
+Notes:
+
+- This endpoint uses `page` + `page_size` (tier-capped) rather than `limit`.
+
+### create_webhook_subscription()
+
+```python
+sub = client.create_webhook_subscription(
+    "Track specific vendors",
+    {
+        "records": [
+            {"event_type": "awards.new_award", "subject_type": "entity", "subject_ids": ["UEI123ABC"]},
+            {"event_type": "awards.new_transaction", "subject_type": "entity", "subject_ids": ["UEI123ABC"]},
+        ]
+    },
+)
+```
+
+Notes:
+
+- Prefer v2 fields: `subject_type` + `subject_ids`.
+- Legacy compatibility: `resource_ids` is accepted as an alias for `subject_ids` (don’t send both).
+- Catch-all: `subject_ids: []` means “all subjects” for that record and is **Enterprise-only**. Large tier users must list specific IDs.
+
+### update_webhook_subscription()
+
+```python
+sub = client.update_webhook_subscription("SUBSCRIPTION_UUID", subscription_name="Updated name")
+```
+
+### delete_webhook_subscription()
+
+```python
+client.delete_webhook_subscription("SUBSCRIPTION_UUID")
+```
+
+### list_webhook_endpoints()
+
+List your webhook endpoint(s).
+
+```python
+endpoints = client.list_webhook_endpoints(page=1, limit=25)
+```
+
+### get_webhook_endpoint()
+
+```python
+endpoint = client.get_webhook_endpoint("ENDPOINT_UUID")
+```
+
+### create_webhook_endpoint() / update_webhook_endpoint() / delete_webhook_endpoint()
+
+In production, MakeGov provisions the initial endpoint for you. These are most useful for dev/self-service.
+
+```python
+endpoint = client.create_webhook_endpoint("https://example.com/tango/webhooks")
+endpoint = client.update_webhook_endpoint(endpoint.id, is_active=False)
+client.delete_webhook_endpoint(endpoint.id)
+```
+
+### test_webhook_delivery()
+
+Send an immediate test webhook to your configured endpoint.
+
+```python
+result = client.test_webhook_delivery()
+print(result.success, result.status_code)
+```
+
+### get_webhook_sample_payload()
+
+Fetch Tango-shaped sample deliveries (and sample subscription request bodies).
+
+```python
+sample = client.get_webhook_sample_payload(event_type="awards.new_award")
+print(sample["event_type"])
+```
+
+### Deliveries / redelivery
+
+The API does not currently expose a public `/api/webhooks/deliveries/` or redelivery endpoint. Use:
+
+- `test_webhook_delivery()` for connectivity checks
+- `get_webhook_sample_payload()` for building handlers + subscription payloads
+
+### Receiving webhooks (signature verification)
+
+Every delivery includes an HMAC signature header:
+
+- `X-Tango-Signature: sha256=<hex digest>`
+
+Compute the digest over the **raw request body bytes** using your shared secret.
+
+```python
+import hashlib
+import hmac
+
+
+def verify_tango_webhook_signature(secret: str, raw_body: bytes, signature_header: str | None) -> bool:
+    if not signature_header:
+        return False
+    sig = signature_header.strip()
+    if sig.startswith("sha256="):
+        sig = sig[len("sha256=") :]
+    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, sig)
+```
+
+---
+
 ## Response Objects
 
 ### PaginatedResponse
@@ -659,6 +905,48 @@ print(f"Total collected: {len(all_results)} results")
 
 ---
 
+## ShapeConfig (predefined shapes)
+
+The SDK provides predefined shape strings as constants on `ShapeConfig`. Use them as the `shape` argument for list/get methods when you want a consistent, validated set of fields without building a custom shape string.
+
+```python
+from tango import TangoClient, ShapeConfig
+
+client = TangoClient()
+
+# List methods default to the minimal shape when shape is omitted
+contracts = client.list_contracts(limit=10)  # uses CONTRACTS_MINIMAL
+
+# Or pass the constant explicitly
+contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10)
+entity = client.get_entity("UEI_KEY", shape=ShapeConfig.ENTITIES_COMPREHENSIVE)
+```
+
+**Available constants (by resource):**
+
+| Constant | Used by | Description |
+|----------|---------|-------------|
+| `CONTRACTS_MINIMAL` | `list_contracts`, `search_contracts` | key, piid, award_date, recipient(display_name), description, total_contract_value |
+| `ENTITIES_MINIMAL` | `list_entities` | uei, legal_business_name, cage_code, business_types |
+| `ENTITIES_COMPREHENSIVE` | `get_entity` | Full entity profile (addresses, naics, psc, obligations, etc.) |
+| `FORECASTS_MINIMAL` | `list_forecasts` | id, title, anticipated_award_date, fiscal_year, naics_code, status |
+| `OPPORTUNITIES_MINIMAL` | `list_opportunities` | opportunity_id, title, solicitation_number, response_deadline, active |
+| `NOTICES_MINIMAL` | `list_notices` | notice_id, title, solicitation_number, posted_date |
+| `GRANTS_MINIMAL` | `list_grants` | grant_id, opportunity_number, title, status(*), agency_code |
+| `IDVS_MINIMAL` | `list_idvs`, `list_vehicle_awardees` | key, piid, award_date, recipient(display_name,uei), description, total_contract_value, obligated, idv_type |
+| `IDVS_COMPREHENSIVE` | `get_idv` | Full IDV with offices, place_of_performance, competition, transactions, etc. |
+| `VEHICLES_MINIMAL` | `list_vehicles` | uuid, solicitation_identifier, organization_id, awardee_count, order_count, vehicle_obligations, vehicle_contracts_value, solicitation_title, solicitation_date |
+| `VEHICLES_COMPREHENSIVE` | `get_vehicle` | Full vehicle with competition_details, fiscal_year, set_aside, etc. |
+| `VEHICLE_AWARDEES_MINIMAL` | `list_vehicle_awardees` | uuid, key, piid, award_date, title, order_count, idv_obligations, idv_contracts_value, recipient(display_name,uei) |
+| `ORGANIZATIONS_MINIMAL` | `list_organizations`, `list_organization_offices` | key, fh_key, name, level, type, short_name |
+| `OTAS_MINIMAL` | `list_otas` | key, piid, award_date, recipient(display_name,uei), description, total_contract_value, obligated |
+| `OTIDVS_MINIMAL` | `list_otidvs` | key, piid, award_date, recipient(display_name,uei), description, total_contract_value, obligated, idv_type |
+| `SUBAWARDS_MINIMAL` | `list_subawards` | award_key, prime_recipient(uei,display_name), subaward_recipient(uei,display_name) |
+
+All predefined shapes are validated at SDK release time (see [Developer Guide](DEVELOPERS.md#sdk-conformance-maintainers)). For custom shapes, see the [Shaping Guide](SHAPES.md).
+
+---
+
 ## Error Handling
 
 The SDK provides specific exception types for different error scenarios.
@@ -849,7 +1137,8 @@ client = TangoClient()
 
 ## Additional Resources
 
-- [Shaping Guide](SHAPES.md) - Comprehensive guide to response shaping
+- [Shaping Guide](SHAPES.md) - Response shaping syntax, examples, and field reference
+- [Developer Guide](DEVELOPERS.md) - Dynamic models, predefined shapes, and SDK conformance (maintainers)
 - [Quick Start](quick_start.ipynb) - Interactive notebook with examples
 - [GitHub Repository](https://github.com/makegov/tango-python) - Source code and examples
 - [Tango API Documentation](https://tango.makegov.com/docs) - Full API documentation

{tango_python-0.2.0 → tango_python-0.4.0}/docs/DEVELOPERS.md

@@ -12,6 +12,7 @@ The Tango SDK uses dynamic models that generate runtime types matching the exact
 - [Type Hints and IDE Support](#type-hints-and-ide-support)
 - [Performance Considerations](#performance-considerations)
 - [Troubleshooting](#troubleshooting)
+- [SDK conformance (maintainers)](#sdk-conformance-maintainers)
 
 ## Overview
 
@@ -623,6 +624,32 @@ If you encounter issues:
 3. See [examples/](../examples/) for working code samples
 4. Contact support at [tango@makegov.com](mailto:tango@makegov.com)
 
+## SDK conformance (maintainers)
+
+The SDK is kept in sync with the Tango API and its own shape schemas via two conformance checks. Both run in CI on every push and PR (see [Lint workflow](../.github/workflows/lint.yml)) and can be run locally with [scripts/check_filter_shape_conformance.py](../scripts/check_filter_shape_conformance.py).
+
+### Filter conformance
+
+- **What it checks:** Every list/get endpoint in the canonical manifest (from the [tango](https://github.com/makegov/tango) API repo) has a matching SDK method that exposes the manifest’s filter parameters—either as explicit arguments or via the method’s `api_param_mapping`.
+- **Why it matters:** Ensures the SDK supports all query filters the API exposes for each resource, so users can filter without relying on undocumented `**kwargs`.
+- **Warnings:** Methods that take filters only via `**kwargs` are reported as warnings (filter names cannot be verified against the manifest).
+
+### Shape conformance
+
+- **What it checks:** Every predefined shape in `ShapeConfig` (e.g. `CONTRACTS_MINIMAL`, `IDVS_MINIMAL`, `GRANTS_MINIMAL`) is parsed and validated against the SDK’s explicit schemas in `tango/shapes/explicit_schemas.py`. Each shape must only reference fields that exist for that model (including nested fields).
+- **Why it matters:** Ensures default shapes never reference invalid or renamed fields, so default list/get behavior stays valid after schema or API changes.
+- **Errors:** Parse failures or invalid field names in any `ShapeConfig` constant are reported as errors and fail the check.
+
+### Running the conformance check
+
+- **In CI:** The [Lint workflow](../.github/workflows/lint.yml) runs the full check automatically (it has access to the manifest). No setup needed for push/PR.
+- **Locally:** You need the manifest file to run the script. If you have it (e.g. a path to `filter_shape_contract.json` from the [tango](https://github.com/makegov/tango) repo—wherever you keep that repo—or from a colleague), run:
+  ```bash
+  uv run python scripts/check_filter_shape_conformance.py --manifest /path/to/filter_shape_contract.json
+  ```
+  If you don’t have the manifest, CI will still run the full check on your branch; shape conformance is included whenever the script runs.
+- **Output:** JSON with `errors` and `warnings`. Exit code 1 if there are any errors. See [scripts/README.md](../scripts/README.md#filter-and-shape-conformance) for full usage and `--list-missing`.
+
 ## Next Steps
 
 - Read the [API Reference](API_REFERENCE.md) for detailed class and method documentation

{tango_python-0.2.0 → tango_python-0.4.0}/docs/SHAPES.md

@@ -2,6 +2,8 @@
 
 Response shaping lets you control which fields the API returns, making your requests faster and more efficient. Instead of receiving hundreds of fields you don't need, you specify exactly what you want.
 
+**See also:** [API Reference](API_REFERENCE.md) for method parameters and [ShapeConfig (predefined shapes)](API_REFERENCE.md#shapeconfig-predefined-shapes); [Developer Guide](DEVELOPERS.md) for dynamic models and maintainer conformance.
+
 ## Why Use Response Shaping?
 
 **Performance Benefits:**
@@ -27,11 +29,36 @@ contracts = client.list_contracts(
     shape="key,piid,recipient(display_name),total_contract_value"
 )
 
+# Or use a predefined shape constant
+from tango import ShapeConfig
+contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10)
+
 # Access the data
 for contract in contracts.results:
     print(f"{contract['piid']}: {contract['recipient']['display_name']}")
 ```
 
+## Predefined shapes (ShapeConfig)
+
+Instead of writing shape strings by hand, you can use the SDK’s predefined constants. Each list/get method has a default minimal shape when you omit `shape`; you can also pass a constant explicitly.
+
+```python
+from tango import TangoClient, ShapeConfig
+
+client = TangoClient()
+
+# These are equivalent (list_contracts defaults to CONTRACTS_MINIMAL)
+contracts = client.list_contracts(limit=10)
+contracts = client.list_contracts(shape=ShapeConfig.CONTRACTS_MINIMAL, limit=10)
+
+# Other resources
+entities = client.list_entities(shape=ShapeConfig.ENTITIES_MINIMAL)
+idvs = client.list_idvs(shape=ShapeConfig.IDVS_MINIMAL)
+grants = client.list_grants(shape=ShapeConfig.GRANTS_MINIMAL)
+```
+
+**Available constants:** Contracts (`CONTRACTS_MINIMAL`), Entities (`ENTITIES_MINIMAL`, `ENTITIES_COMPREHENSIVE`), Forecasts, Opportunities, Notices, Grants, IDVs, Vehicles, Organizations, OTAs, OTIDVs, Subawards. See [API Reference – ShapeConfig](API_REFERENCE.md#shapeconfig-predefined-shapes) for the full table and which method uses which constant.
+
 ## Basic Shaping
 
 ### Simple Fields
@@ -455,5 +482,6 @@ display_name = contract.get('recipient', {}).get('display_name', 'Unknown')
 - **Define patterns** - Create reusable shapes for your common queries
 
 For more help, see:
-- [Quick Start Guide](quick_start.ipynb) - Interactive examples
-- [API Reference](API_REFERENCE.md) - Complete field listings
+- [API Reference](API_REFERENCE.md) - Method parameters, [ShapeConfig table](API_REFERENCE.md#shapeconfig-predefined-shapes), and field context
+- [Developer Guide](DEVELOPERS.md) - Dynamic models, predefined shapes in depth, and SDK conformance (for maintainers)
+- [Quick Start Guide](quick_start.ipynb) - Interactive examples

{tango_python-0.2.0 → tango_python-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tango-python"
-version = "0.2.0"
+version = "0.4.0"
 description = "Python SDK for the Tango API"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -97,6 +97,7 @@ markers = [
     "live: Tests that always use live API (skip cassettes)",
     "cached: Tests that only run with cached responses",
     "slow: Tests that are slow to execute",
+    "production: Production API smoke tests that run against live API",
 ]
 
 [tool.coverage.run]