Skip to main content

OBBject

The OBBject (OpenBB Object) is at the heart of developing around the OpenBB Platform. Every command will return this class as the command output.

This class contains the following attributes:

  • results
    • This contains serializable data that was obtained by running the command.
  • provider
    • The name of the provider that was used to obtain the data.
  • warnings
    • Any warnings that were generated by the command.
  • extra
    • Additional metadata about the command run, including any arguments, the route, the timestamp, etc.

Additionally, the OBBject class contains a class variable, accessors, which is used to register extensions to the class. This is done by using the @obbject_accessor decorator. This decorator will register the class as an accessor to the OBBject class, and will be available on every OBBject returned by a command.


from openbb import obb
res = obb.equity.price.historical("AAPL")
res.accessors

An example with the openbb-charting extension would output:

{'charting'}

Find more about OBBject extensions here.

Example​

In the python interface, the OBBject class is returned by every command. The following example shows how to access the results of a command:

from openbb import obb

obbject = obb.equity.price.historical("AAPL", provider="fmp")

display(obbject)
OBBject

id: 0655d06a-8797-7310-8000-4daaa1d47936
results: [{'date': datetime.datetime(2023, 11, 21, 0, 0), 'open': 191.41, 'high': 1...
provider: fmp
warnings: None
chart: None
extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'fmp'}, 'standa...

The output type is <class 'openbb_core.app.model.obbject.OBBject'>.

If we look at the results attribute, we see that we are returned a list of the Data models used, i.e

obbject.results[0]
FMPEquityHistoricalData(date=2023-11-21 00:00:00, open=191.41, high=191.5, low=189.74, close=190.375, volume=24029603, vwap=190.54, label=November 21, 23, adj_close=190.375, unadjusted_volume=24029603.0, change=-1.03, change_percent=-0.5407241, change_over_time=-0.005407241)

In general, this will not be how you want to ingest or modify your data, so to help with this we have provided some methods.

OBBject Methods​

We understand that there is no one size fits all solution for data ingestion and manipulation, so we have provided a few methods to help with this and handle the conversion from Obbject to your preferred data type. These methods are accessed by running obbject.<method>.

to_dataframe()

One of the most popular libraries for python data manipulation, this method will return a pandas dataframe with the results.

We have designed this function to work with various data structures we have encountered. Given the time series nature of the data, we set the index to be date if that column appears in the models.

This also has the shorter alias to_df().

type(obb.equity.price.historical("AAPL", provider="fmp").to_dataframe())
<class 'pandas.core.frame.DataFrame'>
to_dict()

A very common data structure is to return the data in a dictionary. This model provides an interface to do so, with options to return the dictionary in different orientations, just as in the pandas to_dict() method. The default method will return a dictionary that allows you to index to obtain data:

to_dict = obb.equity.price.historical("AAPL", provider="fmp").to_dict()["open"][:10]
[150.16, 148.13, 149.45, 148.31, 145.14, 144.29, 141.4, 148.21, 145.96, 147.77]

Orienting as records will give you a list of dictionaries, commonly used in JSON data structures:

obb.equity.price.historical("AAPL", provider="fmp").to_dict("records")[0]
{'date': datetime.date(2023, 3, 6),
 'open': 153.79,
 'high': 156.3,
 'low': 153.46,
 'close': 153.83,
 'volume': 87558000,
 'vwap': 154.53,
 'label': 'March 06, 23',
 'adj_close': 153.01,
 'unadjusted_volume': 87558000.0,
 'change': 0.04,
 'change_percent': 0.02600949,
 'change_over_time': 0.0002600949}
to_numpy()

Returns numpy arrays of the results. Note that this loses the column names, so you will need to index the array to obtain the data.

to_numpy = obb.equity.price.historical("AAPL", provider="fmp").to_numpy()[:1]
[
  [datetime.date(2023, 5, 19), 176.39, 176.39, 174.94, 175.16,
  55809475, 175.72, 174.23, 55809475.0, -1.23, -0.0069732]
],
...
to_polars()

Growing in popularity, polars is a blazingly fast dataframe library. This method will return a polars dataframe.

Note that we do not include polars in the core dependency tree, so it needs to be installed separately.

show()

When a charting extension is installed, this method will display the chart if it was computed during the execution of the command, by setting the chart parameter to True.

OBBject Extensions​

OBBject extensions registers an accessor in each OBBject that is returned when a command is executed.

This page details the process for extending the OBBject class.

On this page