diff options
author | Danglewood <85772166+deeleeramone@users.noreply.github.com> | 2024-05-29 08:00:53 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-05-29 15:00:53 +0000 |
commit | 0085221611196e622afeea1d2c7101196dad0ed7 (patch) | |
tree | 2a42449411dd26f80d52bf4e50c14deea1e73bb1 | |
parent | 01a71a89953127ce79193d53021570d9a03d2194 (diff) |
[Feature] Add Central Bank Holdings (Federal Reserve) (#6469)
* add central bank holdings
* codespell
* actually commit the standard model
---------
Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>
16 files changed, 1791 insertions, 44 deletions
diff --git a/openbb_platform/core/openbb_core/provider/standard_models/central_bank_holdings.py b/openbb_platform/core/openbb_core/provider/standard_models/central_bank_holdings.py new file mode 100644 index 00000000000..b84d1ecaf3a --- /dev/null +++ b/openbb_platform/core/openbb_core/provider/standard_models/central_bank_holdings.py @@ -0,0 +1,30 @@ +"""Central Bank Holdings Standard Model.""" + +from datetime import ( + date as dateType, +) +from typing import Optional + +from pydantic import Field + +from openbb_core.provider.abstract.data import Data +from openbb_core.provider.abstract.query_params import QueryParams +from openbb_core.provider.utils.descriptions import ( + DATA_DESCRIPTIONS, + QUERY_DESCRIPTIONS, +) + + +class CentralBankHoldingsQueryParams(QueryParams): + """Central Bank Holdings Query.""" + + date: Optional[dateType] = Field( + default=None, + description=QUERY_DESCRIPTIONS.get("date", ""), + ) + + +class CentralBankHoldingsData(Data): + """Central Bank Holdings Data.""" + + date: dateType = Field(description=DATA_DESCRIPTIONS.get("date", "")) diff --git a/openbb_platform/extensions/economy/integration/test_economy_api.py b/openbb_platform/extensions/economy/integration/test_economy_api.py index 3f7998c14de..b06ac4937e6 100644 --- a/openbb_platform/extensions/economy/integration/test_economy_api.py +++ b/openbb_platform/extensions/economy/integration/test_economy_api.py @@ -657,3 +657,42 @@ def test_economy_country_profile(params, headers): result = requests.get(url, headers=headers, timeout=30) assert isinstance(result, requests.Response) assert result.status_code == 200 + + +@parametrize( + "params", + [ + ( + { + "date": None, + "provider": "federal_reserve", + "holding_type": "all_treasury", + "summary": False, + "monthly": False, + "cusip": None, + "wam": False, + } + ), + ( + { + "date": None, + "provider": "federal_reserve", + "holding_type": "all_agency", + "summary": False, + "monthly": False, + "cusip": None, + "wam": True, + } + ), + ], +) +@pytest.mark.integration +def test_economy_central_bank_holdings(params, headers): + """Test the economy central bank holdings.""" + params = {p: v for p, v in params.items() if v} + + query_str = get_querystring(params, []) + url = f"http://0.0.0.0:8000/api/v1/economy/central_bank_holdings?{query_str}" + result = requests.get(url, headers=headers, timeout=5) + assert isinstance(result, requests.Response) + assert result.status_code == 200 diff --git a/openbb_platform/extensions/economy/integration/test_economy_python.py b/openbb_platform/extensions/economy/integration/test_economy_python.py index 75a01123c7b..4825b504949 100644 --- a/openbb_platform/extensions/economy/integration/test_economy_python.py +++ b/openbb_platform/extensions/economy/integration/test_economy_python.py @@ -606,3 +606,41 @@ def test_economy_indicators(params, obb): assert result assert isinstance(result, OBBject) assert len(result.results) > 0 + + +@parametrize( + "params", + [ + ( + { + "date": None, + "provider": "federal_reserve", + "holding_type": "all_treasury", + "summary": False, + "monthly": False, + "cusip": None, + "wam": False, + } + ), + ( + { + "date": None, + "provider": "federal_reserve", + "holding_type": "all_agency", + "summary": False, + "monthly": False, + "cusip": None, + "wam": True, + } + ), + ], +) +@pytest.mark.integration +def test_economy_central_bank_holdings(params, obb): + """Test economy central bank holdings.""" + params = {p: v for p, v in params.items() if v} + + result = obb.economy.central_bank_holdings(**params) + assert result + assert isinstance(result, OBBject) + assert len(result.results) > 0 diff --git a/openbb_platform/extensions/economy/openbb_economy/economy_router.py b/openbb_platform/extensions/economy/openbb_economy/economy_router.py index 6adeaeea1ea..b318d1183e6 100644 --- a/openbb_platform/extensions/economy/openbb_economy/economy_router.py +++ b/openbb_platform/extensions/economy/openbb_economy/economy_router.py @@ -378,3 +378,35 @@ async def indicators( ) -> OBBject: """Get economic indicators by country and indicator.""" return await OBBject.from_query(Query(**locals())) + + +@router.command( + model="CentralBankHoldings", + examples=[ + APIEx( + description="The default is the latest Treasury securities held by the Federal Reserve.", + parameters={"provider": "federal_reserve"}, + ), + APIEx( + description="Get historical summaries of the Fed's holdings.", + parameters={"provider": "federal_reserve", "summary": True}, + ), + APIEx( + description="Get the balance sheet holdings as-of a historical date.", + parameters={"provider": "federal_reserve", "date": "2019-05-21"}, + ), + APIEx( + description="Use the `holding_type` parameter to select Agency securities," + + " or specific categories or Treasury securities.", + parameters={"provider": "federal_reserve", "holding_type": "agency_debts"}, + ), + ], +) +async def central_bank_holdings( + cc: CommandContext, + provider_choices: ProviderChoices, + standard_params: StandardParams, + extra_params: ExtraParams, +) -> OBBject: + """Get the balance sheet holdings of a central bank.""" + return await OBBject.from_query(Query(**locals())) diff --git a/openbb_platform/openbb/assets/reference.json b/openbb_platform/openbb/assets/reference.json index 7fcaea8ee60..aae0334f071 100644 --- a/openbb_platform/openbb/assets/reference.json +++ b/openbb_platform/openbb/assets/reference.json @@ -5202,6 +5202,313 @@ }, "model": "EconomicIndicators" }, + "/economy/central_bank_holdings": { + "deprecated": { + "flag": null, + "message": null + }, + "description": "Get the balance sheet holdings of a central bank.", + "examples": "\nExamples\n--------\n\n```python\nfrom openbb import obb\n# The default is the latest Treasury securities held by the Federal Reserve.\nobb.economy.central_bank_holdings(provider='federal_reserve')\n# Get historical summaries of the Fed's holdings.\nobb.economy.central_bank_holdings(provider='federal_reserve', summary=True)\n# Get the balance sheet holdings as-of a historical date.\nobb.economy.central_bank_holdings(provider='federal_reserve', date='2019-05-21')\n# Use the `holding_type` parameter to select Agency securities, or specific categories or Treasury securities.\nobb.economy.central_bank_holdings(provider='federal_reserve', holding_type=agency_debts)\n```\n\n", + "parameters": { + "standard": [ + { + "name": "date", + "type": "Union[date, str]", + "description": "A specific date to get data for.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "provider", + "type": "Literal['federal_reserve']", + "description": "The provider to use for the query, by default None. If None, the provider specified in defaults is selected or 'federal_reserve' if there is no default.", + "default": "federal_reserve", + "optional": true + } + ], + "federal_reserve": [ + { + "name": "holding_type", + "type": "Literal['all_agency', 'agency_debts', 'mbs', 'cmbs', 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips']", + "description": "Type of holdings to return.", + "default": "all_treasury", + "optional": true, + "choices": [ + "all_agency", + "agency_debts", + "mbs", + "cmbs", + "all_treasury", + "bills", + "notesbonds", + "frn", + "tips" + ] + }, + { + "name": "summary", + "type": "bool", + "description": "If True, returns historical weekly summary by holding type. This parameter takes priority over other parameters.", + "default": false, + "optional": true, + "choices": null + }, + { + "name": "cusip", + "type": "Union[str, List[str]]", + "description": " Multiple items allowed for provider(s): federal_reserve.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "wam", + "type": "bool", + "description": "If True, returns weighted average maturity aggregated by agency or treasury securities. This parameter takes priority over `holding_type`, `cusip`, and `monthly`.", + "default": false, + "optional": true, + "choices": null + }, + { + "name": "monthly", + "type": "bool", + "description": "If True, returns historical data for all Treasury securities at a monthly interval. This parameter takes priority over other parameters, except `wam`. Only valid when `holding_type` is set to: 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips'.", + "default": false, + "optional": true, + "choices": null + } + ] + }, + "returns": { + "OBBject": [ + { + "name": "results", + "type": "List[CentralBankHoldings]", + "description": "Serializable results." + }, + { + "name": "provider", + "type": "Optional[Literal['federal_reserve']]", + "description": "Provider name." + }, + { + "name": "warnings", + "type": "Optional[List[Warning_]]", + "description": "List of warnings." + }, + { + "name": "chart", + "type": "Optional[Chart]", + "description": "Chart object." + }, + { + "name": "extra", + "type": "Dict[str, Any]", + "description": "Extra info." + } + ] + }, + "data": { + "standard": [ + { + "name": "date", + "type": "date", + "description": "The date of the data.", + "default": "", + "optional": false, + "choices": null + } + ], + "federal_reserve": [ + { + "name": "security_type", + "type": "str", + "description": "Type of security - i.e. TIPs, FRNs, etc.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "description", + "type": "str", + "description": "Description of the security. Only returned for Agency securities.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "is_aggreated", + "type": "Literal['Y']", + "description": "Whether the security is aggregated. Only returned for Agency securities.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "cusip", + "type": "str", + "description": "", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "issuer", + "type": "str", + "description": "Issuer of the security.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "maturity_date", + "type": "date", + "description": "Maturity date of the security.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "term", + "type": "str", + "description": "Term of the security. Only returned for Agency securities.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "face_value", + "type": "float", + "description": "Current face value of the security (Thousands). Current face value of the securities, which is the remaining principal balance of the securities.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "par_value", + "type": "float", + "description": "Par value of the security (Thousands). Changes in par may reflect primary and secondary market transactions and/or custodial account activity.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "coupon", + "type": "float", + "description": "Coupon rate of the security.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "spread", + "type": "float", + "description": "Spread to the current reference rate, as determined at each security's initial auction.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "percent_outstanding", + "type": "float", + "description": "Total percent of the outstanding CUSIP issuance.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "bills", + "type": "float", + "description": "Treasury bills amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "frn", + "type": "float", + "description": "Floating rate Treasury notes amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "notes_and_bonds", + "type": "float", + "description": "Treasuy Notes and bonds amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "tips", + "type": "float", + "description": "Treasury inflation-protected securities amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "mbs", + "type": "float", + "description": "Mortgage-backed securities amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "cmbs", + "type": "float", + "description": "Commercial mortgage-backed securities amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "agencies", + "type": "float", + "description": "Agency securities amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "total", + "type": "float", + "description": "Total SOMA holdings amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "tips_inflation_compensation", + "type": "float", + "description": "Treasury inflation-protected securities inflation compensation amount (Thousands). Only returned when 'summary' is True.", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "change_prior_week", + "type": "float", + "description": "Change in SOMA holdings from the prior week (Thousands).", + "default": null, + "optional": true, + "choices": null + }, + { + "name": "change_prior_year", + "type": "float", + "description": "Change in SOMA holdings from the prior year (Thousands).", + "default": null, + "optional": true, + "choices": null + } + ] + }, + "model": "CentralBankHoldings" + }, "/equity/calendar/ipo": { "deprecated": { "flag": null, diff --git a/openbb_platform/openbb/package/economy.py b/openbb_platform/openbb/package/economy.py index b3e5f7cb231..19191e3f4da 100644 --- a/openbb_platform/openbb/package/economy.py +++ b/openbb_platform/openbb/package/economy.py @@ -16,6 +16,7 @@ class ROUTER_economy(Container): available_indicators balance_of_payments calendar + central_bank_holdings composite_leading_indicator country_profile cpi @@ -368,6 +369,139 @@ class ROUTER_economy(Container): @exception_handler @validate + def central_bank_holdings( + self, + date: Annotated[ + Union[datetime.date, None, str], + OpenBBField(description="A specific date to get data for."), + ] = None, + provider: Annotated[ + Optional[Literal["federal_reserve"]], + OpenBBField( + description="The provider to use for the query, by default None.\n If None, the provider specified in defaults is selected or 'federal_reserve' if there is\n no default." + ), + ] = None, + **kwargs + ) -> OBBject: + """Get the balance sheet holdings of a central bank. + + Parameters + ---------- + date : Union[datetime.date, None, str] + A specific date to get data for. + provider : Optional[Literal['federal_reserve']] + The provider to use for the query, by default None. + If None, the provider specified in defaults is selected or 'federal_reserve' if there is + no default. + holding_type : Literal['all_agency', 'agency_debts', 'mbs', 'cmbs', 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips'] + Type of holdings to return. (provider: federal_reserve) + summary : bool + If True, returns historical weekly summary by holding type. This parameter takes priority over other parameters. (provider: federal_reserve) + cusip : Optional[str] + Multiple comma separated items allowed. + wam : bool + If True, returns weighted average maturity aggregated by agency or treasury securities. This parameter takes priority over `holding_type`, `cusip`, and `monthly`. (provider: federal_reserve) + monthly : bool + If True, returns historical data for all Treasury securities at a monthly interval. This parameter takes priority over other parameters, except `wam`. Only valid when `holding_type` is set to: 'all_treasury', 'bills', 'notesbonds', 'frn', 'tips'. (provider: federal_reserve) + + Returns + ------- + OBBject + results : List[CentralBankHoldings] + Serializable results. + provider : Optional[Literal['federal_reserve']] + Provider name. + warnings : Optional[List[Warning_]] + List of warnings. + chart : Optional[Chart] + Chart object. + extra : Dict[str, Any] + Extra info. + + CentralBankHoldings + ------------------- + date : date + The date of the data. + security_type : Optional[str] + Type of security - i.e. TIPs, FRNs, etc. (provider: federal_reserve) + description : Optional[str] + Description of the security. Only returned for Agency securities. (provider: federal_reserve) + is_aggreated : Optional[Literal['Y']] + Whether the security is aggregated. Only returned for Agency securities. (provider: federal_reserve) + cusip : Optional[str] + + issuer : Optional[str] + Issuer of the security. (provider: federal_reserve) + maturity |