Coverage for src/usaspending/resources/subawards_resource.py: 100%

1"""Subawards resource implementation.""" 

2 

3from __future__ import annotations 

4from typing import TYPE_CHECKING 

5 

6from .base_resource import BaseResource 

7from ..logging_config import USASpendingLogger 

8 

9if TYPE_CHECKING: 

10 from ..queries.subawards_search import SubAwardsSearch 

11 

12logger = USASpendingLogger.get_logger(__name__) 

13 

14 

15class SubAwardsResource(BaseResource): 

16 """Resource for subaward-related operations. 

17 

18 Provides access to subaward search and retrieval endpoints. Subawards  

19 represent the secondary distribution of federal funds from prime recipients 

20 to subrecipients who carry out portions of the federal program. 

21  

22 The resource supports searching for both contract subawards (subcontracts) 

23 and grant subawards, with filtering by time periods, award types, agencies, 

24 and recipients. Results include detailed information about the prime award, 

25 subrecipient, and the subaward transaction itself. 

26  

27 Note: Subaward reporting is required for subawards of $30,000 or more under 

28 the Federal Funding Accountability and Transparency Act (FFATA). 

29 """ 

30 

31 def search(self) -> "SubAwardsSearch": 

32 """Create a subawards search query builder. 

33 

34 Returns: 

35 SubAwardsSearch query builder for chaining filters 

36 

37 Example: 

38 >>> subawards = client.subawards.search() 

39 ... .with_award_types("A", "B", "C") 

40 ... .in_time_period("2024-01-01", "2024-12-31") 

41 ... .limit(50) 

42 >>> for sub in subawards: 

43 ... print(f"{sub.sub_awardee_name}: ${sub.sub_award_amount:,.2f}") 

44 """ 

45 logger.debug("Creating subawards search query builder") 

46 from ..queries.subawards_search import SubAwardsSearch 

47 

48 return SubAwardsSearch(self._client) 

49 

50 def for_award(self, award_id: str) -> "SubAwardsSearch": 

51 """Create a subawards search query for a specific award. 

52 

53 This is a convenience method that chains search().for_award(award_id). 

54 

55 Args: 

56 award_id: Unique award identifier 

57 

58 Returns: 

59 SubAwardsSearch query builder for chaining filters 

60 

61 Example: 

62 >>> subawards = client.subawards.for_award("CONT_AWD_123...") 

63 ... .limit(50) 

64 >>> for sub in subawards: 

65 ... print(f"{sub.sub_award_date}: {sub.sub_awardee_name}") 

66 """ 

67 logger.debug(f"Creating subawards search for award: {award_id}") 

68 return self.search().for_award(award_id)