usaspending-orm 0.6.0__py3-none-any.whl

usaspending/models/funding.py

@@ -0,0 +1,182 @@
+"""Funding model for USASpending data."""
+
+from __future__ import annotations
+
+from typing import Dict, Any, Optional, TYPE_CHECKING
+from decimal import Decimal
+
+from .base_model import BaseModel
+from ..utils.formatter import to_decimal, round_to_millions
+
+if TYPE_CHECKING:
+    from .agency import Agency
+
+
+class Funding(BaseModel):
+    """Represents federal account funding data for an award."""
+
+    def __init__(self, data: Dict[str, Any]):
+        """Initialize Funding instance.
+
+        Args:
+            data: Raw funding data from API response
+        """
+        super().__init__(data)
+
+    @property
+    def transaction_obligated_amount(self) -> Optional[Decimal]:
+        """Amount obligated for this funding record."""
+        return to_decimal(self.get_value("transaction_obligated_amount", default=0.0))
+
+    @property
+    def gross_outlay_amount(self) -> Optional[Decimal]:
+        """Gross outlay amount for this funding record."""
+        return to_decimal(self.get_value("gross_outlay_amount", default=0.0))
+
+    @property
+    def disaster_emergency_fund_code(self) -> Optional[str]:
+        """Code indicating whether funding is associated with a disaster."""
+        return self.get_value("disaster_emergency_fund_code")
+
+    @property
+    def federal_account(self) -> Optional[str]:
+        """Identifier of the federal account."""
+        return self.get_value("federal_account")
+
+    @property
+    def account_title(self) -> Optional[str]:
+        """Federal account title."""
+        return self.get_value("account_title")
+
+    @property
+    def funding_agency_name(self) -> Optional[str]:
+        """Name of the funding agency."""
+        return self.get_value("funding_agency_name")
+
+    @property
+    def funding_agency_id(self) -> Optional[int]:
+        """Internal surrogate identifier of the funding agency."""
+        value = self.get_value("funding_agency_id")
+        return int(value) if value is not None else None
+
+    @property
+    def funding_toptier_agency_id(self) -> Optional[int]:
+        """Top-tier funding agency identifier."""
+        value = self.get_value("funding_toptier_agency_id")
+        return int(value) if value is not None else None
+
+    @property
+    def funding_agency_slug(self) -> Optional[str]:
+        """URL-friendly funding agency identifier."""
+        return self.get_value("funding_agency_slug")
+
+    @property
+    def funding_agency(self) -> Optional["Agency"]:
+        """Retrieve the full Agency object for the funding agency."""
+        name = self.funding_agency_name
+        if name:
+            return self._client.agencies.find_all_funding_agencies_by_name(
+                name
+            ).toptier()[0]
+        else:
+            return None
+
+    @property
+    def awarding_agency_name(self) -> Optional[str]:
+        """Name of the awarding agency."""
+        return self.get_value("awarding_agency_name")
+
+    @property
+    def awarding_agency_id(self) -> Optional[int]:
+        """Internal surrogate identifier of the awarding agency."""
+        value = self.get_value("awarding_agency_id")
+        return int(value) if value is not None else None
+
+    @property
+    def awarding_toptier_agency_id(self) -> Optional[int]:
+        """Top-tier awarding agency identifier."""
+        value = self.get_value("awarding_toptier_agency_id")
+        return int(value) if value is not None else None
+
+    @property
+    def awarding_agency_slug(self) -> Optional[str]:
+        """URL-friendly awarding agency identifier."""
+        return self.get_value("awarding_agency_slug")
+
+    @property
+    def awarding_agency(self) -> Optional["Agency"]:
+        """Retrieve the full Agency object for the funding agency."""
+        name = self.awarding_agency_name
+        if name:
+            return self._client.agencies.find_all_awarding_agencies_by_name(
+                name
+            ).toptier()[0]
+        else:
+            return None
+
+    @property
+    def object_class(self) -> Optional[str]:
+        """Object class code."""
+        return self.get_value("object_class")
+
+    @property
+    def object_class_name(self) -> Optional[str]:
+        """Object class name/description."""
+        return self.get_value("object_class_name")
+
+    @property
+    def program_activity_code(self) -> Optional[str]:
+        """Program activity code."""
+        return self.get_value("program_activity_code")
+
+    @property
+    def program_activity_name(self) -> Optional[str]:
+        """Program activity name."""
+        return self.get_value("program_activity_name")
+
+    @property
+    def reporting_fiscal_year(self) -> Optional[int]:
+        """Fiscal year of the submission date."""
+        value = self.get_value("reporting_fiscal_year")
+        return int(value) if value is not None else None
+
+    @property
+    def reporting_fiscal_quarter(self) -> Optional[int]:
+        """Fiscal quarter of the submission date."""
+        value = self.get_value("reporting_fiscal_quarter")
+        return int(value) if value is not None else None
+
+    @property
+    def reporting_fiscal_month(self) -> Optional[int]:
+        """Fiscal month of the submission date."""
+        value = self.get_value("reporting_fiscal_month")
+        return int(value) if value is not None else None
+
+    @property
+    def is_quarterly_submission(self) -> Optional[bool]:
+        """True if submission is quarterly, False if monthly."""
+        return self.get_value("is_quarterly_submission")
+
+    def __repr__(self) -> str:
+        """String representation of Funding."""
+        year = self.reporting_fiscal_year or "?"
+        month = self.reporting_fiscal_month
+
+        # Format month with zero padding if it's a number
+        if month is not None:
+            month_str = f"{month:02d}"
+        else:
+            month_str = "?"
+
+        if self.transaction_obligated_amount:
+            amount = self.transaction_obligated_amount
+            amount_str = f"OBL: {round_to_millions(amount)}"
+        elif self.gross_outlay_amount:
+            amount = self.gross_outlay_amount
+            amount_str = f"OUTLAY: {round_to_millions(amount)}"
+        else:
+            amount_str = "?"
+
+        agency = self.funding_agency_name or "Unknown Agency"
+
+        return f"<Funding {year}-{month_str} {agency} {amount_str}>"

usaspending/models/grant.py

@@ -0,0 +1,147 @@
+"""Grant award model for USASpending data."""
+
+from __future__ import annotations
+from typing import Dict, Any, Optional, List, TYPE_CHECKING
+from functools import cached_property
+from decimal import Decimal
+
+from .award import Award
+from ..utils.formatter import to_decimal
+
+if TYPE_CHECKING:
+    from ..queries.subawards_search import SubAwardsSearch
+
+
+class Grant(Award):
+    """Grant and assistance award types."""
+
+    TYPE_FIELDS = [
+        "fain",
+        "uri",
+        "record_type",
+        "cfda_info",
+        "cfda_number",
+        "primary_cfda_info",
+        "sai_number",
+        "funding_opportunity",
+        "non_federal_funding",
+        "total_funding",
+        "transaction_obligated_amount",
+    ]
+
+    SEARCH_FIELDS = Award.SEARCH_FIELDS + [
+        "Start Date",
+        "End Date",
+        "Award Amount",
+        "Total Outlays",
+        "Award Type",
+        "SAI Number",
+        "CFDA Number",
+        "Assistance Listings",
+        "primary_assistance_listing",
+    ]
+
+    @property
+    def fain(self) -> Optional[str]:
+        """
+        An identification code assigned to each financial assistance award tracking
+        purposes. The FAIN is tied to that award (and all future modifications to that
+        award) throughout the award's life. Each FAIN is assigned by an agency. Within
+        an agency, FAIN are unique: each new award must be issued a new FAIN. FAIN
+        stands for Federal Award Identification Number, though the digits are letters,
+        not numbers.
+        """
+        return self._lazy_get("fain")
+
+    @property
+    def uri(self) -> Optional[str]:
+        """The uri of the award"""
+        return self._lazy_get("uri")
+
+    @property
+    def record_type(self) -> Optional[int]:
+        """Grant record type identifier."""
+        return self._lazy_get("record_type")
+
+    @property
+    def cfda_info(self) -> List[Dict[str, Any]]:
+        """Catalog of Federal Domestic Assistance information for grants."""
+        return self._lazy_get("cfda_info", "Assistance Listings", default=[])
+
+    @property
+    def cfda_number(self) -> Optional[str]:
+        """Primary CFDA number for grants."""
+        primary_info = self._lazy_get("primary_cfda_info", "primary_assistance_listing")
+        if primary_info:
+            return primary_info.get("cfda_number")
+
+        cfda_list = self._lazy_get("cfda_info", "Assistance Listings")
+        if cfda_list:
+            return cfda_list[0].get("cfda_number")
+
+        return self._lazy_get("cfda_number", "CFDA Number")
+
+    @property
+    def primary_cfda_info(self) -> Optional[Dict[str, Any]]:
+        """Primary CFDA program information."""
+        return self._lazy_get("primary_cfda_info", "primary_assistance_listing")
+
+    @property
+    def sai_number(self) -> Optional[str]:
+        """System for Award Identification (SAI) number for grants."""
+        return self._lazy_get("sai_number", "SAI Number")
+
+    @cached_property
+    def funding_opportunity(self) -> Optional[Dict[str, Any]]:
+        """Funding opportunity details for grants."""
+        return self._lazy_get("funding_opportunity")
+
+    @property
+    def non_federal_funding(self) -> Optional[Decimal]:
+        """A summation of this award's transactions' non-federal funding amount"""
+        return to_decimal(self._lazy_get("non_federal_funding", default=None))
+
+    @property
+    def total_funding(self) -> Optional[Decimal]:
+        """The sum of the federal action obligations and the Non-Federal funding amount."""
+        return to_decimal(self._lazy_get("total_funding", default=None))
+
+    @property
+    def transaction_obligated_amount(self) -> Optional[Decimal]:
+        """Transaction-level obligated amount."""
+        return to_decimal(self._lazy_get("transaction_obligated_amount", default=None))
+
+    @property
+    def total_subsidy_cost(self) -> Optional[Decimal]:
+        """Total subsidy cost for this award."""
+        return to_decimal(self._lazy_get("total_subsidy_cost", default=None))
+
+    @property
+    def base_exercised_options(self) -> Optional[Decimal]:
+        """The total amount obligated for the base and exercised options of this award."""
+        return to_decimal(self._lazy_get("base_exercised_options", default=None))
+
+    @property
+    def base_and_all_options(self) -> Optional[Decimal]:
+        """The total amount obligated for the base and all options of this award."""
+        return to_decimal(self._lazy_get("base_and_all_options", default=None))
+
+    @property
+    def subawards(self) -> "SubAwardsSearch":
+        """Get subawards query builder for this grant award with appropriate award type filters.
+
+        Returns a SubAwardsSearch object that can be further filtered and chained.
+        Automatically applies grant award type filters.
+
+        Examples:
+            >>> grant.subawards.count()  # Get count without loading all data
+            >>> grant.subawards.limit(10).all()  # Get first 10 subawards
+            >>> list(grant.subawards)  # Iterate through all subawards
+        """
+        from .award_types import GRANT_CODES
+
+        # Grant subawards use grant award types only
+        # Note: Due to validation in AwardsSearch, we cannot mix grant/direct_payment/other categories
+        return self._client.subawards.award_id(
+            self.generated_unique_award_id
+        ).award_type_codes(*GRANT_CODES)

usaspending/models/idv.py

@@ -0,0 +1,165 @@
+"""IDV (Indefinite Delivery Vehicle) award model for USASpending data."""
+
+from __future__ import annotations
+from typing import Dict, Any, Optional
+from functools import cached_property
+from decimal import Decimal
+
+from .award import Award
+from .location import Location
+from ..utils.formatter import to_decimal
+
+
+class IDV(Award):
+    """Indefinite Delivery Vehicle (IDV) award type.
+
+    IDVs are contract vehicles that provide for an indefinite quantity of supplies
+    or services during a fixed period of time. They establish broad parameters and
+    terms for ordering supplies/services, with specific orders placed against them
+    via delivery orders or task orders.
+
+    Common IDV types include:
+    - GWAC (Government-Wide Acquisition Contract)
+    - IDC (Indefinite Delivery Contract)
+    - FSS (Federal Supply Schedule)
+    - BOA (Basic Ordering Agreement)
+    - BPA (Blanket Purchase Agreement)
+
+    IDVs serve as parent contracts that streamline procurement by pre-negotiating
+    terms, conditions, and pricing for future orders. They reduce administrative
+    costs and enable faster acquisition of recurring needs.
+
+    Example:
+        >>> # Find all IDVs for an agency
+        >>> idvs = client.awards.search().idvs().agency("NASA").all()
+        >>> for idv in idvs:
+        ...     print(f"{idv.piid}: {idv.recipient_name} - ${idv.total_obligation:,.2f}")
+    """
+
+    TYPE_FIELDS = [
+        "piid",
+        "base_and_all_options",
+        "contract_award_type",
+        "naics_code",
+        "naics_description",
+        "naics_hierarchy",
+        "psc_code",
+        "psc_description",
+        "psc_hierarchy",
+        "latest_transaction_contract_data",
+    ]
+
+    SEARCH_FIELDS = Award.SEARCH_FIELDS + [
+        "Start Date",
+        "Award Amount",
+        "Total Outlays",
+        "Contract Award Type",
+        "Last Date to Order",
+        "NAICS",
+        "PSC",
+    ]
+
+    @property
+    def piid(self) -> Optional[str]:
+        """
+        Procurement Instrument Identifier - A unique identifier assigned to a federal
+        contract, purchase order, basic ordering agreement, basic agreement, and
+        blanket purchase agreement. It is used to track the contract, and any
+        modifications or transactions related to it. After October 2017, it is
+        between 13 and 17 digits, both letters and numbers.
+        """
+        return self._lazy_get("piid")
+
+    @property
+    def base_and_all_options(self) -> Optional[Decimal]:
+        """
+        For IDVs, this is the mutually agreed upon total contract value including all options (if any)
+        AND the estimated value of all potential orders. For modifications enter the CHANGE, positive
+        or negative of these values, if any.
+        """
+        return to_decimal(self._lazy_get("base_and_all_options", default=None))
+
+    @property
+    def base_exercised_options(self) -> Optional[Decimal]:
+        """
+        The contract value for the base contract and any options that have been exercised.
+        """
+        return to_decimal(self._lazy_get("base_exercised_options", default=None))
+
+    @property
+    def contract_award_type(self) -> Optional[str]:
+        """Contract award type description."""
+        return self._lazy_get(
+            "contract_award_type", "Contract Award Type", "type_description"
+        )
+
+    @property
+    def naics_code(self) -> Optional[str]:
+        """NAICS industry classification code."""
+        naics_data = self._lazy_get("naics", "NAICS")
+        if isinstance(naics_data, dict):
+            return naics_data.get("code")
+        if self.naics_hierarchy and isinstance(
+            self.naics_hierarchy.get("base_code"), dict
+        ):
+            return self.naics_hierarchy["base_code"].get("code")
+        return None
+
+    @property
+    def naics_description(self) -> Optional[str]:
+        """NAICS industry classification description."""
+        naics_data = self._lazy_get("naics", "NAICS")
+        if isinstance(naics_data, dict):
+            return naics_data.get("description")
+        return None
+
+    @property
+    def psc_code(self) -> Optional[str]:
+        """Product/Service Code (PSC) for contracts."""
+        psc_data = self._lazy_get("psc", "PSC")
+        if isinstance(psc_data, dict):
+            return psc_data.get("code")
+        if self.psc_hierarchy and isinstance(self.psc_hierarchy.get("base_code"), dict):
+            return self.psc_hierarchy["base_code"].get("code")
+        return None
+
+    @property
+    def psc_description(self) -> Optional[str]:
+        """Product/Service Code (PSC) description."""
+        psc_data = self._lazy_get("psc", "PSC")
+        if isinstance(psc_data, dict):
+            return psc_data.get("description")
+        return None
+
+    @cached_property
+    def psc_hierarchy(self) -> Optional[Dict[str, Any]]:
+        """Product/Service Code (PSC) hierarchy information."""
+        return self._lazy_get("psc_hierarchy")
+
+    @cached_property
+    def naics_hierarchy(self) -> Optional[Dict[str, Any]]:
+        """North American Industry Classification System (NAICS) hierarchy."""
+        return self._lazy_get("naics_hierarchy")
+
+    @cached_property
+    def latest_transaction_contract_data(self) -> Optional[Dict[str, Any]]:
+        """Latest contract transaction data with procurement-specific details."""
+        return self._lazy_get("latest_transaction_contract_data")
+
+    @cached_property
+    def place_of_performance(self) -> Optional[Location]:
+        """Award place of performance location.
+
+        Note: IDVs typically have null or empty place_of_performance data.
+        """
+        data = self._lazy_get(
+            "place_of_performance", "Primary Place of Performance", default=None
+        )
+        if not isinstance(data, dict) or not data:
+            return None
+
+        # Check if all values in the dict are None/null (common for IDV awards)
+        if all(v is None for v in data.values()):
+            return None
+
+        return Location(data, self._client)

usaspending/models/lazy_record.py

@@ -0,0 +1,82 @@
+# usaspending/models/lazy_record.py
+from .base_model import ClientAwareModel
+from typing import Dict, Any, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..client import USASpendingClient
+
+
+class LazyRecord(ClientAwareModel):
+    """Enhanced LazyRecord that maintains client reference."""
+
+    def __init__(self, data: Dict[str, Any], client: "USASpendingClient"):
+        super().__init__(data, client)
+        self._details_fetched = False
+
+    def _ensure_details(self) -> None:
+        """Fetch full details using the client."""
+        if self._details_fetched:
+            return
+
+        new_data = self._fetch_details()
+        if new_data:
+            self._data.update(new_data)
+        self._details_fetched = True
+
+    def fetch_all_details(self) -> None:
+        """Eagerly fetch all lazy-loadable data for this model.
+
+        This method is useful when you need to access model properties outside
+        of the client context manager. Call this method before the client session
+        closes to ensure all data is fetched.
+
+        Example:
+            with USASpendingClient() as client:
+                awards = client.awards.search().limit(10).all()
+                for award in awards:
+                    award.fetch_all_details()  # Fetch all lazy data
+            # Now safe to use awards outside the context
+            print(awards[0].subaward_count)
+
+        Raises:
+            DetachedInstanceError: If the client session is already closed.
+        """
+        self._ensure_details()
+
+    def _fetch_details(self) -> Optional[Dict[str, Any]]:
+        """Override in subclasses."""
+        raise NotImplementedError
+
+    def _lazy_get(self, *keys: str, default: Any = None) -> Any:
+        """Get value, triggering lazy load if needed."""
+
+        keys = list(keys)
+
+        # If we've already lazy-loaded details, return whatever
+        # values are present in the data
+        if self._details_fetched:
+            return self.get_value(keys, default=default)
+
+        # Check if any of the keys exist in the current data
+        key_found = False
+        value = None
+
+        for key in keys:
+            if key in self._data:
+                value = self._data[key]
+                key_found = True
+                break
+
+        # If no key was found, or if the value is None (indicating missing data),
+        # trigger lazy loading
+        if not key_found or value is None:
+            # Load full resource data from source
+            self._ensure_details()
+
+            # Set flag
+            self._details_fetched = True
+
+            # Attempt to return the value again
+            value = self.get_value(keys, default=default)
+
+        return value

usaspending/models/loan.py

@@ -0,0 +1,85 @@
+"""Loan award model for USASpending data."""
+
+from __future__ import annotations
+from typing import Dict, Any, Optional, List
+from decimal import Decimal
+
+from .grant import Grant
+from .award import Award
+from ..utils.formatter import to_decimal
+
+
+class Loan(Grant):
+    """Loan award type."""
+
+    TYPE_FIELDS = [
+        "fain",
+        "uri",
+        "total_subsidy_cost",
+        "total_loan_value",
+        "cfda_info",
+        "cfda_number",
+        "primary_cfda_info",
+        "sai_number",
+    ]
+
+    SEARCH_FIELDS = Award.SEARCH_FIELDS + [
+        "Issued Date",
+        "Loan Value",
+        "Subsidy Cost",
+        "SAI Number",
+        "CFDA Number",
+        "Assistance Listings",
+        "primary_assistance_listing",
+    ]
+
+    @property
+    def fain(self) -> Optional[str]:
+        """
+        An identification code assigned to each financial assistance award tracking
+        purposes. The FAIN is tied to that award (and all future modifications to that
+        award) throughout the award's life. Each FAIN is assigned by an agency. Within
+        an agency, FAIN are unique: each new award must be issued a new FAIN. FAIN
+        stands for Federal Award Identification Number, though the digits are letters,
+        not numbers.
+        """
+        return self._lazy_get("fain")
+
+    @property
+    def uri(self) -> Optional[str]:
+        """The uri of the award"""
+        return self._lazy_get("uri")
+
+    @property
+    def total_subsidy_cost(self) -> Optional[Decimal]:
+        """The total of the original_loan_subsidy_cost from associated transactions"""
+        return to_decimal(
+            self._lazy_get("Subsidy Cost", "total_subsidy_cost", default=None)
+        )
+
+    @property
+    def total_loan_value(self) -> Optional[Decimal]:
+        """The total of the face_value_loan_guarantee from associated transactions"""
+        return to_decimal(
+            self._lazy_get("Loan Value", "total_loan_value", default=None)
+        )
+
+    @property
+    def cfda_info(self) -> List[Dict[str, Any]]:
+        """Catalog of Federal Domestic Assistance information for loans."""
+        return self._lazy_get("cfda_info", "Assistance Listings", default=[])
+
+    @property
+    def cfda_number(self) -> Optional[str]:
+        """Primary CFDA number for loans."""
+        return self._lazy_get("cfda_number", "CFDA Number")
+
+    @property
+    def primary_cfda_info(self) -> Optional[Dict[str, Any]]:
+        """Primary CFDA program information."""
+        return self._lazy_get("primary_cfda_info", "primary_assistance_listing")
+
+    @property
+    def sai_number(self) -> Optional[str]:
+        """System for Award Identification (SAI) number for loans."""
+        return self._lazy_get("sai_number", "SAI Number")