OpenBB package with core functionality
Project description
THIS README IS A WORK IN PROGRESS
- THIS README IS A WORK IN PROGRESS
1. Introduction
This directory contains the OpenBB SDK's core functionality. It allows you to create an extension or a provider that will be automatically turned into REST API endpoint and allow sharing data between commands.
2. How to install?
Git clone
Git clone the repository:
git clone git@github.com:OpenBB-finance/OpenBBTerminal.git
Install
Go to openbb_sdk
folder and install the package.
cd openbb_sdk
poetry install
3. How to add an extension?
Project
Build a Python package:
poetry new openbb-sdk-my_extension
Command
Add a router and a command in the openbb_sdk/extensions/<my_extension_folder>/<openbb_my_extension>/<my_extension>_router.py
from openbb_core.app.router import Router
router = Router(prefix="/router_name")
@router.command
def some_command(
some_param: some_param_type,
) -> OBBject[Item]:
pass
If your command only makes use of a standard model defined inside openbb_provider/standard_models
directory, there is no need to repeat its structure in the parameters. Just pass the model name as an argument.
This is an example how we do it for stocks.load
which only depends on StockHistorical
model defined in openbb-provider
:
@router.command(model="StockHistorical")
def load(
cc: CommandContext, # user settings inside
provider_choices: ProviderChoices, # available providers
standard_params: StandardParams, # symbol, start_date, etc.
extra_params: ExtraParams, # provider specific parameters
) -> OBBject[BaseModel]:
"""Load stock data for a specific ticker."""
return OBBject(results=Query(**locals()).execute())
Entrypoint
Add an entrypoint for the extension inside your pyproject.toml
file.
packages = [{include = "openbb_sdk_my_extension"}]
...
[tool.poetry.extensions."openbb_extensions"]
extension_name_space = "my_extension.extension_router:router"
Install extension
Install your extension.
cd openbb_sdk_my_extension
poetry install
4. Usage
Update your credentials and default providers by modifying the .openbb_sdk/user_settings.json
inside your home directory:
{
"credentials": {
"benzinga_api_key": null,
"fmp_api_key": null,
"polygon_api_key": null,
"fred_api_key": null
},
"defaults": {
"routes": {
"/stocks/fa/balance": {
"provider": "polygon"
},
"/stocks/load": {
"provider": "fmp"
},
"/stocks/news": {
"provider": "benzinga"
}
}
}
}
Update your system settings by modifying the .openbb_sdk/system_settings.json
file inside your home directory:
{
"dbms_uri": null
}
4.1 Static version
Run your command:
from openbb import obb
output = obb.stocks.load(
symbol="TSLA",
start_date="2023-01-01",
provider="fmp",
chart=True
)
4.1.1. OBBject
Each command will always return a OBBject
. There you will find:
results
: the data returned by the commandNone
provider
: the provider name (only available provider names allowed) used to get the data orNone
warnings
:List[Warning_]
with warnings caught during the command execution orNone
error
: anError
with any exception that occurred during the command execution orNone
chart
: aChart
with chart data and format orNone
Helpers
To help you manipulate or visualize the data we make some helpers available.
to_dataframe
: transformsresults
into a pandas DataFrame
>>> output.to_dataframe()
open high low close adj_close ...
date
2023-07-21 268.00 268.00 255.8000 260.02 260.019989 ...
2023-07-20 279.56 280.93 261.2000 262.90 262.899994 ...
2023-07-19 296.04 299.29 289.5201 291.26 291.260010 ...
to_dict
: transformsresults
into a dict of lists
>>> output.to_dict()
{
'open': [268.0, 279.56, 296.04],
'high': [268.0, 280.93, 299.29],
'low': [255.8, 261.2, 289.5201],
'close': [260.02, 262.9, 291.26],
'adj_close': [260.019989, 262.899994, 291.26001],
...
}
show
: displayschart.content
to a chart
>>> output.show()
# Jupyter Notebook: inline chart
# Python Interpreter: opens a PyWry window with the chart
to_plotly_json
: proxy tochart.content
>>> output.to_plotly_json()
{
'data':[
{
'close': [260.02, 262.9, 291.26],
'decreasing': {'line': {'width': 1.1}},
'high': [268.0, 280.93, 299.29],
'increasing': {'line': {'width': 1.1}},
...
}
...
]
}
4.1.2. Utilities
User settings
These are your user settings, you can change them anytime and they will be applied. Don't forget to sdk.account.save()
if you want these changes to persist.
from openbb import obb
obb.user.profile
obb.user.credentials
obb.user.preferences
obb.user.defaults
System settings
Check your system settings.
from openbb import obb
obb.system
Coverage
Obtain the coverage of providers and commands.
>>> obb.coverage.commands
{
'.crypto.load': ['fmp', 'polygon'],
'.economy.const': ['fmp'],
'.economy.cpi': ['fred'],
...
}
>>> obb.coverage.providers
{
'fmp':
[
'.crypto.load',
'.economy.const',
'.economy.index',
...
],
'fred': ['.economy.cpi'],
...
}
4.1.3. OpenBB Hub Account
You can login to your OpenBB Hub account and save your credentials there to access them from any device.
from openbb import obb
# Login with personal access token
obb.account.login(pat="your_pat", remember_me=True) # pragma: allowlist secret
# Login with email, password or SDK token
obb.account.login(email="your_email", password="your_password", remember_me=True) # pragma: allowlist secret
# Change a credential
obb.user.credentials.polygon_api_key = "new_key" # pragma: allowlist secret
# Save account changes
obb.account.save()
# Refresh account with latest changes
obb.account.refresh()
# Logout
obb.account.logout()
4.1.4. Command execution
How do we execute commands?
OpenBB SDK core is a REST API powered by FastAPI. We use this feature to run commands both in a web server setting and also in the openbb
python package.
If you are using the openbb
package, running the command below triggers a "request" to the CommandRunner
class. The "request" will be similar to the one found in 4.2 Dynamic version. This will hit the endpoint matching the command and return the result.
from openbb import obb
obb.stocks.load(
symbol="TSLA",
start_date="2023-07-01",
end_date="2023-07-25",
provider="fmp",
chart=True
)
4.1.5. Environment variables
The OS environment is only read once before the program starts, so make sure you change the variable before importing the SDK. We use the prefix "OPENBB_" to avoid polluting the environment (no pun intended).
To apply an environment variable use one of the following:
-
Temporary: use this snippet
import os os.environ["OPENBB_DEBUG_MODE"] = "True" from openbb import sdk
-
Persistent: create a
.env
file in/.openbb_sdk
folder inside your home directory withOPENBB_DEBUG_MODE="False"
The variables we use are:
OPENBB_DEBUG_MODE
: enables verbosity while running the programOPENBB_DEVELOP_MODE
: points hub service to .co or .devOPENBB_AUTO_BUILD
: enables automatic SDK package build on importOPENBB_CHARTING_EXTENSION
: specifies which charting extension to useOPENBB_API_AUTH
: enables commands authentication in FastAPI
4.2 Dynamic version
You can also use the dynamic version to consume the API endpoints from Python itself.
In fact, the static version makes use of this feature to run each command. Take a look at the example below:
>>> from openbb_core.app.command_runner import CommandRunner
>>> runner = CommandRunner()
>>> output = runner.run(
"/stocks/load",
provider_choices={
"provider": "fmp",
},
standard_params={
"symbol": "TSLA",
"start_date": "2023-07-01",
"end_date": "2023-07-25",
},
extra_params={},
chart=True,
)
>>> output
OBBject
id: ... # UUID Tag
results: ... # Serializable results.
provider: ... # Provider name.
warnings: ... # List of warnings.
chart: ... # Chart object.
metadata: ... # Metadata.
5. REST API
OpenBB SDK comes with a ready to use Rest API built with FastAPI. Start the application using this command:
uvicorn openbb_core.api.rest_api:app --reload
5.1 Test users
There are 2 default users for testing purpose:
User "openbb"
- username : openbb
- password : openbb
User "finance"
- username : finance
- password : finance
6. Front-end typing
Here are libraries to get frontend typing.
openapi-typescript + openapi-fetch
openapi-generator
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for openbb_core-0.1.0a1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b1da36e5ce2c74f36ddd916befce2ffe9b30677a6dd96e21f5e8879f1c166738 |
|
MD5 | ea0a57e1e979bf49f92dbf736ca30601 |
|
BLAKE2b-256 | 01979542d2271100440038baf2230a863014650ef6b4a7029dfde62f59819d55 |