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

1"""Agency resource implementation.""" 

2 

3from __future__ import annotations 

4from typing import TYPE_CHECKING, Optional 

5 

6from .base_resource import BaseResource 

7from ..logging_config import USASpendingLogger 

8 

9if TYPE_CHECKING: 

10 from ..models.agency import Agency 

11 from ..queries.funding_agencies_search import FundingAgenciesSearch 

12 from ..queries.awarding_agencies_search import AwardingAgenciesSearch 

13 

14logger = USASpendingLogger.get_logger(__name__) 

15 

16 

17class AgencyResource(BaseResource): 

18 """Resource for agency-related operations. 

19 

20 Provides access to agency overview and detail endpoints. 

21 """ 

22 

23 def find_by_toptier_code(self, toptier_code: str, fiscal_year: Optional[int] = None) -> "Agency": 

24 """Retrieve agency overview for a specific toptier code and fiscal year. 

25 

26 Args: 

27 toptier_code: The toptier code of an agency (3-4 digit string) 

28 fiscal_year: Optional fiscal year for the data (defaults to current) 

29 

30 Returns: 

31 Agency model instance with full details 

32 

33 Raises: 

34 ValidationError: If toptier_code is invalid 

35 APIError: If agency not found 

36 

37 Example: 

38 >>> agency = client.agencies.find_by_toptier_code("080") # Get NASA for current fiscal year 

39 >>> print(agency.name, agency.mission) 

40 >>>  

41 >>> agency_2023 = client.agencies.find_by_toptier_code("080", fiscal_year=2023) # Get NASA for FY 2023 

42 >>> print(agency_2023.fiscal_year, agency_2023.def_codes) 

43 """ 

44 logger.debug( 

45 f"Retrieving agency overview for toptier_code: {toptier_code}, " 

46 f"fiscal_year: {fiscal_year}" 

47 ) 

48 

49 from ..queries.agency_query import AgencyQuery 

50 

51 return AgencyQuery(self._client).find_by_id(toptier_code, fiscal_year) 

52 

53 def find_all_funding_agencies_by_name(self, name: str) -> "FundingAgenciesSearch": 

54 """Search for funding agencies and offices by name. 

55  

56 Args: 

57 name: Search text to match against agency/office names 

58  

59 Returns: 

60 FundingAgenciesSearch query builder for iteration and filtering 

61  

62 Example: 

63 >>> # Get all matches (agencies, subtiers, offices) 

64 >>> all_results = list(client.agencies.find_all_funding_agencies_by_name("NASA")) 

65 >>>  

66 >>> # Get only toptier agencies 

67 >>> agencies = list(client.agencies.find_all_funding_agencies_by_name("NASA").toptier()) 

68 >>>  

69 >>> # Get only subtier agencies  

70 >>> subtiers = list(client.agencies.find_all_funding_agencies_by_name("NASA").subtier()) 

71 >>>  

72 >>> # Get only offices 

73 >>> offices = list(client.agencies.find_all_funding_agencies_by_name("NASA").office()) 

74 """ 

75 from ..queries.funding_agencies_search import FundingAgenciesSearch 

76 

77 return FundingAgenciesSearch(self._client).with_search_text(name) 

78 

79 def find_all_awarding_agencies_by_name(self, name: str) -> "AwardingAgenciesSearch": 

80 """Search for funding agencies and offices by name. 

81  

82 Args: 

83 name: Search text to match against agency/office names 

84  

85 Returns: 

86 AwardingAgenciesSearch query builder for iteration and filtering 

87  

88 Example: 

89 >>> # Get all matches (agencies, subtiers, offices) 

90 >>> all_results = list(client.agencies.find_all_awarding_agencies_by_name("NASA")) 

91 >>>  

92 >>> # Get only toptier agencies 

93 >>> agencies = list(client.agencies.find_all_awarding_agencies_by_name("NASA").toptier()) 

94 >>>  

95 >>> # Get only subtier agencies  

96 >>> subtiers = list(client.agencies.find_all_awarding_agencies_by_name("NASA").subtier()) 

97 >>>  

98 >>> # Get only offices 

99 >>> offices = list(client.agencies.find_all_awarding_agencies_by_name("NASA").office()) 

100 """ 

101 from ..queries.awarding_agencies_search import AwardingAgenciesSearch 

102 

103 return AwardingAgenciesSearch(self._client).with_search_text(name)