tango-python 0.4.4__py3-none-any.whl → 0.6.0__py3-none-any.whl

tango/__init__.py

@@ -10,10 +10,13 @@ from .exceptions import (
 )
 from .models import (
     GsaElibraryContract,
+    ITDashboardInvestment,
     PaginatedResponse,
     RateLimitInfo,
     SearchFilters,
     ShapeConfig,
+    Vehicle,
+    VehicleMetrics,
     WebhookEndpoint,
     WebhookEventType,
     WebhookEventTypesResponse,
@@ -27,8 +30,14 @@ from .shapes import (
     ShapeParser,
     TypeGenerator,
 )
+from .webhooks import (
+    generate_signature,
+    parse_signature_header,
+    verify_signature,
+)
+from .webhooks.receiver import Delivery, WebhookReceiver
 
-__version__ = "0.4.3"
+__version__ = "0.6.0"
 __all__ = [
     "TangoClient",
     "TangoAPIError",
@@ -38,9 +47,12 @@ __all__ = [
     "TangoRateLimitError",
     "RateLimitInfo",
     "GsaElibraryContract",
+    "ITDashboardInvestment",
     "PaginatedResponse",
     "SearchFilters",
     "ShapeConfig",
+    "Vehicle",
+    "VehicleMetrics",
     "WebhookEndpoint",
     "WebhookEventType",
     "WebhookEventTypesResponse",
@@ -51,4 +63,9 @@ __all__ = [
     "ModelFactory",
     "TypeGenerator",
     "SchemaRegistry",
+    "Delivery",
+    "WebhookReceiver",
+    "generate_signature",
+    "parse_signature_header",
+    "verify_signature",
 ]

tango/client.py

@@ -1,6 +1,7 @@
 """Tango API Client"""
 
 import os
+import warnings
 from datetime import date, datetime
 from decimal import Decimal
 from typing import Any
@@ -26,6 +27,7 @@ from tango.models import (
     Forecast,
     Grant,
     GsaElibraryContract,
+    ITDashboardInvestment,
     Location,
     Notice,
     Opportunity,
@@ -122,6 +124,7 @@ class TangoClient:
     @staticmethod
     def _parse_rate_limit_headers(headers: httpx.Headers) -> RateLimitInfo:
         """Extract rate limit info from response headers."""
+
         def _int_or_none(val: str | None) -> int | None:
             if val is None:
                 return None
@@ -1336,10 +1339,150 @@ class TangoClient:
             data, shape, GsaElibraryContract, flat, flat_lists, joiner=joiner
         )
 
+    # ============================================================================
+    # IT Dashboard Investments
+    # ============================================================================
+
+    def list_itdashboard_investments(
+        self,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+        joiner: str = ".",
+        search: str | None = None,
+        agency_code: int | None = None,
+        agency_name: str | None = None,
+        type_of_investment: str | None = None,
+        updated_time_after: str | date | datetime | None = None,
+        updated_time_before: str | date | datetime | None = None,
+        cio_rating: int | None = None,
+        cio_rating_max: int | None = None,
+        performance_risk: bool | None = None,
+    ) -> PaginatedResponse:
+        """List federal IT investments from the IT Dashboard (`/api/itdashboard/`).
+
+        Filters are tier-gated by the API:
+
+        - **Free**: ``search`` (full-text across UII, title, description, agency, bureau)
+        - **Pro**: ``agency_code``, ``type_of_investment``,
+          ``updated_time_after`` / ``updated_time_before``
+        - **Business+**: ``agency_name`` (text), ``cio_rating``,
+          ``cio_rating_max``, ``performance_risk``
+
+        Hitting a gated filter on a lower tier returns a 403 with upgrade info.
+
+        CIO ratings: 1=High Risk, 2=Moderately High, 3=Medium, 4=Moderately Low, 5=Low.
+        ``performance_risk=True`` returns investments with at least one NOT MET metric.
+        """
+        params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+        if shape is None:
+            shape = ShapeConfig.ITDASHBOARD_INVESTMENTS_MINIMAL
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+                if joiner:
+                    params["joiner"] = joiner
+            if flat_lists:
+                params["flat_lists"] = "true"
+        for k, val in (
+            ("search", search),
+            ("agency_code", agency_code),
+            ("agency_name", agency_name),
+            ("type_of_investment", type_of_investment),
+            ("updated_time_after", updated_time_after),
+            ("updated_time_before", updated_time_before),
+            ("cio_rating", cio_rating),
+            ("cio_rating_max", cio_rating_max),
+            ("performance_risk", performance_risk),
+        ):
+            if val is None:
+                continue
+            if isinstance(val, bool):
+                params[k] = "true" if val else "false"
+            elif isinstance(val, (date, datetime)):
+                params[k] = val.isoformat()
+            else:
+                params[k] = val
+        data = self._get("/api/itdashboard/", params)
+        results = [
+            self._parse_response_with_shape(
+                obj, shape, ITDashboardInvestment, flat, flat_lists, joiner=joiner
+            )
+            for obj in data.get("results", [])
+        ]
+        return PaginatedResponse(
+            count=data.get("count", 0),
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=results,
+        )
+
+    def get_itdashboard_investment(
+        self,
+        uii: str,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+        joiner: str = ".",
+    ) -> Any:
+        """Get a single IT Dashboard investment by UII (`/api/itdashboard/{uii}/`)."""
+        params: dict[str, Any] = {}
+        if shape is None:
+            shape = ShapeConfig.ITDASHBOARD_INVESTMENTS_COMPREHENSIVE
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+                if joiner:
+                    params["joiner"] = joiner
+            if flat_lists:
+                params["flat_lists"] = "true"
+        data = self._get(f"/api/itdashboard/{uii}/", params)
+        return self._parse_response_with_shape(
+            data, shape, ITDashboardInvestment, flat, flat_lists, joiner=joiner
+        )
+
     # ============================================================================
     # Vehicles (Awards)
     # ============================================================================
 
+    @staticmethod
+    def _warn_deprecated_vehicle_shape(shape: str | None) -> None:
+        # Upstream sends `Deprecation: true` for these fields/expansions; warn
+        # callers who request them explicitly so they have time to migrate
+        # before tango publishes a Sunset timeline.
+        from tango.shapes.explicit_schemas import DEPRECATED_VEHICLE_SHAPE_FIELDS
+
+        if not shape:
+            return
+        # Match top-level field tokens, ignoring nesting inside parentheses.
+        depth = 0
+        token = ""
+        tokens: list[str] = []
+        for ch in shape:
+            if ch == "(":
+                depth += 1
+            elif ch == ")":
+                depth = max(0, depth - 1)
+            elif ch == "," and depth == 0:
+                tokens.append(token.strip())
+                token = ""
+                continue
+            token += ch
+        tokens.append(token.strip())
+        used = {t.split("(", 1)[0] for t in tokens} & DEPRECATED_VEHICLE_SHAPE_FIELDS
+        if used:
+            warnings.warn(
+                f"Vehicle shape field(s) {sorted(used)!r} are deprecated upstream "
+                "and may be removed in a future tango API version. The API currently "
+                "returns a `Deprecation: true` header for these.",
+                DeprecationWarning,
+                stacklevel=3,
+            )
+
     def list_vehicles(
         self,
         page: int = 1,
@@ -1349,12 +1492,46 @@ class TangoClient:
         flat_lists: bool = False,
         joiner: str = ".",
         search: str | None = None,
+        vehicle_type: str | None = None,
+        type_of_idc: str | None = None,
+        contract_type: str | None = None,
+        set_aside: str | None = None,
+        who_can_use: str | None = None,
+        naics_code: int | None = None,
+        psc_code: str | None = None,
+        program_acronym: str | None = None,
+        agency: str | None = None,
+        organization_id: str | None = None,
+        total_obligated_min: float | int | Decimal | None = None,
+        total_obligated_max: float | int | Decimal | None = None,
+        idv_count_min: int | None = None,
+        idv_count_max: int | None = None,
+        order_count_min: int | None = None,
+        order_count_max: int | None = None,
+        fiscal_year: int | None = None,
+        award_date_after: str | date | datetime | None = None,
+        award_date_before: str | date | datetime | None = None,
+        last_date_to_order_after: str | date | datetime | None = None,
+        last_date_to_order_before: str | date | datetime | None = None,
+        ordering: str | None = None,
     ) -> PaginatedResponse:
-        """List Vehicles (solicitation-centric groupings of IDVs)."""
+        """List Vehicles (solicitation-centric groupings of IDVs).
+
+        Multi-value filters (``vehicle_type``, ``type_of_idc``, ``contract_type``,
+        ``set_aside``) accept pipe-separated values for OR semantics, e.g.
+        ``vehicle_type="A|B|C"``.
+
+        ``ordering`` accepts: ``vehicle_obligations``, ``latest_award_date``,
+        ``total_obligated``, ``award_date``, ``last_date_to_order``,
+        ``fiscal_year``, ``idv_count``, ``order_count``. Prefix with ``-`` for
+        descending.
+        """
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
 
         if shape is None:
             shape = ShapeConfig.VEHICLES_MINIMAL
+        else:
+            self._warn_deprecated_vehicle_shape(shape)
         if shape:
             params["shape"] = shape
             if flat:
@@ -1364,8 +1541,37 @@ class TangoClient:
             if flat_lists:
                 params["flat_lists"] = "true"
 
-        if search:
-            params["search"] = search
+        for k, val in (
+            ("search", search),
+            ("vehicle_type", vehicle_type),
+            ("type_of_idc", type_of_idc),
+            ("contract_type", contract_type),
+            ("set_aside", set_aside),
+            ("who_can_use", who_can_use),
+            ("naics_code", naics_code),
+            ("psc_code", psc_code),
+            ("program_acronym", program_acronym),
+            ("agency", agency),
+            ("organization_id", organization_id),
+            ("total_obligated_min", total_obligated_min),
+            ("total_obligated_max", total_obligated_max),
+            ("idv_count_min", idv_count_min),
+            ("idv_count_max", idv_count_max),
+            ("order_count_min", order_count_min),
+            ("order_count_max", order_count_max),
+            ("fiscal_year", fiscal_year),
+            ("award_date_after", award_date_after),
+            ("award_date_before", award_date_before),
+            ("last_date_to_order_after", last_date_to_order_after),
+            ("last_date_to_order_before", last_date_to_order_before),
+            ("ordering", ordering),
+        ):
+            if val is None:
+                continue
+            if isinstance(val, (date, datetime)):
+                params[k] = val.isoformat()
+            else:
+                params[k] = val
 
         data = self._get("/api/vehicles/", params)
 
@@ -1397,6 +1603,8 @@ class TangoClient:
 
         if shape is None:
             shape = ShapeConfig.VEHICLES_COMPREHENSIVE
+        else:
+            self._warn_deprecated_vehicle_shape(shape)
         if shape:
             params["shape"] = shape
             if flat:
@@ -1424,8 +1632,14 @@ class TangoClient:
         flat: bool = False,
         flat_lists: bool = False,
         joiner: str = ".",
+        search: str | None = None,
     ) -> PaginatedResponse:
-        """List the IDV awardees for a Vehicle (`/api/vehicles/{uuid}/awardees/`)."""
+        """List the IDV awardees for a Vehicle (`/api/vehicles/{uuid}/awardees/`).
+
+        ``search`` runs entity-aware full-text search across IDV fields
+        (PIID, key, solicitation_identifier, NAICS, PSC, idv_type,
+        fiscal_year) and recipient entity details (name, address).
+        """
         params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
 
         if shape is None:
@@ -1439,6 +1653,9 @@ class TangoClient:
             if flat_lists:
                 params["flat_lists"] = "true"
 
+        if search:
+            params["search"] = search
+
         data = self._get(f"/api/vehicles/{uuid}/awardees/", params)
 
         results = [
@@ -1453,6 +1670,54 @@ class TangoClient:
             results=results,
         )
 
+    def list_vehicle_orders(
+        self,
+        uuid: str,
+        page: int = 1,
+        limit: int = 25,
+        shape: str | None = None,
+        flat: bool = False,
+        flat_lists: bool = False,
+        joiner: str = ".",
+        ordering: str | None = None,
+    ) -> PaginatedResponse:
+        """List task orders under a Vehicle's IDVs (``/api/vehicles/{uuid}/orders/``).
+
+        Args:
+            ordering: Server-side sort. Allowed: ``award_date`` (default),
+                ``obligated``, ``total_contract_value``. Prefix with ``-`` for
+                descending.
+        """
+        params: dict[str, Any] = {"page": page, "limit": min(limit, 100)}
+
+        if shape is None:
+            shape = ShapeConfig.VEHICLE_ORDERS_MINIMAL
+        if shape:
+            params["shape"] = shape
+            if flat:
+                params["flat"] = "true"
+                if joiner:
+                    params["joiner"] = joiner
+            if flat_lists:
+                params["flat_lists"] = "true"
+
+        if ordering:
+            params["ordering"] = ordering
+
+        data = self._get(f"/api/vehicles/{uuid}/orders/", params)
+
+        results = [
+            self._parse_response_with_shape(order, shape, Contract, flat, flat_lists, joiner=joiner)
+            for order in data["results"]
+        ]
+
+        return PaginatedResponse(
+            count=data["count"],
+            next=data.get("next"),
+            previous=data.get("previous"),
+            results=results,
+        )
+
     # Business Types endpoints
     def list_business_types(self, page: int = 1, limit: int = 25) -> PaginatedResponse:
         """List business types"""

tango/models.py

@@ -367,6 +367,45 @@ class GsaElibraryContract:
     sins: list[str] | None = None
 
 
+@dataclass
+class ITDashboardInvestment:
+    """Schema definition for IT Dashboard Investment (not used for instances)
+
+    Federal IT investment from itdashboard.gov, exposed at /api/itdashboard/.
+    Identified by ``uii`` (Unique Investment Identifier).
+
+    Tier-gated shape expansions:
+        Free        base fields only
+        Pro+        ``funding`` and ``details`` expansions
+        Business+   nested sub-tables (``cio_evaluation``, ``contracts``,
+                    ``projects``, ``cost_pools_towers``, ``funding_sources``,
+                    ``performance_metrics``, ``performance_actual``,
+                    ``operational_analysis``) and ``business_case_html``
+    """
+
+    uii: str
+    agency_code: int | None = None
+    agency_name: str | None = None
+    bureau_code: int | None = None
+    bureau_name: str | None = None
+    investment_title: str | None = None
+    type_of_investment: str | None = None
+    part_of_it_portfolio: str | None = None
+    updated_time: datetime | None = None
+    url: str | None = None
+    business_case_html: str | None = None
+    funding: dict[str, Any] | None = None
+    details: dict[str, Any] | None = None
+    cio_evaluation: list[dict[str, Any]] | None = None
+    contracts: list[dict[str, Any]] | None = None
+    projects: list[dict[str, Any]] | None = None
+    cost_pools_towers: list[dict[str, Any]] | None = None
+    funding_sources: list[dict[str, Any]] | None = None
+    performance_metrics: list[dict[str, Any]] | None = None
+    performance_actual: list[dict[str, Any]] | None = None
+    operational_analysis: list[dict[str, Any]] | None = None
+
+
 @dataclass
 class Vehicle:
     """Schema definition for Vehicle (not used for instances)"""
@@ -374,6 +413,12 @@ class Vehicle:
     uuid: str
     solicitation_identifier: str
     agency_id: str
+    is_synthetic_solicitation: bool | None = None
+    program_acronym: str | None = None
+    description: str | None = None
+    idv_count: int | None = None
+    total_obligated: Decimal | None = None
+    latest_award_date: date | None = None
     solicitation_title: str | None = None
     solicitation_date: date | None = None
     award_date: date | None = None
@@ -381,6 +426,24 @@ class Vehicle:
     fiscal_year: int | None = None
 
 
+@dataclass
+class VehicleMetrics:
+    """Schema definition for the Vehicle `metrics(*)` expansion (not used for instances)"""
+
+    avg_offers_received: float | None = None
+    award_concentration_hhi: float | None = None
+    order_concentration_hhi: float | None = None
+    competed_rate: float | None = None
+    using_agency_count: int | None = None
+    avg_order_value: float | None = None
+    max_order_value: float | None = None
+    top_recipient_share: float | None = None
+    recent_obligations_24mo: float | None = None
+    recent_orders_24mo: int | None = None
+    days_since_last_order: int | None = None
+    obligation_to_ceiling_ratio: float | None = None
+
+
 @dataclass
 class Entity:
     """Schema definition for Entity (not used for instances)"""
@@ -651,21 +714,34 @@ class ShapeConfig:
 
     # Default for list_vehicles()
     VEHICLES_MINIMAL: Final = (
-        "uuid,solicitation_identifier,organization_id,awardee_count,order_count,"
-        "vehicle_obligations,vehicle_contracts_value,solicitation_title,solicitation_date"
+        "uuid,solicitation_identifier,is_synthetic_solicitation,program_acronym,"
+        "organization_id,organization,vehicle_type,description,"
+        "idv_count,awardee_count,order_count,total_obligated,"
+        "vehicle_obligations,vehicle_contracts_value,latest_award_date,"
+        "solicitation_title,solicitation_date"
     )
 
     # Default for get_vehicle()
     VEHICLES_COMPREHENSIVE: Final = (
-        "uuid,solicitation_identifier,agency_id,organization_id,vehicle_type,who_can_use,"
-        "solicitation_title,solicitation_description,solicitation_date,naics_code,psc_code,set_aside,"
-        "fiscal_year,award_date,last_date_to_order,awardee_count,order_count,vehicle_obligations,vehicle_contracts_value,"
-        "type_of_idc,contract_type,competition_details(*)"
+        "uuid,solicitation_identifier,is_synthetic_solicitation,agency_id,program_acronym,"
+        "organization_id,organization(*),vehicle_type,who_can_use,"
+        "solicitation_title,solicitation_description,solicitation_date,opportunity_id,"
+        "naics_code,psc_code,set_aside,"
+        "fiscal_year,award_date,latest_award_date,last_date_to_order,"
+        "description,idv_count,awardee_count,order_count,total_obligated,"
+        "vehicle_obligations,vehicle_contracts_value,"
+        "type_of_idc,contract_type,metrics(*)"
     )
 
     # Default for list_vehicle_awardees()
     VEHICLE_AWARDEES_MINIMAL: Final = "uuid,key,piid,award_date,title,order_count,idv_obligations,idv_contracts_value,recipient(display_name,uei)"
 
+    # Default for list_vehicle_orders()
+    VEHICLE_ORDERS_MINIMAL: Final = (
+        "key,piid,award_date,obligated,total_contract_value,description,"
+        "recipient(display_name,uei)"
+    )
+
     # Default for list_organizations()
     ORGANIZATIONS_MINIMAL: Final = "key,fh_key,name,level,type,short_name"
 
@@ -687,3 +763,18 @@ class ShapeConfig:
     GSA_ELIBRARY_CONTRACTS_MINIMAL: Final = (
         "uuid,contract_number,schedule,recipient(display_name,uei),idv(key,award_date)"
     )
+
+    # Default for list_itdashboard_investments()
+    # Free-tier safe: matches the API's INVESTMENT_LIST_DEFAULT_SHAPE.
+    ITDASHBOARD_INVESTMENTS_MINIMAL: Final = (
+        "uii,agency_name,bureau_name,investment_title,"
+        "type_of_investment,part_of_it_portfolio,updated_time,url"
+    )
+
+    # Default for get_itdashboard_investment()
+    # Free-tier safe: matches the API's INVESTMENT_RETRIEVE_DEFAULT_SHAPE.
+    ITDASHBOARD_INVESTMENTS_COMPREHENSIVE: Final = (
+        "uii,agency_code,agency_name,bureau_code,bureau_name,"
+        "investment_title,type_of_investment,part_of_it_portfolio,"
+        "updated_time,url"
+    )