jerry/OpenBB
1
0
Fork 0
mirror of https://github.com/OpenBB-finance/OpenBB.git synced 2026-10-27 12:40:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs/new-working-docs: New working docs branch (#5768)

Browse Source 
* move old example notebooks to v3 folder, update loadHistoricalPriceData and add findSymbols

* Create README.md

* Update README.md

* Update README.md

* Update README.md

* Vertical diagram instead

* important classes

* core dependencies

* folder structure

* devtools

* swap order

* fix github pages deploy issue

* development index

* delete expectations for developers

* devtools

* obbject stuff

* add

* installation

* hub sync

* idk if i committed already

* add usage page for financial statements

* add link to reference page

* syntax

* numbers

* nearly --> more than

* easier to read code blocks

* codespell

* removing mention to provider

* add 'orientation' for to_dict

* info card for output user preference

* put it in a code block

* correct user_settings.json example

* syntax corrections

* fix sentence

* get rid of floating point mathc

* get rid of other floating point math

* add companion example notebook for financial statements, and new section

* historical prices usage page

* codespell

* add commitment of traders section to usage

* add a note

* codespell

* get rid of equals sign

* Cleanup docs. with @the-praxs

* install

* obbject extend

* spell

* HeadTitle thingies

* Update obbject_extensions.md

* Update obbject_extensions.md

* typo

* Update architectural_considerations.md

* point to the TET pattern

* optional vs required

* reviewing the  patterns. removed the --pre flag under the assumption this will be the final docs for the release cc @deeleeramone

* add a walkthrough

* spelling

* Add more in the introduction

* validator examples

* update Copper-to-Gold notebook example for V4

* Update README.md

* QA Caveats w @the-praxs

* info on class outputs

* merge add data sources and add data points

* disclaimer on cookiecutter

* add missing import to example

* slight syntax change

* missing code block

* missing import

* update intrinio example syntax

* intrinio syntax update

* urls

* core and provider merged

* example syntax

* grammar

* Update API banner link

* quick-fix-docs cc @minhhoang1023

* Update pip install command for v3

* remove --pre note block

* update landing image

---------

Co-authored-by: Henrique Joaquim <h.joaquim@campus.fct.unl.pt>
Co-authored-by: Luqman <luqazino@gmail.com>
Co-authored-by: James Maslek <jmaslek11@gmail.com>
Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>
Co-authored-by: montezdesousa <79287829+montezdesousa@users.noreply.github.com>
Co-authored-by: Theodore Aptekarev <aptekarev@gmail.com>
Co-authored-by: Pratyush Shukla <ps4534@nyu.edu>
This commit is contained in:
Danglewood
2023-11-30 17:09:25 -08:00
committed by GitHub
parent 10cfd1e961
commit c047cfeddd
44 changed files with 137561 additions and 118963 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
examples/README.md vendored
View File

@@ -1,18 +1,35 @@
# Jupyter Notebook Examples Using the OpenBB SDK
# Jupyter Notebook Examples Using the OpenBB Platform
This folder is a collection of example notebooks that demonstrate some of the ways to get started using the OpenBB SDK. To run them, ensure that the active kernel selected is the same Python virtual environment where OpenBB was installed.
This folder is a collection of example notebooks that demonstrate some of the ways to get started with using the OpenBB Platform. To run them, ensure that the active kernel selected is the same Python virtual environment where OpenBB was installed.
## Table of Contents
### findSymbols
This notebook provides an introduction to discovering, finding, and searching ticker symbols.
- Search
- Find company and institutional filings
- Screen stocks by region and metrics
### loadHistoricalPriceData
This notebook walks through collecting historical price data using a variety of methods and sources.
This notebook walks through collecting historical price data, at different intervals, using a variety of sources.
- Loading data with different intervals, and changing sources
- A brief explanation of ticker symbology
- Resampling a time series index
- Some differences between providers, and comparing outputs
### financialStatements
This set of examples introduces financial statements in the OpenBB Platform and compares the free cash flow yields of large-cap retail industry companies.
- Financial statements
- What to expect with data from different sources
- Financial attributes
- Ratios and other metrics
- Loading data with different intervals, and changing sources.
- A brief explanation of ticker symbology.
- Using other functions and modules to load data with besides `openbb.stocks.load()`.
- Gang-loading a list of tickers' price data in a single call.
- Drawing candle and line charts.
### copperToGoldRatio
@@ -21,56 +38,4 @@ This notebook explains how to calculate and plot the Copper-to-Gold ratio.
- Loading historical front-month futures prices.
- Getting the historical series from FRED for the 10-year constant maturity US treasury bill.
- Performing basic DataFrame operations.
- Creating OpenBB Figure objects, and plotting on two y-axis.
### realizedVolatilityModels
This notebook demonstrates the six, realized volatility models with in the Technical Analysis module.
- Explore differences between:
- Standard Deviation
- Parkinson
- Hodges-Tompkins
- Garman-Klass
- Rogers-Satchell
- Yang-Zhang
- Creating and plotting realized volatility cones.
- Overlaying multiple time series.
- Use the calculated outputs as inputs to a forecast model.
### usdLiquidityIndex
This notebook demonstrates how to query the Federal Reserve Economic Database and recreate the USD Liquidity Index.
- Search FRED for series IDs.
- Load multiple series as a single call.
- Unpacking the data response from the FRED query.
- Perform arithmetic operations on a DataFrame.
- Normalization methods for a series or DataFrame.
- Simple processes for creating charts.
### optionsChains
This notebook demonstrates how to fetch and work with options chains data.
- Use the new method for loading options chains data.
- Examine the differences of the data, between sources.
- Calculate and visualize volume and open interest by strike and expiration.
- Calculate and visualize the Net Delta Exposure, in dollars, by strike and expiration.
- Visualize the term structure of the implied volatility skew.
- Get tables with multiple single-leg options strategies.
### googleColabInstallation
This notebook demonstrates how to install the OpenBB SDK within Google Colab.
### volumeAtPrice
Volume-at-price is a chart used by technical analysts as a visual gauge to where the trading levels are concentrated, relative to price and volume. In short, it is the sum of volume at different price levels. This notebook utilizes individual components of the OpenBB SDK and combines them to build a new view.
- Price
- Volume
- VWAP
- SMA
- OpenBBFigure
- Creating charts with Plotly Graph Objects.

97770
examples/copperToGoldRatio.ipynb vendored
View File

File diff suppressed because it is too large Load Diff

1059
examples/financialStatements.ipynb vendored Normal file
View File

File diff suppressed because it is too large Load Diff

1409
examples/findSymbols.ipynb vendored Normal file
View File

File diff suppressed because it is too large Load Diff

29579
examples/loadHistoricalPriceData.ipynb vendored
View File

File diff suppressed because it is too large Load Diff

79
examples/v3/README.md vendored Normal file
View File

@@ -0,0 +1,79 @@
# Jupyter Notebook Examples Using the OpenBB SDK
This folder is a collection of example notebooks that demonstrate some of the ways to get started using the OpenBB SDK. To run them, ensure that the active kernel selected is the same Python virtual environment where OpenBB was installed.
## Table of Contents
:::note
These examples are for a deprecated version, the code and examples may have bugs and outdated syntax.
:::
### loadHistoricalPriceData
This notebook walks through collecting historical price data using a variety of methods and sources.
- Loading data with different intervals, and changing sources.
- A brief explanation of ticker symbology.
- Using other functions and modules to load data with besides `openbb.stocks.load()`.
- Gang-loading a list of tickers' price data in a single call.
- Drawing candle and line charts.
### copperToGoldRatio
This notebook explains how to calculate and plot the Copper-to-Gold ratio.
- Loading historical front-month futures prices.
- Getting the historical series from FRED for the 10-year constant maturity US treasury bill.
- Performing basic DataFrame operations.
- Creating OpenBB Figure objects, and plotting on two y-axis.
### realizedVolatilityModels
This notebook demonstrates the six, realized volatility models with in the Technical Analysis module.
- Explore differences between:
- Standard Deviation
- Parkinson
- Hodges-Tompkins
- Garman-Klass
- Rogers-Satchell
- Yang-Zhang
- Creating and plotting realized volatility cones.
- Overlaying multiple time series.
- Use the calculated outputs as inputs to a forecast model.
### usdLiquidityIndex
This notebook demonstrates how to query the Federal Reserve Economic Database and recreate the USD Liquidity Index.
- Search FRED for series IDs.
- Load multiple series as a single call.
- Unpacking the data response from the FRED query.
- Perform arithmetic operations on a DataFrame.
- Normalization methods for a series or DataFrame.
- Simple processes for creating charts.
### optionsChains
This notebook demonstrates how to fetch and work with options chains data.
- Use the new method for loading options chains data.
- Examine the differences of the data, between sources.
- Calculate and visualize volume and open interest by strike and expiration.
- Calculate and visualize the Net Delta Exposure, in dollars, by strike and expiration.
- Visualize the term structure of the implied volatility skew.
- Get tables with multiple single-leg options strategies.
### googleColabInstallation
This notebook demonstrates how to install the OpenBB SDK within Google Colab.
### volumeAtPrice
Volume-at-price is a chart used by technical analysts as a visual gauge to where the trading levels are concentrated, relative to price and volume. In short, it is the sum of volume at different price levels. This notebook utilizes individual components of the OpenBB SDK and combines them to build a new view.
- Price
- Volume
- VWAP
- SMA
- OpenBBFigure

95896
examples/v3/copperToGoldRatio.ipynb vendored Normal file
View File

File diff suppressed because it is too large Load Diff

0
examples/googleColabInstallation.ipynb → examples/v3/googleColabInstallation.ipynb vendored
View File

28256
examples/v3/loadHistoricalPriceData.ipynb vendored Normal file
View File

File diff suppressed because it is too large Load Diff

0
examples/optionsChains.ipynb → examples/v3/optionsChains.ipynb vendored
View File

0
examples/realizedVolatilityModels.ipynb → examples/v3/realizedVolatilityModels.ipynb vendored
View File

0
examples/usdLiquidityIndex.ipynb → examples/v3/usdLiquidityIndex.ipynb vendored
View File

0
examples/volumeAtPrice.ipynb → examples/v3/volumeAtPrice.ipynb vendored
View File

3
openbb_platform/README.md vendored
View File

@@ -18,6 +18,7 @@ The command below provides access to the core functionalities behind the OpenBB
```bash
pip install openbb
pip install openbb
```
To install extensions that expand the core functionalities specify the extension name or use `all` to install all.
@@ -27,7 +28,7 @@ To install extensions that expand the core functionalities specify the extension
pip install openbb[charting]
# Install all available extensions
pip install openbb[all]
pip install openbb[all] --pre
``````
> Note: These instruction are specific to v4. For installation instructions and documentation for v3 go to our [website](https://docs.openbb.co/sdk).

32
website/content/platform/development/contributor-guidelines/quality_assurance.md vendored
View File

@@ -101,3 +101,35 @@ pip install tuna
python -X importtime openbb/__init__.py 2> import.log
tuna import.log
```
## Known caveats
When using the OpenBB QA Framework it is important to be aware of the following caveats:
- The tests are semi-automated and might require manual intervention. For example, adjusting out-of-top level imports or changing specific arguments for a given payload.
- The integration tests are more complex and if your newly added provider integration is already covered by the
integration tests from previous commands or providers, you will need to manually inject the payload for the new
provider.
- In the integration test parametrized payload, the first item is always the set of standard parameters. Every
consecutive item is a set of parameters for a specific provider with the standard parameters included.
- The integration tests require you to be explicit, by using all of the standard parameters and provider-specific
parameters in the payload. If you want to exclude a parameter, you can use `None` as its value.
- The integration tests require you to be explicit by specifying the `provider` parameter in provider-specific
payloads.
- When recording unit tests, you might run into issues with the cache that is tied to your specific provider and present
on your local machine. You will know that this is the case if your tests pass locally, but fail on the CI. To fix this,
you can delete the cache file from your local machine and re-record the tests.
> Note that the cache is likely located here:
> Windows: `C:\Users\user\AppData\Local\`
> Linux: `/home/user/.cache/`
> Mac: `/Users/user/Library/Caches`
- Some providers (we are aware only of YFinance so far) do an additional request when used from the US region. As our CI
is running from the US region, this might cause the tests to fail. A workaround for this is to use a VPN to record the
tests from a different region.

7
website/content/platform/development/contributor-guidelines/sharing_extensions.md vendored
View File

@@ -23,7 +23,8 @@ To publish your extension to PyPI, you'll need to have a PyPI account and a PyPI
### Setup
Create an account and get an API token from <https://pypi.org/manage/account/token/>
Store the token with
Store the token with:
```bash
poetry config pypi-token.pypi pypi-YYYYYYYY
@@ -31,7 +32,7 @@ poetry config pypi-token.pypi pypi-YYYYYYYY
### Release
`cd` into the directory where your extension `pyproject.toml` lives and make sure that the `pyproject.toml` specifies the version tag you want to release and run.
`cd` into the directory where your extension `pyproject.toml` lives and make sure that the `pyproject.toml` specifies the version tag you want to release and run:
```bash
poetry build
@@ -39,7 +40,7 @@ poetry build
This will create a `/dist` folder in the directory, which will contain the `.whl` and `tar.gz` files matching the version to release.
If you want to test your package locally you can do it with
If you want to test your package locally you can do it with:
```bash
pip install dist/openbb_[FILE_NAME].whl

130
website/content/platform/development/contributor-guidelines/write_code_commit.md vendored
View File

@@ -15,6 +15,136 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Write Code and Commit - Contributor Guidelines - Development | OpenBB Platform Docs" />
## Folder Structure Overview
<details>
<summary>OpenBB Platform file tree</summary>
```bash
├── extensions
│   ├── charting
│   │   ├── __init__.py
│   │   ├── integration
│   │   ├── openbb_charting
│   │   ├── pyproject.toml
│   │   ├── README.md
│   │   └── tests
│   ├── crypto
│   │   ├── integration
│   │   ├── openbb_crypto
│   │   ├── poetry.lock
│   │   ├── pyproject.toml
│   │   ├── README.md
│   │   └── tests
│   ├── currency
│   │   ├── integration
│   │   ├── openbb_currency
│   │   ├── poetry.lock
│   │   ├── pyproject.toml
│   │   ├── README.md
│   │   └── tests
...
├── providers
│   ├── alpha_vantage
│   │   ├── __init__.py
│   │   ├── openbb_alpha_vantage
│   │   ├── poetry.lock
│   │   ├── pyproject.toml
│   │   ├── README.md
│   │   └── tests
│   ├── benzinga
│   │   ├── dist
│   │   ├── __init__.py
│   │   ├── openbb_benzinga
│   │   ├── poetry.lock
│   │   ├── pyproject.toml
│   │   ├── README.md
│   │   └── tests
...
├── openbb
│   ├── __init__.py
│   ├── package
├── platform
│   ├── core
│   │   ├── integration
│   │   ├── openbb_core
│   │   │   ├── api
│   │   │   ├── app
│   │   ├── poetry.lock
│   │   ├── pyproject.toml
│   │   ├── README.md
│   │   └── tests
│   │  
│   └── provider
│   ├── openbb_provider
│   ├── poetry.lock
│   ├── pyproject.toml
│   ├── README.md
│   └── tests
├── EXTENSIONS.md
├── integration
├── PROVIDERS.md
├── pyproject.toml
├── README.md
└── tests
```
</details>
The OpenBB Platform is organized into several key directories, each serving a specific purpose in the architecture of the system. Below is an overview of the main directories and their roles:
### `extensions`
This directory houses the various extensions available in the OpenBB Platform. Each extension has its own folder, containing the necessary files for its operation.
Each extension typically includes:
- `integration`: Integration tests.
- `openbb_[extension_name]`: Main codebase for the extension.
- `poetry.lock` and `pyproject.toml`: Dependency management files.
- `README.md`: Documentation specific to the extension.
- `tests`: Unit tests for the extension.
### `providers`
This directory contains the data providers integrated with the OpenBB Platform. Each provider has its own subdirectory.
Common files in each provider include:
- `openbb_[provider_name]`: Core code for the provider's integration.
- `poetry.lock` and `pyproject.toml`: Files for managing dependencies.
- `README.md`: Documentation for the provider.
- `tests`: Unit tests for the provider.
### `openbb`
This is the main directory for the OpenBB package, containing the core functionalities and modules of the OpenBB Platform.
- `package`: Contains the main package files and modules, i.e., the static auto generated files that serve the Python interface.
### `platform`
This directory hosts the core platform functionalities (`core`) which is the central part of the OpenBB Platform application.
### Root Directory Files
In the root directory, several important files are present:
- `EXTENSIONS.md`: List of available OpenBB extensions and its maintainers.
- `PROVIDERS.md`: List of available OpenBB providers and its maintainers
- `pyproject.toml`: The main file for managing the platform dependencies.
- `README.md`: The primary entry point for the OpenBB Platform documentation.
- `tests`: Contains tests that are relevant to the overall platform.
This structure allows for modular development and easy integration of new features, extensions, and providers, making the OpenBB Platform highly scalable and adaptable.
## How to create a PR?
To create a PR to the OpenBB Platform, you'll need to fork the repository and create a new branch.

7
website/content/platform/development/dependency_management.md vendored
View File

@@ -1,6 +1,6 @@
---
title: Dependency Management
sidebar_position: 2
sidebar_position: 3
description: Dealing with dependencies when developing with the OpenBB Platform. Learn
how to add new dependencies to the OpenBB Platform and how to add new dependencies
to your custom extension.
@@ -17,8 +17,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
## High-Level Overview
- **Provider**: The base package with no dependencies on other `openbb` packages.
- **Core**: Depends on the Provider and serves as the main infrastructural package.
- **Core**: Serves as the main infrastructural package.
- **Extensions**: Utility packages that leverage Core's infrastructure. Each extension is its own package.
- **Providers**: Utility packages extending functionality to different providers, where each provider is its own package.
@@ -41,7 +40,7 @@ Ensure you're in a fresh conda environment before adjusting dependencies.
## Core and Extensions
### Installation
### Dev Installation
For development setup, use the provided script to install all extensions and their dependencies:

83
website/content/platform/development/developer-guidelines/add_custom_data_sources.md vendored
View File

@@ -1,83 +0,0 @@
---
title: Add Custom Data Sources
sidebar_position: 5
description: This guide provides detailed instructions on how to add custom data sources to the OpenBB Platform. It covers the process of creating a custom extension, standardizing data, defining models, and creating a Fetcher class.
keywords:
- OpenBB custom data sources
- Data standardization
- Pydantic models
- Fetcher class
- OpenBB extensions
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Add Custom Data Sources - Developer Guidelines - Development | OpenBB Platform Docs" />
You will get your data either from a CSV file, local database or from an API endpoint.
If you don't want or don't need to partake in the data standardization framework, you have the option to add all the logic straight inside the router file. This is usually the case when you are returning custom data from your local CSV file, or similar. Keep in mind that we also serve the REST API and that you shouldn't send non-serializable objects as a response (e.g. a pandas dataframe).
Saying that, we highly recommend following the standardization framework, as it will make your life easier in the long run and unlock a set of features that are only available to standardized data.
When standardizing, all data is defined using two different pydantic models:
1. Define the [query parameters](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/query_params.py) model.
2. Define the resulting [data schema](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/data.py) model.
> The models can be entirely custom, or inherit from the OpenBB standardized models.
> They enforce a safe and consistent data structure, validation and type checking.
We call this the ***Know-Your-Data*** principle.
After you've defined both models, you'll need to define a `Fetcher` class which contains three methods:
1. `transform_query` - transforms the query parameters to the format of the API endpoint.
2. `extract_data` - makes the request to the API endpoint and returns the raw data.
3. `transform_data` - transforms the raw data into the defined data model.
> Note that the `Fetcher` should inherit from the [`Fetcher`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/fetcher.py) class, which is a generic class that receives the query parameters and the data model as type parameters.
After finalizing your models, you need to make them visible to the Openbb Platform. This is done by adding the `Fetcher` to the `__init__.py` file of the `<your_package_name>/<your_module_name>` folder as part of the [`Provider`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/provider.py).
Any command, that uses the `Fetcher` class you've just defined, will be calling the `transform_query`, `extract_data` and `transform_data` methods under the hood in order to get the data and output it do the end user.
If you're not sure what's a command and why is it even using the `Fetcher` class, follow along!
## OpenBB Platform Commands
The OpenBB Platform will enable you to query and output your data in a very simple way.
> Any Platform endpoint will be available both from a Python interface and the API.
The command definition on the Platform follows [FastAPI](https://fastapi.tiangolo.com/) conventions, meaning that you'll be creating **endpoints**.
The Cookiecutter template generates for you a `router.py` file with a set of examples that you can follow, namely:
- Perform a simple `GET` and `POST` request - without worrying on any custom data definition.
- Using a custom data definition so you get your data the exact way you want it.
You can expect the following endpoint structure when using a `Fetcher` to serve the data:
```python
@router.command(model="Example")
def model_example(
cc: CommandContext,
provider_choices: ProviderChoices,
standard_params: StandardParams,
extra_params: ExtraParams,
) -> OBBject[BaseModel]:
"""Example Data."""
return OBBject(results=Query(**locals()).execute())
```
Let's break it down:
- `@router.command(...)` - this tells the OpenBB Platform that this is a command.
- `model="Example"` - this is the name of the `Fetcher` dictionary key that you've defined in the `__init__.py` file of the `<your_package_name>/<your_module_name>` folder.
- `cc: CommandContext` - this contains a set of user and system settings that is useful during the execution of the command - eg. api keys.
- `provider_choices: ProviderChoices` - all the providers that implement the `Example` `Fetcher`.
- `standard_params: StandardParams` - standardized parameters that are common to all providers that implement the `Example` `Fetcher`.
- `extra_params: ExtraParams` - it contains the provider specific arguments that are not standardized.
You only need to change the `model` parameter to the name of the `Fetcher` dictionary key and everything else will be handled by the OpenBB Platform.

132
website/content/platform/development/developer-guidelines/add_data_point.md vendored
View File

@@ -1,7 +1,7 @@
---
title: Add a Data Point
title: Integrating Data Sources and Points
sidebar_position: 3
description: This guide provides detailed instructions on how to add a new data point to the OpenBB Platform. It covers the process of creating a new provider, defining query parameters and data output models, and building a Fetcher class.
description: This comprehensive guide is designed to assist developers in integrating custom data sources and adding new data points to the OpenBB Platform. It covers the creation of custom extensions, standardization of data, definition of models, and the construction of a Fetcher class. This document is essential for developers looking to enhance the platform with new data capabilities.
keywords:
- OpenBB Platform
- Data point addition
@@ -9,26 +9,49 @@ keywords:
- Query parameters
- Data output models
- Fetcher class
- OpenBB custom data sources
- Data standardization
- Pydantic models
- OpenBB extensions
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Add a Data Point - Developer Guidelines - Development | OpenBB Platform Docs" />
<HeadTitle title="Integrating Data Sources and Points - Developer Guidelines - Development | OpenBB Platform Docs" />
In this section, we'll be adding a new data point to the OpenBB Platform. We will add a new provider with an existing [standard data](https://github.com/OpenBB-finance/OpenBBTerminal/tree/develop/openbb_platform/core/provider/standard_models) model.
In this section, we'll be adding a new data point to the OpenBB Platform. We will add a new provider with an existing model, imported from: [openbb_core.provider.standard_models](/platform/data_models).
## Identify which type of data you want to add
## Identify your data
In this example, we'll be adding OHLC stock data that is used by the `obb.equity.price.historical` command.
You will get your data either from a CSV file, local database or from an API endpoint.
Note that, if no command exists for your data, we need to add one under the right router.
Each router is categorized under different extensions (stocks, currency, crypto, etc.).
:::note
If you don't want or don't need to partake in the data standardization framework, you have the option to add all the logic straight inside the router file. This is usually the case when you are returning custom data from your local CSV file, or similar. Keep in mind that we also serve the REST API and that you shouldn't send non-serializable objects as a response (e.g. a pandas dataframe).
:::
We highly recommend following the standardization framework, as it will make your life easier in the long run and unlock a set of features that are only available to standardized data.
When standardizing, all data is defined using two different pydantic models:
1. Define the [query parameters](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/query_params.py) model.
2. Define the resulting [data schema](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/data.py) model.
> The models can be entirely custom, or inherit from the OpenBB standardized models.
> They enforce a safe and consistent data structure, validation and type checking.
We call this the ***Know-Your-Data*** principle.
In the following example, we'll be adding historical, end-of-day OHLC (open, high, low, close) equity data that is used by the `obb.equity.price.historical` command.
Note that if no command exists for your data, we need to add one under the right router.
Each router is categorized under the relevant extension (equity, currency, crypto, etc.).
## Check if the standard model exists
Given the fact that there's already an endpoint for OHLCV stock data, we can check if the standard exists.
Given the fact that there's already an endpoint for historical equity data, we can check for the existing standard model.
In this case, it's `EquityHistorical` which can be found in `/OpenBBTerminal/openbb_platform/core/provider/standard_models/equity_historical`.
In this case, it's `EquityHistorical` which can be found in the list of data models [here](/platform/data_models).
If the standard model doesn't exist:
@@ -56,7 +79,8 @@ class <ProviderName>EquityHistoricalQueryParams(EquityHistoricalQueryParams):
### Create Data Output model
The data output is the data that is returned by the API endpoint.
The data output model is a data class containing Fields mapping the response of the API.
For the `StockHistorical` example, this would look like the following:
```python
@@ -73,11 +97,44 @@ class <ProviderName>EquityHistoricalData(EquityHistoricalData):
> Note that, since `EquityHistoricalData` inherits from pydantic's `BaseModel`, we can leverage validators to perform additional checks on the output model. A very good example of this, would be to transform a string date into a datetime object.
### Optional vs Required fields when creating models
When creating a new model, you need to decide whether a field is required or not.
This is done by using `typing`'s `Optional` when defining the field type.
In the context of the **Standard Models**:
- Required: all the providers use that field (either to query or to present data).
- Optional: at least two providers use that field (either to query or to present data).
In the context of the **Provider Models**:
- Required: the provider uses that field:
- Needs the field to query the API.
- The data presented by the provider contains that field.
- Optional: the may or may not use that field:
- If the user uses that field, the provider will also use it to query the API.
- The data presented by the provider may or may not contain that field.
> Learn more about Pydantic's fields [here](https://docs.pydantic.dev/latest/concepts/fields/).
### Build the Fetcher
The `Fetcher` class is responsible for making the request to the API endpoint and providing the output.
The `Fetcher` class is responsible for processing the Query and turning that into an API request and finally returning the data model. Each fetcher contains three methods that are implemented by its abstract definition:
It will receive the Query Parameters, and it will return the output while leveraging the pydantic model schemas.
- `transform_query`
- Convert a standard query into a provider-specific query
- `extract_data`
- Get the data from the API endpoint
- `transform_data`
- Convert the API response data into a list of standard data models.
> Read more on the `TET` pattern [here](/platform/development/developer-guidelines/architectural_considerations#the-tet-pattern).
:::note
Note that the `Fetcher` should inherit from the [`Fetcher`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/fetcher.py) class, which is a generic class that receives the query parameters and the data model as type parameters.
:::
For the `EquityHistorical` example, this would look like the following:
@@ -117,11 +174,10 @@ class <ProviderName>EquityHistoricalFetcher(
return [<ProviderName>EquityHistoricalData.model_validate(d) for d in data]
```
> Make sure that you're following the TET pattern when building a `Fetcher` - **Transform, Extract, Transform**. See more on this [here](/platform/contributing/developer-guidelines/architectural_considerations#the-tet-pattern).
## Make the provider visible
In order to make the new provider visible to the OpenBB Platform, you'll need to add it to the `__init__.py` file of the `providers/<provider_name>/openbb_<provider_name>/` folder.
After finalizing your models, you need to make them visible to the Openbb Platform.
This is done by adding the `Fetcher` to the `__init__.py` file of the `<your_package_name>/<your_module_name>` folder as part of the [`Provider`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/provider/openbb_core/provider/abstract/provider.py).
```python
"""<Provider Name> Provider module."""
@@ -140,6 +196,50 @@ from openbb_<provider_name>.models.equity_historical import <ProviderName>Equity
)
```
Any command, that uses the `Fetcher` class you've just defined, will be calling the `transform_query`, `extract_data` and `transform_data` methods under the hood in order to get the data and output it do the end user.
If the provider does not require any credentials, you can remove that parameter. On the other hand, if it requires more than 2 items to authenticate, you can add a list of all the required items to the `credentials` list.
:::info
After running `pip install .` on `openbb_platform/providers/<provider_name>` your provider should be ready for usage, both from the Python interface and the API.
:::
If you're not sure what's a command and why is it even using the `Fetcher` class, follow along!
## OpenBB Platform Commands
The OpenBB Platform will enable you to query and output your data in a very simple way.
> Any Platform endpoint will be available both from a Python interface and the API.
The command definition on the Platform follows [FastAPI](https://fastapi.tiangolo.com/) conventions, meaning that you'll be creating **endpoints**.
The [Cookiecutter template](https://github.com/OpenBB-finance/openbb-cookiecutter) generates for you a `router.py` file with a set of examples that you can follow, namely:
- Perform a simple `GET` and `POST` request - without worrying on any custom data definition.
- Using a custom data definition so you get your data the exact way you want it.
You can expect the following endpoint structure when using a `Fetcher` to serve the data:
```python
@router.command(model="Example")
def model_example(
cc: CommandContext,
provider_choices: ProviderChoices,
standard_params: StandardParams,
extra_params: ExtraParams,
) -> OBBject[BaseModel]:
"""Example Data."""
return OBBject(results=Query(**locals()).execute())
```
Let's break it down:
- `@router.command(...)` - this tells the OpenBB Platform that this is a command.
- `model="Example"` - this is the name of the `Fetcher` dictionary key that you've defined in the `__init__.py` file of the `<your_package_name>/<your_module_name>` folder.
- `cc: CommandContext` - this contains a set of user and system settings that is useful during the execution of the command - eg. api keys.
- `provider_choices: ProviderChoices` - all the providers that implement the `Example` `Fetcher`.
- `standard_params: StandardParams` - standardized parameters that are common to all providers that implement the `Example` `Fetcher`.
- `extra_params: ExtraParams` - it contains the provider specific arguments that are not standardized.
You only need to change the `model` parameter to the name of the `Fetcher` dictionary key and everything else will be handled by the OpenBB Platform.

193
website/content/platform/development/developer-guidelines/architectural_considerations.md vendored
View File

@@ -8,6 +8,7 @@ keywords:
- Import Statements
- TET Pattern
- Fetcher Classes
- Core Dependencies
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
@@ -16,6 +17,112 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
## Important classes
### The `Data` class
The OpenBB Standardized Data Model.
The `Data` class is a flexible Pydantic model designed to accommodate various data structures
for OpenBB's data processing pipeline as it's structured to support dynamic field definitions.
The model leverages Pydantic's powerful validation features to ensure data integrity while
providing the flexibility to handle extra fields that are not explicitly defined in the model's
schema. This makes the `Data` class ideal for working with datasets that may have varying
structures or come from heterogeneous sources.
Key Features:
- Dynamic field support: Can dynamically handle fields that are not pre-defined in the model,
allowing for great flexibility in dealing with different data shapes.
- Alias handling: Utilizes an aliasing mechanism to maintain compatibility with different naming
conventions across various data formats.
Usage:
The `Data` class can be instantiated with keyword arguments corresponding to the fields of the
expected data. It can also parse and validate data from JSON or other serializable formats, and
convert them to a `Data` instance for easy manipulation and access.
Example:
```python
from openbb_core.provider.abstract.data import Data
# Direct instantiation
data_record = Data(name="OpenBB", value=42)
# Conversion from a dictionary
data_dict = {"name": "OpenBB", "value": 42}
data_record = Data(**data_dict)
```
The class is highly extensible and can be subclassed to create more specific models tailored to
particular datasets or domains, while still benefiting from the base functionality provided by the
`Data` class.
### The `QueryParams` class
The QueryParams class is a standardized model for handling query input parameters in the OpenBB platform. It extends the BaseModel from the Pydantic library, which provides runtime data validation and serialization.
The class includes a dictionary, `__alias_dict__`, which can be used to map the original parameter names to aliases. This can be useful when dealing with different data providers that may use different naming conventions for similar parameters.
The `__repr__` method provides a string representation of the QueryParams object, which includes the class name and a list of the model's parameters and their values.
The `model_config` attribute is a `ConfigDict` instance that allows extra fields not defined in the model and populates the model by name.
The `model_dump` method is used to serialize the model into a dictionary. If the `__alias_dict__` is not empty, it will use the aliases defined in it for the keys in the returned dictionary. If the `__alias_dict__` is empty, it will return the original serialized model.
### The `Fetcher` class
The `Fetcher` class is an abstract base class designed to provide a structured way to fetch data from various providers. It uses generics to allow for flexibility in the types of queries, data, and return values it handles.
The class defines a series of methods that must be implemented by any subclass: `transform_query`, `extract_data`, and `transform_data`. These methods represent the core steps of fetching data: transforming input parameters into a provider-specific query, extracting data from the provider using the query, and then transforming the provider-specific data into a desired format.
The `fetch_data` method orchestrates these steps, taking in parameters and optional credentials, and returning the transformed data.
The class also includes a test method for validating the functionality of a fetcher, performing assertions on each stage of the fetch process.
Additionally, the `Fetcher` class uses a custom `classproperty` decorator to define class-level properties that return the types of the query parameters, return value, and data.
The `require_credentials` class variable indicates whether credentials are needed to fetch data from the provider. This can be overridden by subclasses as needed.
:::info
The `Fetcher` class implementation is based on the [TET pattern](/platform/development/developer-guidelines/architectural_considerations#the-tet-pattern). This pattern imposes a standardized structure, namely:
- Transform the query: the output of this method should be `QueryParams` child.
- Extract the data: the output of this method can be `Any` but it's recommended to be a `Dict` (will facilitate the next step of the fetcher's action, the data transformation).
- Transform the data: the output of this method should be a `List[Data]` or `Data` (or a child of it).
:::
### The `OBBject` class
The OBBject class is a generic class in the OpenBB platform that represents a standardized object for handling and manipulating data fetched from various providers. It extends the `Tagged` class and uses Python's generics to allow flexibility in the type of results it can handle.
The class includes several fields such as results, provider, warnings, chart, and extra, which respectively represent the fetched data, the data provider, any warnings generated during data fetching, an optional chart object for visualizing the data, and a dictionary for any additional information.
The class provides several methods for converting the fetched data into different formats, including `to_df` (or `to_dataframe`) for converting to a pandas DataFrame, `to_polars` for converting to a Polars DataFrame, `to_numpy` for converting to a numpy array, and `to_dict` for converting to a dictionary.
The `to_chart` method allows for creating or updating a chart based on the fetched data, and the show method is used to display the chart.
The class also includes a `__repr__` method for a human-readable representation of the object, and a `model_parametrized_name method` for returning the model name with its parameters.
### The `Router` class
The `Router` class in the OpenBB platform is responsible for managing and routing API requests. It uses the `APIRouter` from the FastAPI library to handle routing.
The class includes a command method that allows for the registration of callable functions as API endpoints. This method takes care of setting up the API route, including defining the HTTP methods, response models, operation IDs, and other necessary parameters for the API endpoint.
The `include_router` method allows for the inclusion of another router, effectively merging the routes from the included router into the current one.
The `Router` class also interacts with the `SignatureInspector` class to validate and complete function signatures, ensuring that the functions registered as API endpoints have the correct parameters and return types.
The `api_router` property provides access to the underlying APIRouter instance, allowing for direct interaction with the FastAPI routing system if needed.
:::info
The `Router` class exposes a `command` decorator that allows for the registration of callable functions as API endpoints. This method takes care of setting up the API route, including defining the HTTP methods, response models, operation IDs, and other necessary parameters for the API endpoint.
This decorator enforces that the decorated function (of type `Callable`) returns an `OBBject` instance. I.e., the signature of a decorated function should translate to `Callable[P, OBBject]` (a callable object (like a function) that takes arguments of type `P` and returns an object of type `OBBject`).
:::
## Import statements
```python
@@ -40,6 +147,9 @@ from openbb_core.app.router import Router
## The TET pattern
The TET pattern is a pattern that we use to build the `Fetcher` classes. It stands for **Transform, Extract, Transform**.
![Diagram](https://github.com/OpenBB-finance/OpenBBTerminal/assets/48914296/ae9908be-00c0-40af-8acb-afeeb9629f2b)
As the OpenBB Platform has its own standardization framework and the data fetcher are a very important part of it, we need to ensure that the data is transformed and extracted in a consistent way, to help us do that, we came up with the **TET** pattern, which helps us build and ship faster as we have a clear structure on how to build the `Fetcher` classes.
1. **Transform** query
@@ -48,7 +158,7 @@ As the OpenBB Platform has its own standardization framework and the data fetche
transform_query(params: Dict[str, Any])
```
Transforms the query parameters. Given a `params` dictionary this method should return the transformed query parameters as a [`QueryParams`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/provider/abstract/query_params.py) child so that we can leverage the pydantic model schemas and validation into the next step. This might also be the place do perform some transformations on any given parameter, i.e., if you want to transform an empty date into a `datetime.now().date()`.
Transforms the query parameters. Given a `params` dictionary this method should return the transformed query parameters as a [`QueryParams`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/openbb_core/provider/abstract/query_params.py) child so that we can leverage the pydantic model schemas and validation into the next step. This might also be the place do perform some transformations on any given parameter, i.e., if you want to transform an empty date into a `datetime.now().date()`.
2. **Extract** data
@@ -64,26 +174,31 @@ As the OpenBB Platform has its own standardization framework and the data fetche
transform_data(query: ExampleQueryParams, data: Dict, **kwargs: Any) -> List[ExampleHistoricalData]
```
Transforms the raw data into the defined data model. Given the transformed query parameters (might be useful for some filtering), the raw data and any other extra arguments, this method should return the transformed data as a list of [`Data`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/provider/abstract/data.py) children.
Transforms the raw data into the defined data model. Given the transformed query parameters (might be useful for some filtering), the raw data and any other extra arguments, this method should return the transformed data as a list of [`Data`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/openbb_core/provider/abstract/data.py) children.
## Data processing commands
The data processing commands are commands that are used to process the data that may or may not come from the OpenBB Platform.
In order to create a data processing framework general enough to be used by any extension, we've created a special abstract class called `Data`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/provider/abstract/data.py) which **all** standardized (and consequently its child classes) will inherit from.
Why is this important?
So that we can ensure that all `OBBject.results` will share a common ground on which we can apply out-of-the-box data processing commands, such as the `ta`, `qa` or the `econometrics` menus.
In order to create a data processing framework general enough to be used by any extension, we've created a special abstract class called [`Data`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/openbb_core/provider/abstract/data.py) which **all** standardized (and consequently its child classes) will inherit from.
**Why is this important?**
We ensure that all `OBBject.results` will share a common ground on which we can apply out-of-the-box data processing commands, such as the `ta`, `qa`, or the `econometrics` menus.
**But what's really the `Data` class?**
But what's really the `Data` class?
It's a pydantic model that inherits from the `BaseModel` and can contain any given number of extra fields. In practice, it looks as follows:
```python
from openbb import obb
>>> res = obb.equity.price.historical("AAPL")
>>> res.results[0]
res = obb.equity.price.historical("AAPL")
res.results[0]
```
```python
AVEquityHistoricalData(date=2023-11-03 00:00:00, open=174.24, high=176.82, low=173.35, close=176.65, volume=79829246.0, vwap=None, adj_close=None, dividend_amount=None, split_coefficient=None)
```
> The `AVEquityHistoricalData` class, is a child class of the `Data` class.
@@ -91,6 +206,7 @@ AVEquityHistoricalData(date=2023-11-03 00:00:00, open=174.24, high=176.82, low=1
Note how we've indexed to get only the first element of the `results` list (which represents a single row, if we want to think about it as a tabular output). This simply means that we are getting a `List` of `AVEquityHistoricalData` from the `obb.equity.price.historical` command. Or, we can also say that that's equivalent to `List[Data]`!
This is very powerful, as we can now apply any data processing command to the `results` list, without worrying about the underlying data structure.
That's why, on data processing commands (such as the `ta` menu) we will find on its function signature the following:
```python
@@ -116,31 +232,35 @@ Not at all! Consider the following example:
```python
>>> from openbb_core.provider.abstract.data import Data
>>> my_data_item_1 = {"open": 1, "high": 2, "low": 3, "close": 4, "volume": 5, "date": "2020-01-01"}
>>> my_data_item_1_as_data = Data.model_validate(my_data_item_1)
>>> my_data_item_1_as_data
Data(open=1, high=2, low=3, close=4, volume=5, date=2020-01-01)
from openbb_core.provider.abstract.data import Data
my_data_item_1 = {"open": 1, "high": 2, "low": 3, "close": 4, "volume": 5, "date": "2020-01-01"}
my_data_item_1_as_data = Data.model_validate(my_data_item_1)
my_data_item_1_as_data
```
```python
Data(open=1, high=2, low=3, close=4, volume=5, date="2020-01-01")
```
This means that the `Data` class is cleaver enough to understand that you are passing a dictionary and it will try to validate it for you.
In other words, if you're using data that doesn't come from the OpenBBPlatform, you only need to ensure it's parsable by the `Data` class and you'll be able to use the data processing commands.
In other words, if you're using data that doesn't come from the OpenBB Platform, you only need to ensure it's parsable by the `Data` class and you'll be able to use the data processing commands.
In other words, imagine you have a dataframe that you want to use with the `ta` menu. You can do the following:
```python
>>> res = obb.equity.price.historical("AAPL")
>>> my_df = res.to_dataframe() # yes, you can convert your OBBject.results into a dataframe out-of-the-box!
>>> my_records = df.to_dict(orient="records")
res = obb.equity.price.historical("AAPL")
my_df = res.to_dataframe() # yes, you can convert your OBBject.results into a dataframe out-of-the-box!
my_records = df.to_dict(orient="records")
>>> obb.ta.ema(data=my_record)
obb.ta.ema(data=my_record)
```
```console
OBBject
results: [{'close': 77.62, 'close_EMA_50': None}, {'close': 80.25, 'close_EMA_50': ... # this is a `List[Data]` yet again
results: [{'close': 77.62, 'close_EMA_50': None}, {'close': 80.25, 'close_EMA_50': ...}] # this is a `List[Data]` yet again
```
> Note that that for this example we've used the `OBBject.to_dataframe()` method to have an example dataframe, but it could be any other dataframe that you have.
@@ -148,10 +268,10 @@ results: [{'close': 77.62, 'close_EMA_50': None}, {'close': 80.25, 'close_EMA_50
## Python Interface
When using the OpenBB Platform on a Python Interface, docstrings and type hints are your best friends as it provides plenty of context on how to use the commands.
Looking at an example on the `ta` menu:
```python
def ema(
self,
data: Union[List[Data], pandas.DataFrame],
@@ -161,9 +281,6 @@ def ema(
offset: int = 0,
chart: bool = False,
) -> OBBject[List[Data]]:
...
```
We can easily deduct that the `ema` command accept data in the formats of `List[Data]` or `pandas.DataFrame`.
@@ -175,7 +292,6 @@ We can easily deduct that the `ema` command accept data in the formats of `List[
When using the OpenBB Platform on a API Interface, the types are a bit more limited than on the Python one, as, for example, we can't use `pandas.DataFrame` as a type. However the same principles apply for what `Data` means, i.e., any given data processing command, which are characterized as POST endpoints on the API, will accept data as a list of records on the **request body**, i.e.:
```json
[
{
"open": 80,
@@ -184,7 +300,26 @@ When using the OpenBB Platform on a API Interface, the types are a bit more limi
"close": 77.62,
"volume": 2487300
}
...
]
```
## Core Dependencies
The OpenBB Platform core relies on a set of carefully selected Python libraries to provide its functionality. These dependencies include:
> Note that, in this context by core we mean the `openbb-core` package.
- FastAPI for building the API.
- Uvicorn as the ASGI server.
- Pandas for data manipulation and analysis.
- Pydantic for data validation and serialization using Python type annotations.
- Requests for making HTTP requests.
- Websockets for handling WebSocket connections.
These dependencies are specified in the `pyproject.toml` files.
### Importance of a Lean Core
Keeping the OpenBB Platform core as lean as possible is crucial for maintaining the platform's performance, ease of use, and flexibility. A lean core means faster installation times, less memory usage, and overall better performance. It also reduces the risk of conflicts between dependencies and makes the platform easier to maintain and update.
Moreover, a lean core allows for greater flexibility. Users of the platform can add additional functionality through extensions without being burdened by unnecessary core dependencies. This makes the OpenBB Platform adaptable to a wide range of use cases and requirements.

91
website/content/platform/development/developer-guidelines/build_openbb_extensions.md vendored
View File

@@ -1,6 +1,6 @@
---
title: Building Extensions for OpenBB Platform
sidebar_position: 2
sidebar_position: 4
description: This guide provides a comprehensive walkthrough on how to create custom extensions for the OpenBB Platform. It covers the process from generating the extension structure to sharing it with the community.
keywords:
- OpenBB Platform
@@ -14,7 +14,19 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Build OpenBB Extensions - Developer Guidelines - Development | OpenBB Platform Docs" />
We have a **Cookiecutter** template that will help you get started. It serves as a jumpstart for your extension development, so you can focus on the data and not on the boilerplate.
In order to speed up the process of building an extension, we have provided a **Cookiecutter** template. It serves as a jumpstart for your extension development, so you can focus on the data and not on the boilerplate.
:::info
Take into consideration that building an extension requires a good understanding of the OpenBB Platform and that it is limited to a small set of use cases.
Before starting, please read the [Integrating Data Sources and Points](/platform/development/developer-guidelines/add_data_point) guide to make sure you really need a new extension.
Extension use cases might include:
- Adding a new data provider
- Adding a new toolkit
- Adding a new charting library
- Adding a new asset class
:::
Please refer to the [Cookiecutter template](https://github.com/OpenBB-finance/openbb-cookiecutter) and follow the instructions there.
@@ -35,3 +47,78 @@ The high level steps are:
2. **Use Loose Versioning**: If possible, specify a range to maintain compatibility. E.g., `>=1.4,<1.5`.
3. **Testing**: Test your extension with the Platform's core to avoid conflicts. Both unit and integration tests are recommended.
4. **Document Dependencies**: Use `pyproject.toml` and `poetry.lock` for clear, up-to-date records.
## Walkthrough
If you do not wish to use the cookiecutter template, this section will walk through the steps of creating a new provider extension.
### Generate the extension structure
We first create a new directory for our provider. This should be located under the `openbb_platform/providers` directory. If I am adding `cooldatasource`, I would create the following directory structure:
```md
cooldatasource/
├── openbb_cooldatasource/
│ ├── models/
│ │ └── cooldatamodel.py
│ ├── utils/
│ │ └── helper_functions.py
│ └── __init__.py
├── pyproject.toml
└── README.md
```
In this structure, the `cooldatamodel.py` and `helper_functions.py` are the folders handling the logic for obtaining data, as described in the next sections.
The `__init__.py` defines the provider, using the following code:
```python
from openbb_core.provider.abstract.provider import Provider
cooldatasource_provider = Provider(
name="cooldatasource",
website="",
description="",
credentials=["api_key"],
fetcher_dict={
"MyModel": MyFetcher,
},
)
```
The pyproject.toml defines the package itself
```[tool.poetry]
name = "openbb-cooldatasource"
version = "latest version"
description = "Cool OpenBB Extension"
authors = ["You"]
readme = "README.md"
packages = [{ include = "openbb_cooldatasource" }]
[tool.poetry.dependencies]
python = "^3.9"
openbb-core = "latest openbb core version"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
[tool.poetry.plugins."openbb_provider_extension"]
cooldatasource = "openbb_cooldatasource:cooldatasource_provider"
```
Where the last line (poetry.plugins) maps to the provider defined in the `__init__.py` file.
### Install your dependencies and package
The next step is to install the dependencies. We use poetry for dependency management, so from our new directory, we generate the lock file using:
```console
poetry lock
```
In order to use the extension we will install it using pip. For development mode, we run the following from our directory
```console
pip install -e .
```
This will install the extension in editable mode, so any changes we make will be reflected in the installed package.
### Use your provider extension
Once this is installed, you can use it directly in the openbb package. If you wish to add this to the repo, please follow the instructions in the contributing section, which enforces QA guidelines for adding tests and ensuring the package is implemented properly.

48
website/content/platform/development/developer-guidelines/devtools.md vendored Normal file
View File

@@ -0,0 +1,48 @@
---
title: DevTools
sidebar_position: 2
description: This page provides information about the `openbb-devtools` package, which includes a range of dependencies essential for robust and efficient software development on the OpenBB Platform.
keywords:
- DevTools
- Python
- Development
- OpenBB Platform
- Dependencies
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="DevTools - Developer Guidelines - Development | OpenBB Platform Docs" />
Please refer to the following PyPI distributed package: https://pypi.org/project/openbb-devtools/
This Python package, `openbb-devtools`, is designed for OpenBB Platform Developers and contains a range of dependencies essential for robust and efficient software development.
These dependencies cater to various aspects like code formatting, security analysis, type checking, testing, and kernel management.
The inclusion of these packages ensures that the development process is streamlined, the code quality is maintained, and the software is secure and reliable.
Included dependencies:
- `ruff`: A fast Python linter focused on performance and simplicity.
- `pylint`: A tool that checks for errors in Python code, enforces a coding standard, and looks for code smells.
- `mypy`: A static type checker for Python, helping catch type errors during development.
- `pydocstyle`: A linter for Python docstrings to ensure they meet certain style requirements.
- `black`: An uncompromising Python code formatter, ensuring consistent code style.
- `bandit`: A tool designed to find common security issues in Python code.
- `pre-commit`: Manages and maintains pre-commit hooks that run checks before each commit, ensuring code quality.
- `nox`: A generic virtualenv management and test command line tool for running tests in isolated environments.
- `pytest`: A mature full-featured Python testing tool that helps in writing better programs.
- `pytest-cov`: A plugin for pytest that measures code coverage during testing.
- `ipykernel`: A package that provides the IPython kernel for Jupyter.
- `types-python-dateutil`: Type stubs for python-dateutil, aiding in static type checking.
- `types-toml`: Type stubs for TOML, useful for static type checking in TOML parsing.
- `poetry`: A tool for dependency management and packaging in Python.
Each dependency plays a critical role in ensuring the code is clean, efficient, and functional, ultimately leading to the development of high-quality software.
While developing code for the OpenBB Platform, one should always install the DevTools packages so that the above development tooling is available out-of-the-box.
:::info
When setting up the environment using the `openbb_platform/dev_install.py` script, the DevTools will also be installed.
:::

36
website/content/platform/development/developer-guidelines/expecations_for_developers.md vendored
View File

@@ -1,36 +0,0 @@
---
title: Expectations for Developers
sidebar_position: 1
description: This guide outlines the expectations for developers contributing to the OpenBB Platform. It covers key areas such as use cases, documentation, code quality, testing, performance, and collaboration.
keywords:
- OpenBB Platform
- Developer guidelines
- Code quality
- Testing
- Collaboration
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Expectations for Developers - Developer Guidelines - Development | OpenBB Platform Docs" />
1. Use Cases:
- Ensure that your extensions or features align with the broader goals of the application.
- Understand that the OpenBB Platform is designed to be foundational; build in a way that complements and doesn't conflict with its core functionalities.
2. Documentation:
- Provide clear and comprehensive documentation for any new feature or extension you develop.
3. Code Quality:
- Adhere to the coding standards and conventions of the OpenBB Platform.
- Ensure your code is maintainable, well-organized, and commented where necessary.
4. Testing:
- Thoroughly test any new feature or extension to ensure it works as expected.
5. Performance:
- Ensure that your extensions or features do not adversely affect the performance of the OpenBB Platform.
- Optimize for scalability, especially if you anticipate high demand for your feature.
6. Collaboration:
- Engage with the OpenBB community to gather feedback on your developments.

135
website/content/platform/development/developer-guidelines/obbject.md vendored Normal file
View File

@@ -0,0 +1,135 @@
---
title: OpenBB OBBject
sidebar_position: 7
description: This page provides information about the OBBject class in the OpenBB Platform. This class provides the interface to interact with commands
keywords:
- OBBject
- Python
- Development
- OpenBB Platform
- Results
- Commands
- Pandas
- DataFrame
- Polars
- Numpy
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="OBBject - Developer Guidelines - Development | OpenBB Platform Docs" />
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.
## 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:
```python
from openbb import obb
obbject = obb.equity.price.historical("AAPL", provider="fmp")
display(obbject)
```
```console
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
```python
obbject.results[0]
```
```console
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()`.
```python
type(obb.equity.price.historical("AAPL", provider="fmp").to_dataframe())
```
```console
<class 'pandas.core.frame.DataFrame'>
```
### to_dict(orient)
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:
```python
to_dict = obb.equity.price.historical("AAPL", provider="fmp").to_dict()["open"][:10]
```
```console
[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:
```python
obb.equity.price.historical("AAPL", provider="fmp").to_dict("records")[0]
```
```python
{'open': 144.29,
'high': 144.81,
'low': 140.35,
'close': 141.17,
'volume': 83763800,
'vwap': 142.11,
'label': 'November 29, 22',
'adj_close': 140.39,
'unadjusted_volume': 83763800.0,
'change': -3.12,
'change_percent': -2.16,
'change_over_time': -0.0216}
```
### Others
In addition to these two highly used methods, we have also provided the following methods:
#### 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_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.
---
More information can be found on the [OpenBB Core Readme](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/README.md)

86
website/content/platform/development/developer-guidelines/obbject_extensions.md vendored Normal file
View File

@@ -0,0 +1,86 @@
---
title: OBBject Extensions
sidebar_position: 8
description: This page provides information about how to write extensions for the OpenBB OBBject class.
keywords:
- OBBject
- Python
- Development
- OpenBB Platform
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="OBBject Extensions - Developer Guidelines - Development | OpenBB Platform Docs" />
As mentioned, OpenBB provides some basic methods for interacting with common data structures that will be seen in the results attribute.
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.
The OpenBB Platform provides a way to do this by extending the OBBject class.
The architecture for extensions was designed similar to how extensions and accessors are done in pandas, and relies on plugins through the poetry dependency management package.
This page will go through the steps of developing a simple, custom extension for the OBBject class.
### Folder structure
```shell
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`.
```python
from openbb_core.app.model.extension import Extension
ext = Extension(name="example", credentials=["some_api_key"])
```
The credentials are required if the extension uses a key for data or a service, or it can alternatively be connection information for a database, or any other information that needs to be passed to the extension.
Now we define the extension 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.
Here, we just add a method to say hi:
```python
@ext.obbject_accessor
class Example:
def __init__(self, obbject):
self._obbject = obbject
def hello(self):
api_key = self._obbject._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:
```toml
[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:
```shell
>>> 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.

144
website/content/platform/development/developer-guidelines/validators.md vendored Normal file
View File

@@ -0,0 +1,144 @@
---
title: Validators
sidebar_position: 4
description: This guide provides detailed instructions on how and where validators should be used.
keywords:
- OpenBB Platform
- Data point addition
- Provider creation
- Query parameters
- Data output models
- Fetcher class
- validator
- field
- param
- Fast API
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Validators - Developer Guidelines - Development | OpenBB Platform Docs" />
Both QueryParams and Data models can benefit from the tactical use of Pydantic validators. This page will outline some of the key scenarios where they are deployed. Overall, they assist with enforcing Fast API compliance for both inputs and outputs.
## Why Use Validators?
Some situations where they are used include:
- A query parameter accepts a List.
- A query parameter is a date.
- A query parameter requires a dynamic default state.
- A data field is a date.
- A data field is a number but the source values contain string elements.
## Examples
### String or List of Strings
To enforce compliance with Fast API, a list needs to be converted to a comma-separated string. This type of validator works on the **input** of the model, and it ensures that both the Python interface and the Rest API are able to accept a list of symbols, or just one.
```python
from typing import List, Optional, Set, Union
from datetime import (
date as dateType,
datetime,
timedelta,
)
from dateutil import parser
from openbb_core.provider.abstract.query_params import QueryParams
from openbb_core.provider.utils.descriptions import QUERY_DESCRIPTIONS
from pydantic import Field, field_validator, model_validator
class EquityHistoricalQueryParams(QueryParams):
"""Equity Historical Price Query."""
symbol: str = Field(description=QUERY_DESCRIPTIONS.get("symbol", ""))
interval: Optional[str] = Field(
default="1d",
description=QUERY_DESCRIPTIONS.get("interval", ""),
)
start_date: Optional[dateType] = Field(
default=None,
description=QUERY_DESCRIPTIONS.get("start_date", ""),
)
end_date: Optional[dateType] = Field(
default=None,
description=QUERY_DESCRIPTIONS.get("end_date", ""),
)
@field_validator("symbol", mode="before", check_fields=False)
@classmethod
def upper_symbol(cls, v: Union[str, List[str], Set[str]]):
"""Convert symbol to uppercase."""
if isinstance(v, str):
return v.upper()
return ",".join([symbol.upper() for symbol in list(v)])
symbols = ["AAPL", "MSFT", "GOOG"]
params = EquityHistoricalQueryParams(symbol=symbols)
params.model_dump()
```
```python
{'symbol': 'AAPL,MSFT,GOOG',
'interval': '1d',
'start_date': None,
'end_date': None}
```
The list of symbols can also be entered as a comma-separated string:
```python
symbols = "AAPL,MSFT,GOOG"
params = EquityHistoricalQueryParams(symbol=symbols)
params.model_dump()
```
```python
{'symbol': 'AAPL,MSFT,GOOG',
'interval': '1d',
'start_date': None,
'end_date': None}
```
### Dynamic Default Date
It might be desirable to have a default date parameter that is not static. To allow this, we must set the default as `None`, and use the `model_validator`. The block below is added to the class defined above.
```python
@model_validator(mode="before")
@classmethod
def validate_dates(cls, values) -> dict:
"""Validate the query parameters."""
if values.get("start_date") is None:
values["start_date"] = (datetime.now() - timedelta(days=90)).strftime(
"%Y-%m-%d"
)
if values.get("end_date") is None:
values["end_date"] = datetime.now().strftime("%Y-%m-%d")
return values
```
```python
params = EquityHistoricalQueryParams(symbol=symbols)
params.model_dump()
```
```python
{'symbol': 'AAPL,MSFT,GOOG',
'interval': '1d',
'start_date': datetime.date(2023, 8, 30),
'end_date': datetime.date(2023, 11, 28)}
```
### Formatting Dates
Providers will format dates in a number of ways. OpenBB uses YYYY-MM-DD as the standard convention. Validators are setup to parse the date from the source format to the desired one. The validator below is used in some data models to convert date values to a datetime object.
```python
@field_validator("date", mode="before", check_fields=False)
def date_validate(cls, v): # pylint: disable=E0213
"""Return formatted datetime."""
return parser.isoparse(str(v))
```

38
website/content/platform/development/index.md vendored
View File

@@ -28,20 +28,20 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
This section provides guidelines for contributing to the OpenBB Platform.
Throughout it, we will be differentiating between two types of contributors: Developers and Contributors.
1. **Developers**: Those who are building new features or extensions for the OpenBB Platform or leveraging the OpenBB Platform.
2. **Contributors**: Those who contribute to the existing codebase, by opening a Pull Request, thus giving back to the community.
1. **Developers**: Those who are building new features or new extensions for the OpenBB Platform or leveraging the OpenBB Platform for custom applications.
2. **Contributors**: Those who contribute to the existing codebase, by opening a Pull Request, thus giving back to the community. This can include bug fixes, enhancements, documentation, and more.
**Why is this distinction important?**
The OpenBB Platform is designed as a foundation for further development. We anticipate a wide range of creative use cases for it. Some use cases may be highly specific or detail-oriented, solving particular problems that may not necessarily fit within the OpenBB Platform Github repository. This is entirely acceptable and even encouraged. This document provides a comprehensive guide on how to build your own extensions, add new data points, and more.
The OpenBB Platform has been designed to be the foundation for further development of applications regarding investment research. We anticipate a wide range of creative use cases for it. Some use cases may be highly specific or detail-oriented, solving particular problems that may not necessarily fit within the OpenBB Platform Github repository. This is entirely acceptable and even encouraged. This document provides a comprehensive guide on how to build your own extensions, add new data points, and more.
The **Developer** role, as defined in this document, can be thought of as the foundational role. Developers are those who use the OpenBB Platform as is or build upon it.
Conversely, the **Contributor** role refers to those who enhance the OpenBB Platform codebase (either by directly adding to the OpenBB Platform or by extending the [extension repository](/platform/extensions)). Contributors are willing to go the extra mile, spending additional time on quality assurance, testing, or collaborating with the OpenBB development team to ensure adherence to standards, thereby giving back to the community.
The **Contributor** role refers to those who enhance the OpenBB Platform codebase (either by directly adding to the OpenBB Platform or by creating an [extension](/platform/extensions)). Contributors are willing to go the extra mile, spending additional time on quality assurance, testing, or collaborating with the OpenBB development team to ensure adherence to standards, thereby giving back to the community.
## Quick look into the OpenBB Platform
The OpenBB Platform is built by the Open-Source community and is characterized by its core and extensions. The core handles data integration and standardization, while the extensions enable customization and advanced functionalities. The OpenBB Platform is designed to be used both from a Python interface and a REST API.
The OpenBB Platform was built by the Open-Source community and is characterized by its core and extensions. The core handles data integration and standardization, while extensions enable customization and advanced functionalities. The OpenBB Platform is designed to be used from either a REST API or from a Python package.
The REST API is built on top of FastAPI and can be started by running the following command from the root:
@@ -49,15 +49,13 @@ The REST API is built on top of FastAPI and can be started by running the follow
uvicorn openbb_platform.platform.core.openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload
```
The Python interfaces we provide to users is the `openbb` python package.
The Python interface we provide to users is the `openbb` python package.
The code you will find in this package is generated from a script and it is just a wrapper around the `openbb-core` and any installed extensions.
The code you will find in this package is generated from a script, which is a wrapper around the `openbb-core` with any additional extensions that are installed.
When the user runs `import openbb`, `from openbb import obb` or other variants, the script that generates the packaged code is triggered. It detects if there are new extensions installed in the environment and rebuilds the packaged code accordingly. If new extensions are not found, it just uses the current packaged version.
When the user runs `import openbb`, `from openbb import obb` or other variants, the script that generates the packaged code is triggered. It detects if there are new extensions installed in the environment and rebuilds the packaged code accordingly. If new extensions are not found, it uses the current packaged version.
When you are developing chances are you want to manually trigger the package rebuild.
You can do that with:
In the case you wish to manually trigger a rebuild of the package (see more in the contributing information), the following command can be run:
```python
python -c "import openbb; openbb.build()"
@@ -69,7 +67,7 @@ The Python interface can be imported with:
from openbb import obb
```
This document will take you through two types of contributions:
The remainder of this document will take you through two types of contributions:
1. Building a custom extension
2. Contributing directly to the OpenBB Platform
@@ -77,8 +75,8 @@ This document will take you through two types of contributions:
Before moving forward, please take a look at the high-level view of the OpenBB Platform architecture. We will go over each bit in this document.
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/OpenBB-finance/OpenBBTerminal/assets/74266147/c9a5a92a-28b6-4257-aefc-deaebe635c6a"/>
<img alt="OpenBB Platform High-Level Architecture" src="https://github.com/OpenBB-finance/OpenBBTerminal/assets/74266147/c9a5a92a-28b6-4257-aefc-deaebe635c6a"/>
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/OpenBB-finance/OpenBBTerminal/assets/48914296/6125cbf2-ff5b-4cd8-b5b8-452cd8d84418"/>
<img alt="OpenBB Platform High-Level Architecture" src="https://github.com/OpenBB-finance/OpenBBTerminal/assets/48914296/6125cbf2-ff5b-4cd8-b5b8-452cd8d84418"/>
</picture>
### What is the Standardization Framework?
@@ -97,7 +95,7 @@ Usage of these models will unlock a set of perks that are only available to stan
The standard models are defined under the `/OpenBBTerminal/openbb_platform/platform/core/provider/standard_models/` directory.
They define the [`QueryParams`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/provider/abstract/query_params.py) and [`Data`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/core/provider/abstract/data.py) models, which are used to query and output data. They are pydantic and you can leverage all the pydantic features such as validators.
Each standard model defines a [`QueryParams`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/platform/provider/openbb_provider/abstract/query_params.py) and [`Data`](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/openbb_platform/platform/provider/openbb_provider/abstract/data.py) model, which are used to query and output data. Under the hood, these are just pydantic models, meaning you can leverage all the built-in pydantic features such as validators.
#### Standardization Caveats
@@ -109,6 +107,8 @@ The standardization framework is a very powerful tool, but it has some caveats t
#### Standard QueryParams Example
An example `QueryParams` is shown here, coming from the EquityHistorical standard model:
```python
class EquityHistoricalQueryParams(QueryParams):
"""Stock end of day Query."""
@@ -121,12 +121,14 @@ class EquityHistoricalQueryParams(QueryParams):
)
```
The `QueryParams` is an abstract class that just tells us that we are dealing with query parameters
The `QueryParams` is an abstract class that defines what parameters will be needed to make a query to obtain data. Note that not all possible parameters are defined here, and can be further refined in the provider-specific model.
The OpenBB Platform dynamically knows where the standard models begin in the inheritance tree, so you don't need to worry about it.
#### Standard Data Example
The `Data` model for the EquityHistorical standard model is shown here:
```python
class EquityHistoricalData(Data):
"""Stock end of day price Data."""
@@ -148,12 +150,12 @@ An extension adds functionality to the OpenBB Platform. It can be a new data sou
#### Types of extensions
We primarily have 3 types of extensions:
Extensions currently fall into 3 categories:
1. OpenBB Extensions - built and maintained by the OpenBB team (e.g. `openbb-equity`)
2. Community Extensions - built by anyone and primarily maintained by OpenBB (e.g. `openbb-yfinance`)
3. Independent Extensions - built and maintained independently by anyone
If your extension is of high quality and you think that it would be a good community extension, you can open a PR to the OpenBB Platform repository and we'll review it.
If you have built an extension and you think that it would be a good community extension, you can open a PR to the OpenBB Platform repository and we will review it.
We encourage independent extensions to be shared with the community by publishing them to PyPI.

10
website/content/platform/extensions/data_extensions.md vendored
View File

@@ -25,9 +25,9 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Data - Extensions | OpenBB Platform Docs" />
Data extensions will expand the breadth and coverage of the data available in the OpenBB Platform. Each source (provider) is its own independent extension, even if there is only one endpoint accessible. This allows every data source to be inserted or removed, at any time, without distrubing the operation of the Core components.
Data extensions will expand the breadth and coverage of the data available in the OpenBB Platform. Each source (provider) is its own independent extension, even if there is only one endpoint accessible. This allows every data source to be inserted or removed, at any time, without disturbing the operation of the Core components.
Functions will appear in the Python Interface and Fast API only if a supported provider, for that specific endpoint, is installed. Additional Python libraries will be installed, where required, by the extension.
Functions will appear in the Python Interface and Fast API only if a supported provider, for that specific endpoint, is installed. Additional Python libraries will be installed, where required, by the extension.
## Provider Coverage
@@ -40,13 +40,13 @@ obb.coverage.providers
## Installation
All data extensions are installed with similar syntax. Published data extensions will have names beginning with `openbb`. For example, yFinance.
All data extensions are installed with similar syntax. Published data extensions will have names beginning with `openbb`. For example, yFinance.
```console
pip install openbb-yfinance
```
Additions and removals update the router automatically to reflect the changes when the Python interpreter is refreshed. Below is a list of data provider extensions.
Additions and removals update the router automatically to reflect the changes when the Python interpreter is refreshed. Below is a list of data provider extensions.
Uninstall any extension with `pip uninstall`.
@@ -80,6 +80,6 @@ pip uninstall openbb-yfinance
| openbb-wsj | [Wall Street Journal](https://www.wsj.com/) data connector. | pip install openbb-wsj | Community | None |
| openbb-yfinance | [Yahoo Finance](https://finance.yahoo.com/) data connector. | pip install openbb-yfinance | Community | None |
Have you published a data provider extension and want it featured on this list? Tell us about it! Open a pull request on [GitHub](https://github.com/OpenBB-finance/OpenBBTerminal/) to submit an extension for inclusion. Code contributions, for new and existing, data providers are always welcome.
Have you published a data provider extension and want it featured on this list? Tell us about it! Open a pull request on [GitHub](https://github.com/OpenBB-finance/OpenBBTerminal/) to submit an extension for inclusion. Code contributions, for new and existing, data providers are always welcome.
Search [PyPI](https://pypi.org/search/?q=openbb-) to find more extensions.

8
website/content/platform/extensions/index.md vendored
View File

@@ -22,17 +22,17 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Overview - Extensions | OpenBB Platform Docs" />
When the core OpenBB Platform package is installed, familiar components might be missing. This is to keep the core components as light as possible. The extension framework allows individual pieces to be installed and removed seamlessly within the environment, using only the desired data and toolkit extensions.
When the core OpenBB Platform package is installed, familiar components might be missing. This is to keep the core components as light as possible. The extension framework allows individual pieces to be installed and removed seamlessly within the environment, using only the desired data and toolkit extensions.
There are two primary types of extensions for the OpenBB Platform:
- [Data](/platform/extensions/data_extensions)
- [Toolkits](/platform/extensions/toolkit_extensions)
The OpenBB Core installation does not include any toolkit extensions. Install the OpenBB Platform with all data and toolkit extensions from PyPI with:
The OpenBB Core installation does not include any toolkit extensions. Install the OpenBB Platform with all data and toolkit extensions from PyPI with:
```python
pip install openbb[all] --pre
pip install openbb[all]
```
When installing from source, navigate into the `openbb_platform` folder from the root of the project and enter:
@@ -41,4 +41,4 @@ When installing from source, navigate into the `openbb_platform` folder from the
python dev_install.py -e
```
This installs all extensions in editable mode, and the Python interface is compiled in, `/openbb_platform/openbb/package`, instead of the environment's `site-packages` folder. The tables in the next pages lists extensions as either, Core or Community. The Core extensions are installed by default.
This installs all extensions in editable mode, and the Python interface is compiled in, `/openbb_platform/openbb/package`, instead of the environment's `site-packages` folder. The tables in the next pages lists extensions as either, Core or Community. The Core extensions are installed by default.

10
website/content/platform/extensions/toolkit_extensions.md vendored
View File

@@ -26,7 +26,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Toolkits - Extensions | OpenBB Platform Docs" />
OpenBB Toolkit Extensions expand the Platform with functions for manipulating data and preparing it for display. The Core Platform installation does not install any toolkit extensions. The table below is the current list of toolkit extensions.
OpenBB Toolkit Extensions expand the Platform with functions for manipulating data and preparing it for display. The Core Platform installation does not install any toolkit extensions. The table below is the current list of toolkit extensions.
| Extension Name | Description | Installation Command | Core/Community | Router Path |
|:-----------------|:-----------:|:-------------------:|:------------------:|-------------:|
@@ -40,9 +40,9 @@ The sections below outline any specific installation considerations for the exte
## Charting
The OpenBB Charting Extension supplies charting infrastructure and services to the OpenBB Platform. Figure objects are served via REST API or Python Client. It utilizes [PyWry](https://github.com/OpenBB-finance/pywry) for handling the display of interactive charts and tables in a separate window, with a Plotly library. The extension framework allows developers to easily insert other Python charting libraries into the router pipeline.
The OpenBB Charting Extension supplies charting infrastructure and services to the OpenBB Platform. Figure objects are served via REST API or Python Client. It utilizes [PyWry](https://github.com/OpenBB-finance/pywry) for handling the display of interactive charts and tables in a separate window, with a Plotly library. The extension framework allows developers to easily insert other Python charting libraries into the router pipeline.
Functions with charting enabled return figures to a field (`chart`) in the `OBBject` response object. They are displayed with the class method, `show()`. Additional Python libraries are installed with this extension:
Functions with charting enabled return figures to a field (`chart`) in the `OBBject` response object. They are displayed with the class method, `show()`. Additional Python libraries are installed with this extension:
- aiohttp
- nbformat
@@ -112,7 +112,7 @@ for OpenBB. It does not contain any code itself, but rather pulls in the followi
### Installation
The extension is included in the dev_install.py script.
The extension is included in the `dev_install.py` script.
Standalone installation:
@@ -175,7 +175,7 @@ After installation, the Python interface will automatically rebuild on initializ
## Technical
The `openbb-technical` extension is for performing technical analysis on time series data. It install a new router path (`obb.techincal`) and some additional Python libraries:
The `openbb-technical` extension is for performing technical analysis on time series data. It installs a new router path (`obb.techincal`) and some additional Python libraries:
- pandas-ta
- scikit-learn

23
website/content/platform/index.md vendored
View File

@@ -16,11 +16,30 @@ keywords:
<!-- markdownlint-disable MD012 MD031 MD033 -->
OpenBB Platform is created and maintained by the OpenBB team together with the contributions from hundreds of community members. This gives us an unrivaled speed of development and the ability to maintain stable integrations with numerous third-party data providers.
The OpenBB Platform has been created and is currently maintained by the OpenBB team together with the contributions from hundreds of community members. This gives us an unrivaled speed of development and the ability to maintain stable integrations with numerous third-party data providers.
Developing and maintaining a full-blown investment research infrastructure from the ground up takes a lot of time and effort. However, it does not have to be this way. By taking advantage of OpenBB Platform with its out-of-the-box data connectors and library of extensions, you can focus on designing and building your financial reports and applications.
<img width="769" alt="sdk" src="https://github.com/OpenBB-finance/OpenBBTerminal/assets/25267873/f8ddb59a-b3b5-436c-80cb-2b97e246a8d9" />
![Platform Docs pic](https://github.com/OpenBB-finance/OpenBBTerminal/assets/85772166/74520441-5e95-4ba6-9d16-6a2d5c966cf9)
## What is the OpenBB Platform?
Starting with V4, we have completely restructured the previous version of the OpenBB SDK.
Instead of a single monolithic SDK, that comes with dependency nightmares and compatibility issues with things you may not need, we have morphed into the OpenBB Platform, which serves as a collection of building blocks to be used for your own need.
We have broken the Platform into two main components:
- OpenBB Core
- OpenBB Extensions
- OpenBB Providers
- OpenBB Toolkits
The OpenBB Core provides all of the groundwork for building custom applications. It is a lightweight package providing connections with data providers in a standardized way, and the ability to build additional toolkits on top. Additionally, the `openbb-core` library contains the infrastructure for Fast API deployments.
OpenBB Extensions are the pieces that can be added to the core for building on top of. We have grouped them categorically as, Providers and Toolkits.
As the name suggests, Providers are the interface to obtaining any raw data from any data source. The data providers are accessed through asset class extensions, such as `openbb-equity`. OpenBB toolkits, such as `openbb-technical`, provide additional functionalities on top of the raw data access.
When you install the Platform (openbb), we provide a default set of extensions that give access to a wide range of functionalities and data. Additional data and processing tools are available to be installed and used as desired. The reason we are doing this is to avoid an overcomplicated environment with many dependencies that can cause issues. The goal is that OpenBB can be used as a drop-in within any environment for building and extending applications.
---

82
website/content/platform/installation.md vendored
View File

@@ -40,7 +40,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
## General System Requirements
Most systems capable of running Python 3.8-3.11 will be compatible with the OpenBB Platform. A modern processor (five years or less), running an up-to-date operating system, with at least 4GB of RAM, is recommended. Maintaining the system with current patches ensures maximum compatibility. At a minimum, Windows and macOS should be:
Most systems capable of running Python 3.8-3.11 will be compatible with the OpenBB Platform. A modern processor (five years or less), running an up-to-date operating system, with at least 4GB of RAM, is recommended. Maintaining the system with current patches ensures maximum compatibility. At a minimum, Windows and macOS should be:
- Windows 10
- Mac OS Big Sur
@@ -49,7 +49,7 @@ Linux users should run the command line update for the package manager, prior to
## Supported Environments
The OpenBB Platform is installed within a Python virtual environment. It is compatible with versions of Python between 3.8 and 3.11, inclusively. The method for creating the environment will be a matter of user preference, from the command line - [Conda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html), [venv](https://docs.python.org/3/library/venv.html), [Docker](https://hub.docker.com/), etc. - or in a code editor and IDE - [VS Code](https://code.visualstudio.com/docs/languages/python), [PyCharm](https://www.jetbrains.com/pycharm/), [Jupyter](https://jupyter.org/).
The OpenBB Platform is installed within a Python virtual environment. It is compatible with versions of Python between 3.8 and 3.11, inclusively. The method for creating the environment will be a matter of user preference, from the command line - [Conda](https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html), [venv](https://docs.python.org/3/library/venv.html), [Docker](https://hub.docker.com/), etc. - or in a code editor and IDE - [VS Code](https://code.visualstudio.com/docs/languages/python), [PyCharm](https://www.jetbrains.com/pycharm/), [Jupyter](https://jupyter.org/).
[Docker](/platform/installation#docker) builds the environment during the installation process, skip ahead to the specific section [below](/platform/installation#docker).
@@ -63,51 +63,81 @@ With the container created, and activated, begin the installation process.
Before installation, update the package manager so that `pip` is current, then create the environment with the desired version of Python and install the following packages:
:::note
Installing packages directly to the system Python or `base` environment is not recommended. Create a new environment.
:::
```console
pip install poetry toml
```
:::note
Installing packages directly to the system Python or `base` environment is not recommended. Create a new environment first (can be any name, using openbb here for example).
```bash
conda create -n openbb python=3.11
conda activate openbb
```
:::
### PyPI
Install from PyPI with:
```console
pip install openbb --pre
pip install openbb
```
To install all of the extensions and providers:
This will install the core OpenBB Platform, along with officially supported extensions and providers.
To install all extensions and providers (both officially supported and community maintained ones):
```console
pip install openbb[all] --pre
pip install openbb[all]
```
:::note
While still under active development, the `pre` flag is required to install the core OpenBB Platform latest version.
:::
To install a single extension:
```console
pip install openbb[charting] --pre
pip install openbb[charting]
```
```console
pip install openbb[ta] --pre
pip install openbb[ta]
```
Import the package with:
Or import a single provider:
```console
pip install openbb-yfinance
```
From your python interpreter, import the OpenBB Platform:
```console
from openbb import obb
```
:::warning
This import statement is required due to the statefulness of the obb package. There is currently no support for imports such as
```console
from openbb.obb.equity import *
```
:::
When the package is imported, any installed extensions will be discovered, imported and available for use.
:::note
Currently if you wish to have the bare-bones openbb package with no extensions or providers, you can install with:
```console
pip install openbb --no-deps
```
:::
### Docker
OpenBB supplies a `.dockerfile` on [GitHub](https://github.com/OpenBB-finance/OpenBBTerminal).
OpenBB provides a `.dockerfile` on [GitHub](https://github.com/OpenBB-finance/OpenBBTerminal).
Run the following command from the repo root to build the image:
@@ -161,7 +191,7 @@ To install all extensions and providers, run: `python dev_install.py -e`
## Post-Installation
With a fresh installation, and upon installing or uninstalling extensions, the Python interface needs to be built. This is done automatically, but can be manually triggered if required. Start a Python session and then `import openbb`:
With a fresh installation, and upon installing or uninstalling extensions, the Python interface needs to be built. This is done automatically, but can be manually triggered if required. Start a Python session and then `import openbb`:
```console
python
@@ -190,9 +220,23 @@ Start the REST API with:
uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload
```
## Hub Synchronization
Once you have installed the OpenBB Platform with the desired providers and extensions, you can synchronize with the [OpenBB Hub](my.openbb.co). The main benefit of this is that you can use your single login to access your saved credentials and preferences from any instance. To login, you can use the `login` method, either using your email and password:
```python
obb.account.login(email='my_email_here', password='my_password_here')
```
Or using your personal access token:
```python
obb.account.login(pat='my_pat_here')
```
## Documentation
The documentation and packages are kept in the `/website` folder, at the base of the repository. Navigate there to install the dependencies and start the development server.
The documentation and packages are kept in the `/website` folder, at the base of the repository. Navigate there to install the dependencies and start the development server.
#### Node.js

20
website/content/platform/usage/basic_syntax.md vendored
View File

@@ -29,7 +29,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Basic Syntax - Usage | OpenBB Platform Docs" />
The structure of command syntax is standardized across common fields. This ensures that a `date` is always a `date` and the format remains consistent throughout. Standardized parameters include, but are not limited to:
The structure of command syntax is standardized across common fields. This ensures that a `date` is always a `date` and the format remains consistent throughout. Standardized parameters include, but are not limited to:
- [provider](#provider)
- [symbol](#symbol)
@@ -60,6 +60,8 @@ Examples below assume that the Python interface has been imported in the current
from openbb import obb
```
or
```python
uvicorn openbb_core.api.rest_api:app
```
@@ -68,7 +70,7 @@ uvicorn openbb_core.api.rest_api:app
## Provider
The `provider` parameter is the way to select the specific source of the data from the endpoint. If a [preference for the default provider](/platform/usage#user-settings) has not been defined, the default will be the first, alphabetically, installed provider. Provider values are entered in lower-case, with an underscore for multiple words - for example:
The `provider` parameter is the way to select the specific source of the data from the endpoint. If a [preference for the default provider](/platform/usage#user-settings) has not been defined, the default will be the first, alphabetically, installed provider. Provider values are entered in lower-case, with an underscore for multiple words - for example:
```python
historical_prices = obb.equity.price.historical("aapl", provider="alpha_vantage")
@@ -84,7 +86,7 @@ Refer to, [Data Providers](/platform/extensions/data_extensions), for instructio
## Symbol
Symbols are not case-sensitive, and where the function allows, can be entered as a `string`, `List[str]`, or a comma-separated `string`. The exact format of the symbol may vary between providers - for example, share classes, exchange suffixes, and global composities. An example of this difference is shown below:
Symbols are not case-sensitive, and where the function allows, can be entered as a `string`, `List[str]`, or a comma-separated `string`. The exact format of the symbol may vary between providers - for example, share classes, exchange suffixes, and global composites. An example of this difference is shown below:
```python
obb.equity.price.historical("brk.b", provider="polygon")
@@ -94,9 +96,9 @@ obb.equity.price.historical("brk.b", provider="polygon")
obb.equity.price.historical("brk-b", provider="fmp")
```
While some providers handle the different formats on their end, others do not. This is something to consider when no results are returned from one source.
While some providers handle the different formats on their end, others do not. This is something to consider when no results are returned from one source.
With providers supporting market data from multiple jurisdictions, the most common method for requesting data outside of US-listings is to append a suffix to the ticker symbol (e.g., `RELIANCE.NS`). Formats may be unique to a provider, so it is best to review the source's documentation for an overview of their specific conventions. [This page](https://help.yahoo.com/kb/SLN2310.html) on Yahoo describes how they format symbols, which many others follow to some degree.
With providers supporting market data from multiple jurisdictions, the most common method for requesting data outside of US-listings is to append a suffix to the ticker symbol (e.g., `RELIANCE.NS`). Formats may be unique to a provider, so it is best to review the source's documentation for an overview of their specific conventions. [This page](https://help.yahoo.com/kb/SLN2310.html) on Yahoo describes how they format symbols, which many others follow to some degree.
### One Symbol
@@ -154,7 +156,7 @@ response.json()
## Dates
Dates are entered everywhere as a string, formatted as, "YYYY-MM-DD". If the function has only the `date` parameter, the data will be a snapshot instead of a time series.
Dates are entered everywhere as a string, formatted as, "YYYY-MM-DD". If the function has only the `date` parameter, the data will be a snapshot instead of a time series.
```python
historical_prices = obb.equity.price.historical(symbol="qqq", start_date="2023-01-10", end_date="2023-01-31", provider="fmp")
@@ -178,7 +180,7 @@ response.json()
## Limit
Where, optional, `limit` parameters are supplied, they are likely to have sensible default states that return N results starting from the most recent entry or the `start_date`. Enter these values as an integer.
Where, optional, `limit` parameters are supplied, they are likely to have sensible default states that return N results starting from the most recent entry or the `start_date`. Enter these values as an integer.
```python
income = obb.equity.fa.income("AAPL", period="quarter", provider="fmp", limit=4)
@@ -186,7 +188,7 @@ income = obb.equity.fa.income("AAPL", period="quarter", provider="fmp", limit=4)
## **kwargs
All endpoints accept additional keyword arguments, but non-existent parameters will be ignored. Invalid parameters are communicated via the `warnings` field in the command response. Parameters can be stored as a dictionary and fed to the command as `**kwargs`. If a provider, or function, has an undocumented parameter it can still be accessed by supplying the additional kwargs.
All endpoints accept additional keyword arguments, but non-existent parameters will be ignored. Invalid parameters are communicated via the `warnings` field in the command response. Parameters can be stored as a dictionary and fed to the command as `**kwargs`. If a provider, or function, has an undocumented parameter it can still be accessed by supplying the additional kwargs.
```python
kwargs = {"symbol":"msft","start_date":"2023-01-01","provider":"polygon"}
@@ -277,4 +279,4 @@ pd.DataFrame.from_records(ta_results)
All functions, parameters, and responses are detailed under the [Reference pages](/platform/reference). The data models for each provider source are described within the [Data Models](/platform/data_models) pages.
These pages are a quick way to cross-reference differences between providers. The same information is provided in a function's signature and docstring.
These pages are a quick way to cross-reference differences between providers. The same information is provided in a function's signature and docstring.

218
website/content/platform/usage/commitment_of_traders.md vendored Normal file
View File

@@ -0,0 +1,218 @@
---
title: Commitment of Traders
sidebar_position: 7
description: This page provides details on the accessing Commitment of Traders reports with
the OpenBB Platform, published by the CFTC weekly. This guide provides examples for
using the combinations of parameters used to get aspects of the report's data.
keywords:
- futures
- commodities
- index
- indices
- positioning
- dealer
- hedge
- open interest
- Nasdaq DataLink
- CFTC
- commitment of traders
- COT
- Treasury Note
- currency
- currencies
- equity
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Commitment of Traders - Usage | OpenBB Platform Docs" />
Commitment of Traders (COT) reports are published on Fridays, by the [CFTC](https://www.cftc.gov/MarketReports/CommitmentsofTraders/index.htm). CFTC COT reports provide a breakdown of each Tuesday’s open interest for futures and options on futures markets in which 20 or more traders hold positions equal to or above the reporting levels established by the CFTC.
## Regulators Module
The `obb.regulators` module contains data published by industry regulators and agencies. The data will not be specific to any particular asset class, and the information is available to the general public. The COT reports have two end points:
- `obb.regulators.cftc.cot()`
- `obb.regulators.cfc.cot_search()`
While the data is public and available directly from the CFTC website, [Nasdaq Data Link](https://data.nasdaq.com/databases/CFTC) provides access to a parsed database with the complete history, of current and obsolete reports, that the `openbb-nasdaq` data provider connects to.
### COT Search
The `obb.regulators.cftc.cot_search()` end point is a curated list of the 100 most common reports. The list can be searched by fuzzy query - i.e., "commodities" - and they are classified under categories and subcategories. Get the whole list with an empty query.
```python
reports = obb.regulators.cftc.cot_search().to_df()
```
The major US indices - S&P 500, Nasdaq 100, Dow Jones Industrial Average, Russell 1000 & 2000, VIX, Bloomberg Commodity Index, etc. - are categorized as "Index".
```python
reports[reports["category"] == "Index"]
```
### COT Reports
There is a default report, Two-Year Treasury Note Futures, which has the code: `042601`. Where available, like the two-year note, the futures continuation symbol (ZT=F) can be used instead of the code. The name can also be used:
```python
zt = obb.regulators.cftc.cot("Two-Year Treasury Note Futures (CBT)").to_df()
zt.iloc[-1]
```
| | 2023-11-14 |
|:------------------------------|----------------:|
| open_interest | 4274379 |
| noncommercial_long | 427897 |
| noncommercial_short | 1827558 |
| noncommercial_spreads | 121573 |
| commercial_long | 3456965 |
| commercial_short | 2188950 |
| total_long | 4006435 |
| total_short | 4138081 |
| nonreportable_positions_long | 267944 |
| nonreportable_positions_short | 136297 |
:::note
Look up reports not listed under `obb.regulators.cftc.cot_search()` by using the Nasdaq Data Link code for the series. Refer to their documentation for a complete list.
:::
### Parameters
There are parameters that will alter the type of report returned.
:::note
Not every combination of parameters is valid for all reports. An error will be raised when parameters are invalid.
:::
#### `data_type`
The `data_type` changes what is returned, futures or futures and options.
- `F` (futures only)
- `FO` (futures and options)
- `CITS` (Commodity Index Trader Supplemental - only valid for commodities.)
The Supplemental report includes 13 select agricultural commodity contracts for combined futures and options positions. Supplemental reports break down the reportable open interest positions into three trader classifications:
- Non-Commercial
- Commercial
- Index Traders
The example below is the CITS report for corn futures.
```python
zc_cits = obb.regulators.cftc.cot("ZC=F", data_type="CITS").to_df()
zc_cits.iloc[-1]
```
| | 2023-11-14 |
|:---------------------------------------|----------------------:|
| open_interest_all | 1837197 |
| noncommercial_positions_long_all_no_cit | 125917 |
| noncommercial_positions_short_all_no_cit | 322629 |
| noncommercial_positions_spreading_all_no_cit | 564330 |
| commercial_positions_long_all_no_cit | 591691 |
| commercial_positions_short_all_no_cit | 602447 |
| total_reportable_positions_long_all | 1635294 |
| total_reportable_positions_short_all | 1612623 |
| nonreportable_positions_long_all | 201904 |
| nonreportable_positions_short_all | 224575 |
| positions_long_cit | 353355 |
| positions_short_cit | 123216 |
#### `legacy_format`
When `True`, reports are broken down by exchange. These reports have a futures only report and a combined futures and options report. Legacy reports break down the reportable open interest positions into two classifications: non-commercial and commercial traders.
```python
legacy_zt = obb.regulators.cftc.cot("ZT=F", legacy_format=True).to_df()
legacy_zt.iloc[-1]
```
| | 2023-11-14 |
|:-------------------|----------------:|
| open_interest | 4274379 |
| dealer_longs | 138114 |
| dealer_shorts | 367211 |
| dealer_spreads | 37152 |
| asset_manager_longs | 1893280 |
| asset_manager_shorts | 504752 |
| asset_manager_spreads | 297009 |
| leveraged_funds_longs | 968702 |
| leveraged_funds_shorts | 2595004 |
| leveraged_funds_spreads | 133108 |
| other_reportable_longs | 507457 |
| other_reportable_shorts | 172232 |
| other_reportable_spreads | 31614 |
| total_reportable_longs | 4006435 |
| total_reportable_shorts | 4138081 |
| non_reportable_longs | 267944 |
| non_reportable_shorts | 136298 |
#### `report_type`
The `report_type` parameter has four choices:
- `ALL`
- `CHG` (change in positions)
- `OLD`(old crop years)
- `OTR` (other crop years)
For selected commodities where there is a well-defined marketing season or crop year, the COT data are broken down by "old" and "other" crop years. The "Major Markets for Which the COT Data Is Shown by Crop Year" table (shown below) lists those commodities and the first and last futures of the marketing season or crop year. In order not to disclose positions in a single future near its expiration, on the first business day of the month of the last future in an "old" crop year, the data for that last future is combined with the data for the next crop year and is shown as "old" crop futures. An example is CBOT wheat, where the first month of the crop year is July and the last month of the prior crop year is May. On May 3, 2004, positions in the May 2004 futures month were aggregated with positions in the July 2004 through May 2005 futures months and shown as "old" crop futures. Positions in all subsequent wheat futures months were shown as "other."
For the "old" and "other" figures, spreading is calculated for equal long and short positions within a crop year. If a non-commercial trader holds a long position in an "old" crop-year future and an equal short position in an "other" crop-year future, the long position will be classified as "long-only" in the "old" crop year and the short position will be classified as "short-only" in the "other" crop year. In this example, in the "all" category, which considers each trader's positions without regard to crop year, that trader's positions will be classified as "spreading." For this reason, summing the "old" and "other" figures for long-only, for short-only, or for spreading will not necessarily equal the corresponding figure shown for "all" futures. Any differences result from traders that spread from an "old" crop-year future to an "other" crop-year future.
#### Major Markets for Which the COT Data Is Shown by Crop Year
|Market| Commodity | First Future| Last Future|
|:-------|:---------:|:-----:|-----:|
|CBOT| Wheat| July |May|
|CBOT| Corn| December | September|
|CBOT| Oats | July | May|
|CBOT| Soybeans | September |August|
|CBOT| Soybean Oil | October | September|
|CBOT| Soybean Meal | October | September|
|CBOT| Rough Rice| September | July|
|KCBT| Wheat | July| May|
|MGE| Wheat | September |July|
|CME| Lean Hogs | December |October|
|CME| Frozen Pork Bellies | February| August|
|NYBT| Cocoa | December |September|
|NYBT| Coffee C | December | September|
|NYBT| Cotton No.2 | October | July|
|NYBT| Frozen Conc Orange Juice | January | November|
#### `measure`
The `measure` parameter has four choices, with `None` as the default state.
- `CR` (concentration ratios)
- `NT` (number of traders)
- `OI` (percent of open interest)
- `CHG` (change in positions - only valid for when `data_type` is 'CITS')
The report shows the percents of open interest held by the largest four and eight reportable traders, without regard to whether they are classified as commercial or non-commercial. The concentration ratios are shown with trader positions computed on a gross long and gross short basis and on a net long or net short basis. The "Net Position" ratios are computed after offsetting each trader’s equal long and short positions. A reportable trader with relatively large, balanced long and short positions in a single market, therefore, may be among the four and eight largest traders in both the gross long and gross short categories, but will probably not be included among the four and eight largest traders on a net basis.
Based on the information contained in the report of futures-and-options combined in the short format, the Supplemental report shows an additional category of “Index Traders” in selected agricultural markets. These traders are drawn from the noncommercial and commercial categories. The noncommercial category includes positions of managed funds, pension funds, and other investors that are generally seeking exposure to a broad index of commodity prices as an asset class in an unleveraged and passively-managed manner. The commercial category includes positions for entities whose trading predominantly reflects hedging of over-the-counter transactions involving commodity indices—for example, a swap dealer holding long futures positions to hedge a short commodity index exposure opposite institutional traders, such as pension funds.
All of these traders—whether coming from the noncommercial or commercial categories—are generally replicating a commodity index by establishing long futures positions in the component markets and then rolling those positions forward from future to future using a fixed methodology. Some traders assigned to the Index Traders category are engaged in other futures activity that could not be disaggregated. As a result, the Index Traders category, which is typically made up of traders with long-only futures positions replicating an index, will include some long and short positions where traders have multi-dimensional trading activities, the preponderance of which is index trading. Likewise, the Index Traders category will not include some traders who are engaged in index trading, but for whom it does not represent a substantial part of their overall trading activity.
#### `transform`
The `transform` parameter modifies the requested report to show the values as the week-over-week difference, rate of change, cumulative, or normalized. These are standard parameters for all Nasdaq Data Link queries.
- `diff`
- `rdiff`
- `cumul`
- `normalize`
:::info
Explanations in this page are from the explanatory notes on the CFTC's [website](https://www.cftc.gov/MarketReports/CommitmentsofTraders/ExplanatoryNotes/index.htm)
:::

336
website/content/platform/usage/financial_statements.md vendored Normal file
View File

@@ -0,0 +1,336 @@
---
title: Financial Statements
sidebar_position: 6
description: This page provides an introduction to financial statement data available in the OpenBB
Platform. This includes quarterly and annual reports, along with metrics and ratios by company.
This guide provides examples for using the variety of sources.
keywords:
- stocks
- companies
- earnings
- dividends
- expectations
- dividend yield
- analyst consensus
- EPS
- assets
- total assets
- financial statements
- cash flow statement
- income statement
- balance sheet
- ratios
- quick ratio
- dividends
- market cap
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Financial Statements - Usage | OpenBB Platform Docs" />
OpenBB Platform data extensions provide access to financial statements as quarterly or annual. There are also endpoints for ratios and other common non-GAAP metrics. Most data providers require a subscription to access all data, refer to the website of a specific provider for details on entitlements and coverage.
Financial statement functions are grouped under the `obb.equity.fundamental` module.
:::info
To begin, import the OpenBB Platform into a Python session:
```python
from openbb import obb
```
:::
## Financial Statements
The typical financial statements consist of three endpoints:
- Balance Sheet: `obb.equity.fundamental.balance()`
- Income Statement: `obb.equity.fundamental.income()`
- Cash Flow Statement: `obb.equity.fundamental.cash()`
The main parameters are:
- `symbol`: The company's ticker symbol.
- `period`: 'annual' or 'quarter'. Default is 'annual'.
- `limit`: Limit the number of results returned, from the latest. Default is 5. For perspective, 150 will go back to 1985. The amount of historical records varies by provider.
### Field Names
:::info
- Every data provider has their own way of parsing and organizing the three financial statements.
- Items within each statement will vary by source and by the type of company reporting.
- Names of line items will vary by source.
- "Date" values may differ because they are from the period starting/ending or date of reporting.
:::
This example highlights how different providers will have different labels for compnay facts.
```python
import pandas as pd
df = pd.DataFrame()
df["yfinance"] = (
obb.equity.fundamental.balance("TGT", provider="yfinance", limit=4)
.to_df()["TotalAssets"].reset_index(drop=True)
)
df["fmp"] = (
obb.equity.fundamental.balance("TGT", provider="fmp", limit=4)
.to_df()["assets"].convert_dtypes().reset_index(drop=True)
)
df["intrinio"] = (
obb.equity.fundamental.balance("TGT", provider="intrinio", limit=4)
.to_df()["total assets"].convert_dtypes().reset_index(drop=True)
)
df["polygon"] = (
obb.equity.fundamental.balance("TGT", provider="polygon", limit=4)
.to_df()["total_assets"].convert_dtypes().reset_index(drop=True)
)
df
```
| | yfinance | fmp | intrinio | polygon |
|---:|------------:|------------:|------------:|------------:|
| 0 | 42779000000 | 42779000000 | 42779000000 | 42779000000 |
| 1 | 51248000000 | 51248000000 | 51248000000 | 51248000000 |
| 2 | 53811000000 | 53811000000 | 53811000000 | 53811000000 |
| 3 | 53335000000 | 53335000000 | 53335000000 | 53335000000 |
### Weighted Average Shares Outstanding
This key metric will be found under the income statement. It might also be called, 'basic', and the numbers do not include authorized but unissued shares. A declining count over time is a sign that the company is returning capital to shareholders in the form of buy backs. Under ideal circumstances, it is more capital-efficient, for both company and shareholders, because distributions are double-taxed. The company pays income tax on dividends paid, and the beneficiary pays income tax again on receipt.
A company will disclose how many shares are outstanding at the end of the period as a weighted average over the reporting period - three months.
Let's take a look at Target. To make the numbers easier to read, we'll divide the entire column by one million.
```python
data = (
obb.equity.fundamental.income("TGT", provider='fmp', limit=150, period="quarter")
.to_df()
)
shares = data["weighted_average_shares_outstanding"]/1000000
```
Where this data starts,
```python
shares.head(1)
```
| date | weighted_average_shares_outstanding |
|:--------------------|--------------------------------------:|
| 1986-07-31 | 1168.82 |
versus currently,
```python
shares.tail(1)
```
| date | weighted_average_shares_outstanding |
|:--------------------|--------------------------------------:|
| 2023-10-31 | 461.6 |
Thirty-seven years later, the share count is approaching a two-thirds reduction. 12.2% over the past five years.
```python
shares.pct_change(20).iloc[-1]
```
```console
-0.12
```
In four reporting periods, 1.3 million shares have been taken out of the float.
```python
shares.iloc[-4] - shares.iloc[-1]
```
```console
-1.3
```
With an average closing price of $144.27, that represents approximately $190M in buy backs.
```python
price = (
obb.equity.price.historical("TGT", start_date="2022-10-01", provider="fmp")
.to_df()
)
round((price["close"].mean()*1300000)/1000000, 2)
```
```console
187.55
```
### Dividends Paid
Dividends paid is in the cash flow statement. We can calculate the amount-per-share with the reported data.
```python
dividends = (
obb.equity.fundamental.cash("TGT", provider='fmp', limit=150, period="quarter")
.to_df()[["dividends_paid"]]
)
dividends["shares"] = data[["weighted_average_shares_outstanding"]]
dividends["div_per_share"] = dividends["dividends_paid"]/dividends["shares"]
dividends["div_per_share"].tail(4)
```
| date | div_per_share |
|:--------------|----------------:|
| 2023-01-28 | -1.07973 |
| 2023-04-29 | -1.07833 |
| 2023-07-29 | -1.08102 |
| 2023-10-31 | -1.09835 |
This can be compared against the real amounts paid to common share holders, as announced.
:::note
The dates immediately above represent the report date, dividends paid are attributed to the quarter they were paid in. The value from "2023-01-28" equates to the fourth quarter of 2022.
:::
```python
(
obb.equity.fundamental.dividends("TGT", provider="fmp")
.to_df()["dividend"]
.loc["2022-11-15":"2023-08-15"]
)
```
date | dividend |
|:--------------|-----------:|
| 2022-11-15 | 1.08 |
| 2023-02-14 | 1.08 |
| 2023-05-16 | 1.08 |
| 2023-08-15 | 1.1 |
The numbers check out, and the $2B paid to investors over four quarters is more than ten times the $190M returned through share buy backs.
### Financial Attributes
The `openbb-intrinio` data extension has an endpoint for extracting a single fact from financial statements. There is a helper function for looking up the correct `tag`.
#### Search Financial Attributes
Search attributes by keyword.
```python
obb.equity.fundamental.search_attributes("marketcap").head(1)
```
| | id | name | tag | statement_code | statement_type | parent_name | sequence | factor | transaction | type | unit |
|---:|:-----------|:----------------------|:----------|:-----------------|:-----------------|:--------------|-----------:|:---------|:--------------|:----------|:-------|
| 0 | tag_BgkbWy | Market Capitalization | marketcap | calculations | industrial | | nan | | | valuation | usd |
The `tag` is what we need, in this case it is what we searched for.
```python
marketcap = (
obb.equity.fundamental.historical_attributes(symbol="TGT", tag = "marketcap", frequency="quarterly")
.to_df()
)
marketcap.tail(5)
```
| date | value |
|:--------------|------------:|
| 2022-12-31 | 66929627287 |
| 2023-03-31 | 75023699391 |
| 2023-06-30 | 59916953938 |
| 2023-09-30 | 50614370690 |
| 2023-11-22 | 60495000000 |
Doing some quick math, and ignoring the most recent value, we can see that the market cap of Target was down nearly a quarter over the last four reporting periods.
```python
(
(marketcap.loc["2023-09-30"] - marketcap.loc["2022-12-31"])/marketcap.loc["2022-12-31"]
).value
```
```console
-0.24
```
## Ratios and Other Metrics
Other valuation functions are derivatives of the financial statements, but the data provider does the math. Values are typically ratios between line items, on a per-share basis, or as a percent growth.
This data set is where you can find EPS, FCF, P/B, EBIT, quick ratio, etc.
### Quick Ratio
Target's quick ratio could be one reason why its share price is losing traction against the market. Its ability to pay current obligations is not optimistically reflected in a 0.27 score, approximately 50% below the historical median.
```python
ratios = (
obb.equity.fundamental.ratios("TGT", limit=50, provider="fmp")
.to_df()
)
display(f"Current Quick Ratio: {ratios['quick_ratio'].iloc[-1]}")
display(f"Median Quick Ratio: {ratios['quick_ratio'].median()}")
```
```console
Current Quick Ratio: 0.27
Median Quick Ratio: 0.58
```
### Free Cash Flow Yield
The `metrics` endpoint, with the `openbb-fmp` data extension, has a field for free cash flow yield. It is calculated by taking the free cash flow per share divided by the current share price. We could arrive at this answer by writing some code, but these types of endpoints do the work so we don't have to. This is part of the value-add that API data distributors provide, they allow you to get straight to work with data.
We'll use this endpoint to extract the data, and compare with some of Target's competition over the last ten years.
```python
# List of other retail chains
tickers = ["COST", "BJ", "DLTR", "DG", "WMT", "BIG", "M", "KSS", "TJX"]
# Create a dictionary of tickers and company names.
names = {
ticker: obb.equity.fundamental.overview(ticker, provider="fmp").results.company_name
for ticker in tickers
}
# Create a column for each.
fcf_yield = pd.DataFrame()
for ticker in tickers:
fcf_yield[names[ticker]] = (
obb.equity.fundamental.metrics(ticker, provider="fmp", period="annual", limit=10)
.to_df()
.reset_index()
.set_index("calendar_year")
.sort_index(ascending=False)
["free_cash_flow_yield"]
)
fcf_yield.transpose()
```
| | 2023 | 2022 | 2021 | 2020 | 2019 | 2018 | 2017 | 2016 | 2015 | 2014 |
|:-----------------------------------|------------:|------------:|----------:|----------:|----------:|-----------:|----------:|-----------:|----------:|------------:|
| Costco Wholesale Corporation | 0.0279218 | 0.0148596 | 0.0265818 | 0.0393512 | 0.0259061 | 0.0274379 | 0.0608836 | 0.00894059 | 0.0307414 | 0.0374833 |
| BJ's Wholesale Club Holdings, Inc. | nan | 0.0447092 | 0.0672128 | 0.113551 | 0.0566305 | 0.0911069 | 0.0261863 | 0.0658713 | 0.0169474 | nan |
| Dollar Tree, Inc. | nan | 0.010756 | 0.013957 | 0.075627 | 0.040338 | 0.0412519 | 0.0340694 | 0.0634655 | 0.0166025 | 0.0410471 |
| Dollar General Corporation | nan | 0.00825589 | 0.0375074 | 0.0589731 | 0.0369217 | 0.0461971 | 0.0426088 | 0.0507761 | 0.0395241 | 0.0460518 |
| Walmart Inc. | 0.0312425 | 0.028372 | 0.0654622 | 0.0445913 | 0.062023 | 0.0572749 | 0.101038 | 0.0735059 | 0.0597117 | 0.0415436 |
| Big Lots, Inc. | nan | -0.550469 | 0.0252616 | 0.115757 | 0.0694642 | -0.111853 | 0.037219 | 0.100721 | 0.110443 | 0.089253 |
| Macy's, Inc. | nan | 0.0504726 | 0.27098 | 0.0391114 | 0.0913008 | 0.101426 | 0.155761 | 0.098993 | 0.0656336 | 0.072322 |
| Kohl's Corporation | nan | -0.143961 | 0.189677 | 0.147968 | 0.119492 | 0.139799 | 0.0961367 | 0.19879 | 0.0816518 | 0.110697 |
| The TJX Companies, Inc. | 0.0271588 | 0.0234975 | 0.0517687 | 0.0401668 | 0.0488266 | 0.0399352 | 0.0536965 | 0.0433279 | 0.0464416 | 0.0406432 |
Explore the rest of the `fundamental` module under the [Reference](/platform/reference/equity/fundamental) section.

16
website/content/platform/usage/find_symbols.md vendored
View File

@@ -1,7 +1,7 @@
---
title: Finding Symbols
sidebar_position: 3
description: This page provides comprehensive information about finding stocks in the
description: This page provides comprehensive information about finding stocks in the
with the OpenBB Platform. Search companies from different sources, and filter results.
This guide is intended to introduce some methods for searching, screening, and discovery.
keywords:
@@ -34,7 +34,7 @@ The examples on this page will assume that the OpenBB Platform has been installe
from openbb import obb
```
If the installation is fresh, or an extension was just installed, the Python interface will need to be rebuilt. It will only take a few moments to complete.
If the installation is fresh, or an extension was just installed, the Python interface will need to be rebuilt. It will only take a few moments to complete.
:::
The simplest way to find a ticker for a company is with a simple fuzzy query.
@@ -82,7 +82,7 @@ This endpoint can be used to map a ticker symbol to a CIK number.
### Find an Institution
Some reporting companies, like invesment trusts and insurance companies, do not have a ticker symbol directly associated with them. Filers in the US will have a CIK number, used to retrieve documents from the SEC.
Some reporting companies, like investment trusts and insurance companies, do not have a ticker symbol directly associated with them. Filers in the US will have a CIK number, used to retrieve documents from the SEC.
```python
obb.regulators.sec.institutions_search("Berkshire Hathaway").to_df()
@@ -150,7 +150,7 @@ obb.equity.fundamental.filings("AAPL", type="4", provider="sec").to_df().iloc[-1
## Screen Markets
Screeners provide a targeted search, a tool for comparison and discovery. Find stocks from around the world with the screener endpoint, and the `openbb-fmp` provider.
Screeners provide a targeted search, a tool for comparison and discovery. Find stocks from around the world with the screener endpoint, and the `openbb-fmp` provider.
### Find Stocks From India
@@ -227,7 +227,7 @@ results.iloc[0]
### Search by Exchange
Some countries, like America, have multiple exchanges. Narrow the search by combining two or more parameters. The example below finds the companies listed on the American Stock Exchange (AMEX) that are domiciled in China.
Some countries, like America, have multiple exchanges. Narrow the search by combining two or more parameters. The example below finds the companies listed on the American Stock Exchange (AMEX) that are domiciled in China.
```python
obb.equity.screener(exchange="amex", country="CN").to_df()
@@ -242,7 +242,7 @@ obb.equity.screener(exchange="amex", country="CN").to_df()
### Filter by Metric
Applying some filters refines and targets the search. The example below finds listing on the NYSE domiciled in the USA, with a market cap between $100-300 billion, and exhibiting a beta value of less than 0.5
Applying some filters refines and targets the search. The example below finds listing on the NYSE domiciled in the USA, with a market cap between $100-300 billion, and exhibiting a beta value of less than 0.5
```python
obb.equity.screener(
@@ -297,7 +297,7 @@ indices[indices["name"].str.contains("ASX 200")]
| S&P/ASX 200 Utilities Sector Index (AUD) | au_utilities | ^AXUJ |
:::tip
With the `openbb-yfinance` extension, index time series can be loaded using the ticker symbol or short code. Non-American indices have a code beginning with the two-letter country code.
With the `openbb-yfinance` extension, index time series can be loaded using the ticker symbol or short code. Non-American indices have a code beginning with the two-letter country code.
```python
(
@@ -312,4 +312,4 @@ With the `openbb-yfinance` extension, index time series can be loaded using the
:::
The examples above show demonstrate the most basic ways to find ticker symbols with the OpenBB Platform. Create your own custom scripts for discovery by combining these with other methods.
The examples above show demonstrate the most basic ways to find ticker symbols with the OpenBB Platform. Create your own custom scripts for discovery by combining these with other methods.

330
website/content/platform/usage/historical_prices.md vendored Normal file
View File

@@ -0,0 +1,330 @@
---
title: Historical Prices
sidebar_position: 4
description: This page provides an introduction to financial statement data available in the OpenBB
Platform. This includes quarterly and annual reports, along with metrics and ratios by company.
This guide provides examples for using the variety of sources.
keywords:
- stocks
- companies
- prices
- historical
- ohlc
- intraday
- intervals
- market data
---
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Historical Prices - Usage | OpenBB Platform Docs" />
Historical market prices typically come in the form of OHLC+V - open, high, low, close, volume. There may be additional fields returned by a provider, but those are the expected columns. Granularity and amount of historical data will vary by provider and subscription status. Visit their websites to understand what your entitlements are.
:::info
These examples will assume that the OpenBB Platform is initialized in a Python session.
```python
from openbb import obb
import pandas as pd
```
:::
## Historical OHLC
The `historical` function is located under a submodule for each asset type. In the `openbb-equity` module.
```python
help(obb.equity.price.historical)
```
- This endpoint has the most number of providers out of any function. At the time of writing, choices are:
['alpha_vantage', 'cboe', 'fmp', 'intrinio', 'polygon', 'tiingo', 'yfinance']
- Common parameters have been standardized across all sources, `start_date`, `end_date`, `interval`.
- The default interval will be `1d`.
- The depth of historical data and choices for granularity will vary by provider and subscription status. Refer to the website and documentation of each source understand your specific entitlements.
- Despite being in the `equity` module, it's might be possible to get other asset types, like currencies or crypto, from the same endpoint.
- For demonstration purposes, we will use the `openbb-yfinance` data extension.
```python
df_daily = obb.equity.price.historical(symbol = "spy", provider="yfinance")
df_daily.to_df().head(1)
```
| date | open | high | low | close | volume | dividends | stock splits | capital gains |
|:--------------|-------:|-------:|-------:|--------:|-----------:|------------:|---------------:|----------------:|
| 2022-11-22 | 396.63 | 400.07 | 395.15 | 399.9 | 60429000 | 0 | 0 | 0 |
To load the entire history available from a source, pick a starting date well beyond what it might be. For example, `1900-01-01`
```python
df_daily =(
obb.equity.price.historical(symbol = "spy", start_date = "1990-01-01", provider="yfinance")
.to_df()
)
df_daily.head(1)
```
| date | open | high | low | close | volume | dividends | stock splits | capital gains |
|:--------------|-------:|-------:|------:|--------:|-----------:|------------:|---------------:|----------------:|
| 1993-01-29 | 43.97 | 43.97 | 43.75 | 43.94 | 1003200 | 0 | 0 | 0 |
### Intervals
The intervals are entered according to this pattern:
- `1m` = One Minute
- `1h` = One Hour
- `1d` = One Day
- `1W` = One Week
- `1M` = One Month
The date for monthly value is the first or last, depending on the provider. This can be easily resampled from daily data.
```python
df_monthly = (
obb.equity.price.historical("spy", start_date="1990-01-01", interval="1M", provider="yfinance")
.to_df()
)
df_monthly.tail(2)
```
| date | open | high | low | close | volume | dividends | stock splits | capital gains |
|:--------------|-------:|-------:|-------:|--------:|------------:|------------:|---------------:|----------------:|
| 2023-10-01 | 426.62 | 438.14 | 409.21 | 418.2 | 1999149700 | 0 | 0 | 0 |
| 2023-11-01 | 419.2 | 456.38 | 418.65 | 455.02 | 1161239576 | 0 | 0 | 0 |
### Resample a Time Series
`yfinance` returns the monthly data for the first day of each month. Let's resample it to take from the last, using the daily information captured in the previous cells.
```python
(
df_daily[["open", "high", "low", "close", "volume"]]
.resample("M")
.agg(
{"open": "first", "high": "max", "low": "min", "close": "last", "volume": "sum"}
).tail(2)
)
```
| date | open | high | low | close | volume |
|:--------------|-------:|-------:|-------:|--------:|------------:|
| 2023-10-31 | 426.62 | 438.14 | 409.21 | 418.2 | 1999149700 |
| 2023-11-30 | 419.2 | 456.38 | 418.65 | 455.02 | 1210484176 |
We can see that the current month's total volume is higher when we resample the daily time series. It is difficult to know where the discrepancy lays, and it may just be a temporary glitch. However, we can verify that the total volume, according to YahooFinance, is the number we just sampled.
:::note
If you are following along, the results will not match exactly what is displayed here.
:::
```python
df_daily.loc["2023-11-01":].sum()["volume"]
```
```console
1210484176
```
### Differences Between Sources
To demonstrate the difference between sources, let's compare values for daily volume from several sources.
```python
# Collect the data
yahoo = obb.equity.price.historical("spy", provider="yfinance").to_df()
alphavantage = obb.equity.price.historical("spy", provider = "alpha_vantage").to_df()
intrinio = obb.equity.price.historical("spy", provider="intrinio").to_df()
fmp = obb.equity.price.historical("spy", provider="fmp").to_df()
# Make a new DataFrame with just the volume columns
compare = pd.DataFrame()
compare["AV Volume"] = alphavantage["volume"].tail(10)
compare["FMP Volume"] = fmp["volume"].tail(10)
compare["Intrinio Volume"] = intrinio["volume"].tail(10)
compare["Yahoo Volume"] = yahoo["volume"].tail(10)
compare
```
| date | AV Volume | FMP Volume | Intrinio Volume | Yahoo Volume |
|:--------------|------------:|-------------:|------------------:|---------------:|
| 2023-11-09 | 83174417 | 83071417 | 83174417 | 83174400 |
| 2023-11-10 | 89558054 | 89558054 | 89558054 | 89462200 |
| 2023-11-13 | 52236068 | 52192568 | 52236068 | 52236100 |
| 2023-11-14 | 97176935 | 97130503 | 97176935 | 97176900 |
| 2023-11-15 | 77327573 | 77327573 | 77327573 | 77327600 |
| 2023-11-16 | 66665797 | 66654468 | 66665797 | 66665800 |
| 2023-11-17 | 83193902 | 83193902 | 83193902 | 83133200 |
| 2023-11-20 | 70055633 | 69614633 | 70055633 | 69936200 |
| 2023-11-21 | 49244639 | 49244639 | 49244639 | 49244600 |
| 2023-11-22 | 59446573 | 59313820 | 58205780 | 59394900 |
## Other Types of Symbols
Other types of assets and ticker symbols can be loaded from `obb.equity.price.historical()`, below are some examples but not an exhaustive list.
### Share Classes
Some sources use `-` as the distinction between a share class, e.g., `BRK-A` and `BRK-B`. Other formats include:
- A period: `BRK.A`
- A slash: `BRK/A`
- No separator, the share class becomes the fourth or fifth letter.
```python
obb.equity.price.historical("brk.b", provider="polygon")
```
```python
obb.equity.price.historical("brk-b", provider="fmp")
```
While some providers handle the different formats on their end, others do not. This is something to consider when no results are returned from one source. Some may even use a combination, or accept multiple variations. Sometimes there is no real logic behind the additional characters, `GOOGL` vs. `GOOG`. These are known unknown variables of ticker symbology, what's good for one source may return errors from another.
### Regional Identifiers
With providers supporting market data from multiple jurisdictions, the most common method for requesting data outside of US-listings is to append a suffix to the ticker symbol (e.g., `RELIANCE.NS`). Formats may be unique to a provider, so it is best to review the source's documentation for an overview of their specific conventions. [This page](https://help.yahoo.com/kb/SLN2310.html) on Yahoo describes how they format symbols, which many others follow to some degree.
### Indices
Sources will have their own treatment of these symbols, some examples are:
- YahooFinance/FMP/CBOE: ^RUT
- Polygon: I:NDX
```python
obb.equity.price.historical("^RUT", provider="cboe").to_df().tail(1)
```
| date | open | high | low | close | volume |
|:--------------|--------:|--------:|--------:|--------:|---------:|
| 2023-11-22 | 1796.37 | 1804.96 | 1785.93 | 1792.92 | 0 |
```python
obb.equity.price.historical("^RUT", provider="fmp").to_df().tail(1)
```
| date | open | high | low | close | volume | vwap | label | adj_close | unadjusted_volume | change | change_percent | change_over_time |
|:--------------|--------:|--------:|--------:|--------:|---------:|--------:|:----------------|------------:|--------------------:|---------:|-----------------:|-------------------:|
| 2023-11-22 | 1792.51 | 1803.12 | 1789.88 | 1795.54 | 0 | 1796.18 | November 22, 23 | 1795.54 | 0 | 3.02893 | 0.16898 | 0.0016898 |
:::info
**For an endpoint geared more specifically towards indices, try `obb.index.market()`**
:::
### Currencies
FX symbols face the same dilemma as share classes, there are several variations of the same symbol.
- YahooFinance: `EURUSD=X`
- Polygon: `C:EURUSD`
- AlphaVantage/FMP: `EURUSD`
:::info
**The symbol prefixes are handled internally when `obb.currency.price.historical()` is used, enter as a pair with no extra characters.**
:::
```python
obb.equity.price.historical("EURUSD=X", provider="yfinance").to_df().tail(1)
```
| date | open | high | low | close | volume | dividends | stock splits |
|:--------------|-------:|-------:|-------:|--------:|---------:|------------:|---------------:|
| 2023-11-22 | 1.0918 | 1.0923 | 1.0855 | 1.0918 | 0 | 0 | 0 |
```python
obb.equity.price.historical("C:EURUSD", provider="polygon").to_df().tail(1)
```
| date | open | high | low | close | volume | vwap | transactions |
|:--------------|--------:|-------:|-------:|--------:|---------:|-------:|---------------:|
| 2023-11-21 | 1.09168 | 1.0923 | 1.0851 | 1.0888 | 155827 | 1.0893 | 155827 |
### Crypto
Similar, but different to FX tickers.
- YahooFinance: `BTC-USD`
- Polygon: `X:BTCUSD`
- AlphaVantage/FMP: `BTCUSD`
:::info
**The symbol prefixes are handled internally when `obb.crypto.price.historical()` is used, enter as a pair with no extra characters and placing the fiat currency second.**
:::
```python
obb.equity.price.historical("X:BTCUSD", provider="polygon").to_df().tail(1)
```
| date | open | high | low | close | volume | vwap | transactions |
|:--------------|-------:|-------:|------:|--------:|---------:|--------:|---------------:|
| 2023-11-21 | 35756 | 37900 | 35633 | 37433.8 | 30411.4 | 36841.5 | 464907 |
As noted above, `X:` or other prefixes are not required when using the `crypto` version of this same endpoint.
```python
obb.crypto.price.historical("BTCUSD", provider="polygon").to_df().tail(1)
```
| date | open | high | low | close | volume | vwap | transactions |
|:--------------|-------:|-------:|------:|--------:|---------:|--------:|---------------:|
| 2023-11-21 | 35756 | 37900 | 35633 | 37433.8 | 30411.4 | 36841.5 | 464907 |
### Futures
Historical prices for the continuation chart, can be fetched by the `fmp` or `yfinance` data extensions. Individual active contracts are returned by `yfinance`.
- Continuous front-month: `CL=F`
- December 2023 contract: `CLZ24.NYM`
- March 2024 contract: `CLH24.NYM`
Individual contracts will require knowing which of the CME venues the future is listed on. `["NYM", "NYB", "CME", "CBT"]`.
```python
obb.equity.price.historical("CL=F", provider="fmp").to_df().tail(1)
```
| date | open | high | low | close | volume | vwap | label | adj_close | unadjusted_volume | change | change_percent | change_over_time |
|:--------------|-------:|-------:|------:|--------:|---------:|-------:|:----------------|------------:|--------------------:|---------:|-----------------:|-------------------:|
| 2023-11-22 | 77.77 | 77.97 | 73.79 | 76.78 | 368686 | 76.18 | November 22, 23 | 76.78 | 368686 | -0.99 | -1.27 | -0.0127 |
```python
obb.equity.price.historical("CLZ24.NYM", provider="yfinance").to_df().tail(1)
```
| date | open | high | low | close | volume | dividends | stock splits |
|:--------------|-------:|-------:|------:|--------:|---------:|------------:|---------------:|
| 2023-11-22 | 74.07 | 74.07 | 73.41 | 73.46 | 610 | 0 | 0 |
### Options
Individual options contracts are also loadable from `openbb.equity.price.historical()`.
- YahooFinance: `SPY241220P00400000`
- Polygon: `O:SPY241220P00400000`
```python
obb.equity.price.historical("SPY241220P00400000", provider="yfinance").to_df().tail(1)
```
| date | open | high | low | close | volume | dividends | stock splits |
|:--------------------|-------:|-------:|------:|--------:|---------:|------------:|---------------:|
| 2023-11-22 00:00:00 | 10.5 | 10.82 | 10.25 | 10.61 | 77 | 0 | 0 |
```python
obb.equity.price.historical("O:SPY241220P00400000", provider="polygon").to_df().tail(1)
```
| date | open | high | low | close | volume | vwap | transactions |
|:--------------|-------:|-------:|------:|--------:|---------:|--------:|---------------:|
| 2023-11-20 | 10.9 | 10.95 | 10.75 | 10.75 | 17 | 10.8376 | 10 |

61
website/content/platform/usage/index.md vendored
View File

@@ -27,7 +27,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Overview - Usage | OpenBB Platform Docs" />
At its base, the OpenBB Platform supplies core architecture and services for connecting data providers and extensions, consumable as a Python client and Fast API. The extension framework provides interoperability between as many, or few, services required. Optional extras are not included with the base installation, and these include:
At its base, the OpenBB Platform supplies core architecture and services for connecting data providers and extensions, consumable as a Python client and Fast API. The extension framework provides interoperability between as many, or few, services required. Optional extras are not included with the base installation, and these include:
- Charting libraries and views
- Data cleaning
@@ -37,15 +37,15 @@ At its base, the OpenBB Platform supplies core architecture and services for con
## Authorization
By default, authorization is not required to initialize and use the core services. Most data providers, however, require an API key to access their data. They can be stored locally, or securely on the OpenBB Hub for convenient remote access. Refer to our Developer Guidelines for best practices within a production environment.
By default, authorization is not required to initialize and use the core services. Most data providers, however, require an API key to access their data. They can be stored locally, or securely on the OpenBB Hub for convenient remote access. Refer to our Developer Guidelines for best practices within a production environment.
### OpenBB Hub
Data provider credentials and user preferences can be securely stored on the OpenBB Hub and accessed via a revokable Personal Access Token (PAT). Login to the [Hub](https://my.openbb.co/) to manage this method of remote authorization.
Data provider credentials and user preferences can be securely stored on the OpenBB Hub and accessed via a revokable Personal Access Token (PAT). Login to the [Hub](https://my.openbb.co/) to manage this method of remote authorization.
#### Python Client
The OpenBB Hub is a convenient solution for accessing data in temporary environments, like Google Colab. Login using the Python client with:
The OpenBB Hub is a convenient solution for accessing data in temporary environments, like Google Colab. Login using the Python client with:
```jupyterpython
from openbb import obb
@@ -79,7 +79,7 @@ Activate the Python environment and then start the server from a Terminal comman
uvicorn openbb_core.api.rest_api:app
```
To use the Fast API documentation page, navigate to [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). By default, no authorization is required. Basic authorization can be enabled with environment variables. In the home folder, along with `user_settings.json`, create a new file, `.env`, if it does not yet exist.
To use the Fast API documentation page, navigate to [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). By default, no authorization is required. Basic authorization can be enabled with environment variables. In the home folder, along with `user_settings.json`, create a new file, `.env`, if it does not yet exist.
```.env
OPENBB_API_AUTH="True"
@@ -112,7 +112,7 @@ Refer to the Developer Guidelines for custom authorization procedures.
### Local Environment
Credentials and user preferences are stored locally, `~/.openbb_platform/`, as a JSON file, `user_settings.json`. It is read upon initializing the Python client, or when the Fast API is authorized. If the file does not exist, create it with any text editor. The schema below can be copy/pasted if required, providers not listed here are added using the same format:
Credentials and user preferences are stored locally, `~/.openbb_platform/`, as a JSON file, `user_settings.json`. It is read upon initializing the Python client, or when the Fast API is authorized. If the file does not exist, create it with any text editor. The schema below can be copy/pasted if required, providers not listed here are added using the same format:
```json
{
@@ -136,7 +136,7 @@ obb.user.credentials.intrinio_api_key = "REPLACE_WITH_KEY"
## Environment Variables
Environment variables are defined in a `.env` file. If this file does not exist, create it inside the same folder `user_settings.json` is located.
Environment variables are defined in a `.env` file. If this file does not exist, create it inside the same folder `user_settings.json` is located.
- `OPENBB_DEBUG_MODE`: enables verbosity while running the program
- `OPENBB_DEVELOP_MODE`: points hub service to .co or .dev
@@ -199,7 +199,7 @@ obb.user.preferences
obb.user.defaults
```
Notably, `obb.user.defaults`, defines default providers for any command. They are stored in the `user_settings.json` file, under `routes`. Below is an example of what it might look like.
Notably, `obb.user.defaults`, defines default providers for any command. They are stored in the `user_settings.json` file, under `routes`. Below is an example of what it might look like.
```json
{
@@ -223,20 +223,22 @@ Notably, `obb.user.defaults`, defines default providers for any command. They a
}
},
{
"data_directory": "~/OpenBBUserData", // Where to store data
"export_directory": "~/OpenBBUserData/exports", // Where to store exports
"cache_directory": "~/OpenBBUserData/cache", // Where to store the cache
"user_styles_directory": "~/OpenBBUserData/styles/user", // Where to store user styles
"charting_extension": "openbb_charting", // Charting extension to use
"chart_style": "dark", // Chart style to use (dark or light)
"plot_enable_pywry": true, // Whether to enable PyWry
"plot_pywry_width": 1400, // PyWry width
"plot_pywry_height": 762, // PyWry height
"plot_open_export": false, // Whether to open plot image exports after they are created
"table_style": "dark", // Table style to use (dark or light)
"request_timeout": 15, // Request timeout
"metadata": true, // Whether to include metadata in the output
"output_type": "OBBject" // Our default output type (OBBject, dataframe, polars, numpy, dict, chart)
"preferences": {
"data_directory": "~/OpenBBUserData", // Where to store data
"export_directory": "~/OpenBBUserData/exports", // Where to store exports
"cache_directory": "~/OpenBBUserData/cache", // Where to store the cache
"user_styles_directory": "~/OpenBBUserData/styles/user", // Where to store user styles
"charting_extension": "openbb_charting", // Charting extension to use
"chart_style": "dark", // Chart style to use (dark or light)
"plot_enable_pywry": true, // Whether to enable PyWry
"plot_pywry_width": 1400, // PyWry width
"plot_pywry_height": 762, // PyWry height
"plot_open_export": false, // Whether to open plot image exports after they are created
"table_style": "dark", // Table style to use (dark or light)
"request_timeout": 15, // Request timeout
"metadata": true, // Whether to include metadata in the output
"output_type": "OBBject" // Our default output type (OBBject, dataframe, polars, numpy, dict, chart)
}
}
}
```
@@ -253,7 +255,7 @@ Notably, `obb.user.defaults`, defines default providers for any command. They a
## Basic Response
The output of every command is an object which contains the results of the request, along with additional information. It is a custom class, `OBBject`, and always returns with the fields listed below:
The output of every command is an object which contains the results of the request, along with additional information. It is a custom class, `OBBject`, and always returns with the fields listed below:
```console
id: ... # UUID Tag
@@ -285,7 +287,7 @@ extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'polygon'},
Additional class methods are helpers for converting the results to a variety of formats.
- `to_dict()`: converts to a dictionary of lists.
- `to_dict()`: converts to a dictionary, accepting all standard "orientation" parameters, i.e., "records"
- `to_df()` / `to_dataframe()`: converts to a Pandas DataFrame.
- `to_numpy()`: converts to a Numpy array.
- `to_polars()`: converts to a Polars table.
@@ -309,9 +311,18 @@ if response.status_code == 200:
data.to_df()
```
:::info
The preferred output type can be set with a user preference.
```python
obb.user.preferences.output_type="dataframe"
```
:::
## Dynamic Command Execution
Dynamic execution provides an alternate entry point to functions. This method requires formatting the query as demonstrated below.
Dynamic execution provides an alternate entry point to functions. This method requires formatting the query as demonstrated below.
```python
from openbb_core.app.command_runner import CommandRunner

31
website/content/platform/usage/market_calendars.md vendored
View File

@@ -1,9 +1,9 @@
---
title: Market Calendars
sidebar_position: 4
description: This page provides details on the market calendars available in the OpenBB
sidebar_position: 5
description: This page provides details on the market calendars available in the OpenBB
Platform. Equity and economic calendars keep investors abreast of market activity and events.
This guide provides examples for using the variety of calendars, and differences between sources.
This guide provides examples for using the variety of calendars, and differences between sources.
keywords:
- stocks
- companies
@@ -33,7 +33,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
<HeadTitle title="Market Calendars - Usage | OpenBB Platform Docs" />
Market calendars are an essential part of any analyst's daily rituals. Economic events and corporate actions provide near-term trading opportunities (or reasons to get out of the way) as expectations meet reality. The OpenBB Platform has a variety of calendars.
Market calendars are an essential part of any analyst's daily rituals. Economic events and corporate actions provide near-term trading opportunities (or reasons to get out of the way) as expectations meet reality. The OpenBB Platform has a variety of calendars.
- Economic
- Earnings
@@ -48,6 +48,7 @@ Examples on this page will assume that the OpenBB Platform is installed, the Pyt
```python
from openbb import obb
import pandas as pd
```
:::
@@ -57,12 +58,12 @@ from openbb import obb
The economic calendar aggregates global central bank and macroeconomic releases, it is located within the `obb.economy` module.
:::tip
Do not rely on the economic calendar for real-time updates. Times posted are scheduled by publishers and are estimates which do not reflect the actual time data is released to the public.
Do not rely on the economic calendar for real-time updates. Times posted are scheduled by publishers and are estimates which do not reflect the actual time data is released to the public.
:::
### Timezone Considerations
There are subtle differences between providers, the main consideration will be the timestamp. FMP and TradingEconomics both return the calendar as UTC-0, while Nasdaq posts events in US/Eastern time. Of the three, only TradingEconomics provides a TZ-aware timestamp. The differences can be reconciled with a few lines of code.
There are subtle differences between providers, the main consideration will be the timestamp. FMP and TradingEconomics both return the calendar as UTC-0, while Nasdaq posts events in US/Eastern time. Of the three, only TradingEconomics provides a TZ-aware timestamp. The differences can be reconciled with a few lines of code.
To identify the issue, let's look at one event. First, from FMP:
@@ -112,9 +113,9 @@ For these reasons, among others, it is important for users to know and understan
### Filtering by Event
The providers do not have a pre-request filter for a specific event. TradingEconomics does have categories, like 'government', but that does not focus it on any particular release. To find something like PMI reports, search for it post-request.
The providers do not have a pre-request filter for a specific event. TradingEconomics does have categories, like 'government', but that does not focus it on any particular release. To find something like PMI reports, search for it post-request.
FMP allows queries to this endpoint to be a maximum width of three months. To get the year-to-date events, requests will need to loop. The code below will do that, filter the results for ISM Manufacturing New Orders, and display the table of hits.
FMP allows queries to this endpoint to be a maximum width of three months. To get the year-to-date events, requests will need to loop. The code below will do that, filter the results for ISM Manufacturing New Orders, and display the table of hits.
### ISM New Orders
@@ -152,7 +153,7 @@ events[events["event"].str.contains("ISM Manufacturing New Orders")]
## Earnings Calendar
The earnings calendar works in a similar way. For companies outside of the US, try the `openbb-fmp` provider.
The earnings calendar works in a similar way. For companies outside of the US, try the `openbb-fmp` provider.
```python
calendar = (
@@ -164,7 +165,7 @@ calendar = (
)
```
This returned 1,234 results, but let's filter it down to those companies with analysts estimates, and display the top ten by EPS conensus.
This returned 1,234 results, but let's filter it down to those companies with analysts estimates, and display the top ten by EPS consensus.
```python
(
@@ -194,7 +195,7 @@ EPS values are reported in the currency of the exchange listing price, direct co
## Dividend Calendar
The dividend calendar uses start/end dates that reflect the ex-dividend date - the date when it begins trading without dividend rights. Aside from the notable dates, the information returned tells you only the amount paid. Calculating the yield requires more data.
The dividend calendar uses start/end dates that reflect the ex-dividend date - the date when it begins trading without dividend rights. Aside from the notable dates, the information returned tells you only the amount paid. Calculating the yield requires more data.
:::note
@@ -207,7 +208,7 @@ The dividend calendar uses start/end dates that reflect the ex-dividend date - t
### Calculate Dividend Yield
The ten highest-payments going ex-div between November 20-24 are shown below. With T+2 settlement, a purchase needs to occur two days prior to the record date for payment eligibility. The dividend yield is the current payment annualized as a percent of the asset's price.
The ten highest-payments going ex-div between November 20-24 are shown below. With T+2 settlement, a purchase needs to occur two days prior to the record date for payment eligibility. The dividend yield is the current payment annualized as a percent of the asset's price.
```python
dividends = (
@@ -256,7 +257,7 @@ dividends["yield"] = (
## IPO Calendar
The IPO calendar shows events based on their status - `["upcoming", "priced", "withdrawn"]` - and Intrinio provides a filter for the min/max dollar amount offerred.
The IPO calendar shows events based on their status - `["upcoming", "priced", "withdrawn"]` - and Intrinio provides a filter for the min/max dollar amount offered.
:::note
The data from both Intrinio and Nasdaq is US-only, both relying on the SEC for filing information.
@@ -266,7 +267,7 @@ Use the `status` parameter to find announcements in different stages of the cycl
### Upcoming
The initial public offerings that are confirmed to be coming to market are categorized as 'upcoming'. The number of companies going public at any given time will depend on market cycles.
The initial public offerings that are confirmed to be coming to market are categorized as 'upcoming'. The number of companies going public at any given time will depend on market cycles.
```python
obb.equity.calendar.ipo(provider="nasdaq", status="upcoming").to_df()
@@ -292,7 +293,7 @@ obb.equity.calendar.ipo(provider="nasdaq", status="withdrawn").to_df().tail(3)
### SPO
SPOs, secondary pubic offerings, are shares being sold by investors after an IPO. The money does not go to the company, but directly to the investor selling shares into the market. The `openbb-nasdaq` provider has an additional boolean parameter, `is_spo`. By default, year-to-date data is returned.
SPOs, secondary pubic offerings, are shares being sold by investors after an IPO. The money does not go to the company, but directly to the investor selling shares into the market. The `openbb-nasdaq` provider has an additional boolean parameter, `is_spo`. By default, year-to-date data is returned.
```python
obb.equity.calendar.ipo(provider="nasdaq", is_spo=True).to_df().tail(1)

6
website/content/pro/getting-started/free-trial.md vendored
View File

@@ -20,7 +20,7 @@ import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
There are 3 main ways to get started:
1. Join the waitlist at https://my.openbb.co/app/pro/early-access
1. Join the wait list at <https://my.openbb.co/app/pro/early-access>
2. Get invited by a colleague who already has access
@@ -28,12 +28,10 @@ There are 3 main ways to get started:
The free trial of **OpenBB Terminal Pro** grants you full access to all features and data for a period of 2 weeks.
To continue using the product after the trial period you can reach out to sales@openbb.finance to extend your trial and discuss pricing options.
To continue using the product after the trial period you can reach out to <sales@openbb.finance> to extend your trial and discuss pricing options.
As an early adopter, your feedback is invaluable. The OpenBB team may reach out to understand your experience and gather insights for improvement.
Note: For your security, you'll need to set up 2-Factor authentication when you log in.
## Personalized Onboarding
Upon your first login, we'll ask a few questions about your investment interests, background, and workflow.

10
website/content/terminal/installation/pypi.md vendored
View File

@@ -208,7 +208,7 @@ Make sure to have completed all previous steps. If followed, there will be a vir
Install the main package of Openbb SDK with `pip`, a package manager.
```shell
pip install openbb-terminal --no-cache-dir
pip install openbb==3.2.4 --no-cache-dir
```
This method provides access to the data aggregation and charting functions of the OpenBB SDK. It does not provide access to the advanced features that are provided by the Portfolio Optimization and Machine Learning toolkits.
@@ -216,23 +216,23 @@ This method provides access to the data aggregation and charting functions of th
The toolkits can be installed individually with:
```shell
pip install "openbb-terminal[optimization]" --no-cache-dir
pip install "openbb[optimization]==3.2.4" --no-cache-dir
```
and
```shell
pip install "openbb-terminal[forecast]" --no-cache-dir
pip install "openbb[forecast]==3.2.4" --no-cache-dir
```
Install all available toolkits at once with:
```shell
pip install "openbb-terminal[all]" --no-cache-dir
pip install "openbb[all]==3.2.4" --no-cache-dir
```
:::info
`pip install openbb-terminal[all]` is not yet compatible with environments such as Google Colab and Kaggle as they come with preinstalled packages that can conflict with the ones used in the OpenBBTerminal and SDK. It may be possible to install without the extra toolkits, but we currently do not officially support this type of installation. We are working on a solution to this problem and will update this section once it is resolved.
`pip install openbb[all]==3.2.4` is not yet compatible with environments such as Google Colab and Kaggle as they come with preinstalled packages that can conflict with the ones used in the OpenBBTerminal and SDK. It may be possible to install without the extra toolkits, but we currently do not officially support this type of installation. We are working on a solution to this problem and will update this section once it is resolved.
:::
## Verify Installation

61
website/package-lock.json generated vendored
View File

@@ -16,6 +16,7 @@
"@radix-ui/react-dialog": "^1.0.2",
"@radix-ui/react-popover": "^1.0.3",
"@radix-ui/react-tooltip": "^1.0.5",
"axios": "^1.6.2",
"clsx": "^1.2.1",
"fuse.js": "^6.6.2",
"hast-util-is-element": "^1.1.0",
@@ -4416,6 +4417,11 @@
"resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
"integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA=="
},
"node_modules/asynckit": {
"version": "0.4.0",
"resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
"integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q=="
},
"node_modules/at-least-node": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/at-least-node/-/at-least-node-1.0.0.tgz",
@@ -4457,11 +4463,13 @@
}
},
"node_modules/axios": {
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/axios/-/axios-0.25.0.tgz",
"integrity": "sha512-cD8FOb0tRH3uuEe6+evtAbgJtfxr7ly3fQjYcMcuPlgkwVS9xboaVIpcDV+cYQe+yGykgwZCs1pzjntcGa6l5g==",
"version": "1.6.2",
"resolved": "https://registry.npmjs.org/axios/-/axios-1.6.2.tgz",
"integrity": "sha512-7i24Ri4pmDRfJTR7LDBhsOTtcm+9kjX5WiY1X3wIisx6G9So3pfMkEiU7emUBe46oceVImccTEM3k6C5dbVW8A==",
"dependencies": {
"follow-redirects": "^1.14.7"
"follow-redirects": "^1.15.0",
"form-data": "^4.0.0",
"proxy-from-env": "^1.1.0"
}
},
"node_modules/babel-loader": {
@@ -5150,6 +5158,17 @@
"node": ">=10"
}
},
"node_modules/combined-stream": {
"version": "1.0.8",
"resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
"integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==",
"dependencies": {
"delayed-stream": "~1.0.0"
},
"engines": {
"node": ">= 0.8"
}
},
"node_modules/comma-separated-tokens": {
"version": "1.0.8",
"resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-1.0.8.tgz",
@@ -5895,6 +5914,14 @@
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/delayed-stream": {
"version": "1.0.0",
"resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz",
"integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==",
"engines": {
"node": ">=0.4.0"
}
},
"node_modules/depd": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz",
@@ -6816,6 +6843,19 @@
"node": ">=6"
}
},
"node_modules/form-data": {
"version": "4.0.0",
"resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.0.tgz",
"integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==",
"dependencies": {
"asynckit": "^0.4.0",
"combined-stream": "^1.0.8",
"mime-types": "^2.1.12"
},
"engines": {
"node": ">= 6"
}
},
"node_modules/forwarded": {
"version": "0.2.0",
"resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -9999,6 +10039,11 @@
"node": ">= 0.10"
}
},
"node_modules/proxy-from-env": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/proxy-from-env/-/proxy-from-env-1.1.0.tgz",
"integrity": "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="
},
"node_modules/pump": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/pump/-/pump-3.0.0.tgz",
@@ -12947,6 +12992,14 @@
"node": ">=10.0.0"
}
},
"node_modules/wait-on/node_modules/axios": {
"version": "0.25.0",
"resolved": "https://registry.npmjs.org/axios/-/axios-0.25.0.tgz",
"integrity": "sha512-cD8FOb0tRH3uuEe6+evtAbgJtfxr7ly3fQjYcMcuPlgkwVS9xboaVIpcDV+cYQe+yGykgwZCs1pzjntcGa6l5g==",
"dependencies": {
"follow-redirects": "^1.14.7"
}
},
"node_modules/watchpack": {
"version": "2.4.0",
"resolved": "https://registry.npmjs.org/watchpack/-/watchpack-2.4.0.tgz",

2
website/pypi.md vendored
View File

@@ -19,7 +19,7 @@ More information on this product can be found [here](https://openbb.co/products/
The command below provides access to the core functionalities behind the [OpenBB Terminal](https://openbb.co/products/terminal).
```python
pip install openbb-terminal
pip install openbb==3.2.4
```
If you wish to utilize our **Portfolio Optimization** or **Machine Learning / Artificial Intelligence** toolkits, please see instructions [here](https://docs.openbb.co/terminal/installation).