|
|
|
|
|
|
|
|
import datetime |
|
|
from typing import Literal, Optional, Union |
|
|
|
|
|
from openbb_core.app.model.field import OpenBBField |
|
|
from openbb_core.app.model.obbject import OBBject |
|
|
from openbb_core.app.static.container import Container |
|
|
from openbb_core.app.static.utils.decorators import exception_handler, validate |
|
|
from openbb_core.app.static.utils.filters import filter_inputs |
|
|
from typing_extensions import Annotated |
|
|
|
|
|
|
|
|
class ROUTER_commodity(Container): |
|
|
"""/commodity |
|
|
petroleum_status_report |
|
|
/price |
|
|
short_term_energy_outlook |
|
|
""" |
|
|
|
|
|
def __repr__(self) -> str: |
|
|
return self.__doc__ or "" |
|
|
|
|
|
@exception_handler |
|
|
@validate |
|
|
def petroleum_status_report( |
|
|
self, |
|
|
start_date: Annotated[ |
|
|
Union[datetime.date, None, str], |
|
|
OpenBBField(description="Start date of the data, in YYYY-MM-DD format."), |
|
|
] = None, |
|
|
end_date: Annotated[ |
|
|
Union[datetime.date, None, str], |
|
|
OpenBBField(description="End date of the data, in YYYY-MM-DD format."), |
|
|
] = None, |
|
|
provider: Annotated[ |
|
|
Optional[Literal["eia"]], |
|
|
OpenBBField( |
|
|
description="The provider to use, by default None. If None, the priority list configured in the settings is used. Default priority: eia." |
|
|
), |
|
|
] = None, |
|
|
**kwargs |
|
|
) -> OBBject: |
|
|
"""EIA Weekly Petroleum Status Report. |
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
provider : str |
|
|
The provider to use, by default None. If None, the priority list configured in the settings is used. Default priority: eia. |
|
|
start_date : Union[date, None, str] |
|
|
Start date of the data, in YYYY-MM-DD format. |
|
|
end_date : Union[date, None, str] |
|
|
End date of the data, in YYYY-MM-DD format. |
|
|
category : Literal['balance_sheet', 'inputs_and_production', 'refiner_blender_net_production', 'crude_petroleum_stocks', 'gasoline_fuel_stocks', 'total_gasoline_by_sub_padd', 'distillate_fuel_oil_stocks', 'imports', 'imports_by_country', 'weekly_estimates', 'spot_prices_crude_gas_heating', 'spot_prices_diesel_jet_fuel_propane', 'retail_prices'] |
|
|
The group of data to be returned. The default is the balance sheet. (provider: eia) |
|
|
table : Optional[str] |
|
|
The specific table element within the category to be returned, default is 'stocks', if the category is 'weekly_estimates', else 'all'. |
|
|
Note: Choices represent all available tables from the entire collection and are not all available for every category. |
|
|
Invalid choices will raise a ValidationError with a message indicating the valid choices for the selected category. |
|
|
Choices are: |
|
|
all |
|
|
conventional_gas |
|
|
crude |
|
|
crude_production |
|
|
crude_production_avg |
|
|
diesel |
|
|
ethanol_plant_production |
|
|
ethanol_plant_production_avg |
|
|
exports |
|
|
exports_avg |
|
|
heating_oil |
|
|
imports |
|
|
imports_avg |
|
|
imports_by_country |
|
|
imports_by_country_avg |
|
|
inputs_and_utilization |
|
|
inputs_and_utilization_avg |
|
|
jet_fuel |
|
|
monthly |
|
|
net_imports_inc_spr_avg |
|
|
net_imports_incl_spr |
|
|
net_production |
|
|
net_production_avg |
|
|
net_production_by_product |
|
|
net_production_by_production_avg |
|
|
product_by_region |
|
|
product_by_region_avg |
|
|
product_supplied |
|
|
product_supplied_avg |
|
|
propane |
|
|
rbob |
|
|
refiner_blender_net_production |
|
|
refiner_blender_net_production_avg |
|
|
stocks |
|
|
supply |
|
|
supply_avg |
|
|
ulta_low_sulfur_distillate_reclassification |
|
|
ulta_low_sulfur_distillate_reclassification_avg |
|
|
weekly |
|
|
Multiple comma separated items allowed. (provider: eia) |
|
|
use_cache : bool |
|
|
Subsequent requests for the same source data are cached for the session using ALRU cache. (provider: eia) |
|
|
|
|
|
Returns |
|
|
------- |
|
|
OBBject |
|
|
results : list[PetroleumStatusReport] |
|
|
Serializable results. |
|
|
provider : Optional[str] |
|
|
Provider name. |
|
|
warnings : Optional[list[Warning_]] |
|
|
list of warnings. |
|
|
chart : Optional[Chart] |
|
|
Chart object. |
|
|
extra : Dict[str, Any] |
|
|
Extra info. |
|
|
|
|
|
PetroleumStatusReport |
|
|
--------------------- |
|
|
date : date |
|
|
The date of the data. |
|
|
table : Optional[str] |
|
|
Table name for the data. |
|
|
symbol : str |
|
|
Symbol representing the entity requested in the data. |
|
|
order : Optional[int] |
|
|
Presented order of the data, relative to the table. |
|
|
title : Optional[str] |
|
|
Title of the data. |
|
|
value : Union[int, float] |
|
|
Value of the data. |
|
|
unit : Optional[str] |
|
|
Unit or scale of the data. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> from openbb import obb |
|
|
>>> # Get the EIA's Weekly Petroleum Status Report. |
|
|
>>> obb.commodity.petroleum_status_report(provider='eia') |
|
|
>>> # Select the category of data, and filter for a specific table within the report. |
|
|
>>> obb.commodity.petroleum_status_report(category='weekly_estimates', table='imports', provider='eia') |
|
|
""" |
|
|
|
|
|
return self._run( |
|
|
"/commodity/petroleum_status_report", |
|
|
**filter_inputs( |
|
|
provider_choices={ |
|
|
"provider": self._get_provider( |
|
|
provider, |
|
|
"commodity.petroleum_status_report", |
|
|
("eia",), |
|
|
) |
|
|
}, |
|
|
standard_params={ |
|
|
"start_date": start_date, |
|
|
"end_date": end_date, |
|
|
}, |
|
|
extra_params=kwargs, |
|
|
info={ |
|
|
"category": { |
|
|
"eia": { |
|
|
"multiple_items_allowed": False, |
|
|
"choices": [ |
|
|
"balance_sheet", |
|
|
"inputs_and_production", |
|
|
"refiner_blender_net_production", |
|
|
"crude_petroleum_stocks", |
|
|
"gasoline_fuel_stocks", |
|
|
"total_gasoline_by_sub_padd", |
|
|
"distillate_fuel_oil_stocks", |
|
|
"imports", |
|
|
"imports_by_country", |
|
|
"weekly_estimates", |
|
|
"spot_prices_crude_gas_heating", |
|
|
"spot_prices_diesel_jet_fuel_propane", |
|
|
"retail_prices", |
|
|
], |
|
|
} |
|
|
}, |
|
|
"table": { |
|
|
"eia": { |
|
|
"multiple_items_allowed": True, |
|
|
"choices": [ |
|
|
"all", |
|
|
"conventional_gas", |
|
|
"crude", |
|
|
"crude_production", |
|
|
"crude_production_avg", |
|
|
"diesel", |
|
|
"ethanol_plant_production", |
|
|
"ethanol_plant_production_avg", |
|
|
"exports", |
|
|
"exports_avg", |
|
|
"heating_oil", |
|
|
"imports", |
|
|
"imports_avg", |
|
|
"imports_by_country", |
|
|
"imports_by_country_avg", |
|
|
"inputs_and_utilization", |
|
|
"inputs_and_utilization_avg", |
|
|
"jet_fuel", |
|
|
"monthly", |
|
|
"net_imports_inc_spr_avg", |
|
|
"net_imports_incl_spr", |
|
|
"net_production", |
|
|
"net_production_avg", |
|
|
"net_production_by_product", |
|
|
"net_production_by_production_avg", |
|
|
"product_by_region", |
|
|
"product_by_region_avg", |
|
|
"product_supplied", |
|
|
"product_supplied_avg", |
|
|
"propane", |
|
|
"rbob", |
|
|
"refiner_blender_net_production", |
|
|
"refiner_blender_net_production_avg", |
|
|
"stocks", |
|
|
"supply", |
|
|
"supply_avg", |
|
|
"ulta_low_sulfur_distillate_reclassification", |
|
|
"ulta_low_sulfur_distillate_reclassification_avg", |
|
|
"weekly", |
|
|
], |
|
|
} |
|
|
}, |
|
|
}, |
|
|
) |
|
|
) |
|
|
|
|
|
@property |
|
|
def price(self): |
|
|
|
|
|
from . import commodity_price |
|
|
|
|
|
return commodity_price.ROUTER_commodity_price( |
|
|
command_runner=self._command_runner |
|
|
) |
|
|
|
|
|
@exception_handler |
|
|
@validate |
|
|
def short_term_energy_outlook( |
|
|
self, |
|
|
start_date: Annotated[ |
|
|
Union[datetime.date, None, str], |
|
|
OpenBBField(description="Start date of the data, in YYYY-MM-DD format."), |
|
|
] = None, |
|
|
end_date: Annotated[ |
|
|
Union[datetime.date, None, str], |
|
|
OpenBBField(description="End date of the data, in YYYY-MM-DD format."), |
|
|
] = None, |
|
|
provider: Annotated[ |
|
|
Optional[Literal["eia"]], |
|
|
OpenBBField( |
|
|
description="The provider to use, by default None. If None, the priority list configured in the settings is used. Default priority: eia." |
|
|
), |
|
|
] = None, |
|
|
**kwargs |
|
|
) -> OBBject: |
|
|
"""Monthly short term (18 month) projections using EIA's STEO model. |
|
|
|
|
|
Source: www.eia.gov/steo/ |
|
|
|
|
|
|
|
|
Parameters |
|
|
---------- |
|
|
provider : str |
|
|
The provider to use, by default None. If None, the priority list configured in the settings is used. Default priority: eia. |
|
|
start_date : Union[date, None, str] |
|
|
Start date of the data, in YYYY-MM-DD format. |
|
|
end_date : Union[date, None, str] |
|
|
End date of the data, in YYYY-MM-DD format. |
|
|
symbol : Optional[str] |
|
|
Symbol to get data for. If provided, overrides the 'table' parameter to return only the specified symbol from the STEO API. Multiple comma separated items allowed. (provider: eia) |
|
|
table : Literal['01', '02', '03a', '03b', '03c', '03d', '03e', '04a', '04b', '04c', '04d', '05a', '05b', '06', '07a', '07b', '07c', '07d1', '07d2', '07e', '08', '09a', '09b', '09c', '10a', '10b'] |
|
|
The specific table within the STEO dataset. Default is '01'. When 'symbol' is provided, this parameter is ignored. |
|
|
01: US Energy Markets Summary |
|
|
02: Nominal Energy Prices |
|
|
03a: World Petroleum and Other Liquid Fuels Production, Consumption, and Inventories |
|
|
03b: Non-OPEC Petroleum and Other Liquid Fuels Production |
|
|
03c: World Petroleum and Other Liquid Fuels Production |
|
|
03d: World Crude Oil Production |
|
|
03e: World Petroleum and Other Liquid Fuels Consumption |
|
|
04a: US Petroleum and Other Liquid Fuels Supply, Consumption, and Inventories |
|
|
04b: US Hydrocarbon Gas Liquids (HGL) and Petroleum Refinery Balances |
|
|
04c: US Regional Motor Gasoline Prices and Inventories |
|
|
04d: US Biofuel Supply, Consumption, and Inventories |
|
|
05a: US Natural Gas Supply, Consumption, and Inventories |
|
|
05b: US Regional Natural Gas Prices |
|
|
06: US Coal Supply, Consumption, and Inventories |
|
|
07a: US Electricity Industry Overview |
|
|
07b: US Regional Electricity Retail Sales |
|
|
07c: US Regional Electricity Prices |
|
|
07d1: US Regional Electricity Generation, Electric Power Sector |
|
|
07d2: US Regional Electricity Generation, Electric Power Sector, continued |
|
|
07e: US Electricity Generating Capacity |
|
|
08: US Renewable Energy Consumption |
|
|
09a: US Macroeconomic Indicators and CO2 Emissions |
|
|
09b: US Regional Macroeconomic Data |
|
|
09c: US Regional Weather Data |
|
|
10a: Drilling Productivity Metrics |
|
|
10b: Crude Oil and Natural Gas Production from Shale and Tight Formations (provider: eia) |
|
|
frequency : Literal['month', 'quarter', 'annual'] |
|
|
The frequency of the data. Default is 'month'. (provider: eia) |
|
|
|
|
|
Returns |
|
|
------- |
|
|
OBBject |
|
|
results : list[ShortTermEnergyOutlook] |
|
|
Serializable results. |
|
|
provider : Optional[str] |
|
|
Provider name. |
|
|
warnings : Optional[list[Warning_]] |
|
|
list of warnings. |
|
|
chart : Optional[Chart] |
|
|
Chart object. |
|
|
extra : Dict[str, Any] |
|
|
Extra info. |
|
|
|
|
|
ShortTermEnergyOutlook |
|
|
---------------------- |
|
|
date : date |
|
|
The date of the data. |
|
|
table : Optional[str] |
|
|
Table name for the data. |
|
|
symbol : str |
|
|
Symbol representing the entity requested in the data. |
|
|
order : Optional[int] |
|
|
Presented order of the data, relative to the table. |
|
|
title : Optional[str] |
|
|
Title of the data. |
|
|
value : Union[int, float] |
|
|
Value of the data. |
|
|
unit : Optional[str] |
|
|
Unit or scale of the data. |
|
|
|
|
|
Examples |
|
|
-------- |
|
|
>>> from openbb import obb |
|
|
>>> # Get the EIA's Short Term Energy Outlook. |
|
|
>>> obb.commodity.short_term_energy_outlook(provider='eia') |
|
|
>>> # Select the specific table of data from the STEO. Table 03d is World Crude Oil Production. |
|
|
>>> obb.commodity.short_term_energy_outlook(table='03d', provider='eia') |
|
|
""" |
|
|
|
|
|
return self._run( |
|
|
"/commodity/short_term_energy_outlook", |
|
|
**filter_inputs( |
|
|
provider_choices={ |
|
|
"provider": self._get_provider( |
|
|
provider, |
|
|
"commodity.short_term_energy_outlook", |
|
|
("eia",), |
|
|
) |
|
|
}, |
|
|
standard_params={ |
|
|
"start_date": start_date, |
|
|
"end_date": end_date, |
|
|
}, |
|
|
extra_params=kwargs, |
|
|
info={ |
|
|
"symbol": { |
|
|
"eia": {"multiple_items_allowed": True, "choices": None} |
|
|
}, |
|
|
"table": { |
|
|
"eia": { |
|
|
"multiple_items_allowed": False, |
|
|
"choices": [ |
|
|
"01", |
|
|
"02", |
|
|
"03a", |
|
|
"03b", |
|
|
"03c", |
|
|
"03d", |
|
|
"03e", |
|
|
"04a", |
|
|
"04b", |
|
|
"04c", |
|
|
"04d", |
|
|
"05a", |
|
|
"05b", |
|
|
"06", |
|
|
"07a", |
|
|
"07b", |
|
|
"07c", |
|
|
"07d1", |
|
|
"07d2", |
|
|
"07e", |
|
|
"08", |
|
|
"09a", |
|
|
"09b", |
|
|
"09c", |
|
|
"10a", |
|
|
"10b", |
|
|
], |
|
|
} |
|
|
}, |
|
|
"frequency": { |
|
|
"eia": { |
|
|
"multiple_items_allowed": False, |
|
|
"choices": ["month", "quarter", "annual"], |
|
|
} |
|
|
}, |
|
|
}, |
|
|
) |
|
|
) |
|
|
|
