Skip to main content

Build New OBBject Extension

OpenBB provides some basic methods for interacting with common data structures that will be seen in the results attribute of the OBBject. If you are working with custom data, or adding new endpoints, it is possible that you will want to have your own methods for interacting with the data, and the OpenBB Platform provides a way to extend the OBBject class.

The architecture for extensions was designed to be similar to extensions and accessors for Pandas, and relies on plugins through the Poetry dependency management package.

This page will go through the steps for developing a simple extension for the OBBject class.

Folder structure​

example
├── README.md
├── openbb_example
│   └── __init__.py
├── poetry.lock
└── pyproject.toml

Writing the extension​

In this example the extension code all lives inside __init__.py.

First we create an Extension class instance to tell openbb-core our extension name and any required credentials to be available at obb.user.credentials.

Credentials are required only if authorization is required for data or services used by this extension. It could also be the connection to a database, or any other information that needs to be passed to the extension.

from openbb_core.app.model.extension import Extension

ext = Extension(name="example", credentials=["some_api_key"])

Then we define the extension's functionality. The decorator, @ext.obbject_accessor, registers an accessor in each OBBject that is returned when a command is executed. This accessor is just a namespace that will contain the methods defined in the decorated class.

For this example, we just add a method to say hi:

@ext.obbject_accessor
class Example:
    def __init__(self, obbject):
        self._obbject = obbject

    def hello(self):
        api_key = self._obbject._user_settings.credentials.some_api_key.get_secret_value()
        print(f"Hello, this is my credential: {api_key}!")

Entry Point​

The pyproject.toml file will specify the usual setup and dependency information. Additionally, we need to include the following block:

[tool.poetry.plugins."openbb_obbject_extension"]
example = "openbb_example:ext"

With this in the file, we can install the extension by running poetry install from the extension folder.

Using the extension​

Now that the extension is installed and built, we can use it! Because we are extending the OBBject, this will be available on any function:

>>> from openbb import obb
>>> obb.user.credentials.some_api_key = "test"
>>> obbject = obb.equity.price.historical("AAPL")
>>> obbject.example.hello()
Hello, this is my credential: test!

In this example, we have added obbject.example as the extension and can use the .hello() functionality right from our OBBject.

On this page