mirror of
https://github.com/OpenBB-finance/OpenBB.git
synced 2026-10-27 12:40:35 +00:00
[Docs] Break Out Usage Section In Docs Pages (#6258)
* break out the Usage section in docs pages * codespell
This commit is contained in:
Danglewood
11
website/content/platform/installation.md
vendored
11
website/content/platform/installation.md
vendored
@@ -254,6 +254,17 @@ obb.account.login(pat='my_pat_here')
|
||||
|
||||
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.
|
||||
|
||||
### Generate Markdown Files
|
||||
|
||||
Markdown files for the Reference and Data Models pages need to be generated.
|
||||
This will generate content based on what is actually installed and contained locally, so it may appear different than what is on this website.
|
||||
|
||||
Open a terminal command line to the `/OpenBBTerminal/website` folder, then enter:
|
||||
|
||||
```bash
|
||||
python generate_platform_v4_markdown.py
|
||||
```
|
||||
|
||||
### Node.js
|
||||
|
||||
- [Node.js](https://nodejs.org/en/) >= 16.13.0
|
||||
|
||||
91
website/content/platform/usage/api_keys.md
vendored
Normal file
91
website/content/platform/usage/api_keys.md
vendored
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: API Keys
|
||||
sidebar_position: 1
|
||||
description: An overview for setting up the OpenBB Platform Python client and Fast API with data provider API keys.
|
||||
keywords:
|
||||
- OpenBB Platform
|
||||
- Python client
|
||||
- Fast API
|
||||
- getting started
|
||||
- authorization
|
||||
- data providers
|
||||
- OpenBB Hub
|
||||
- local environment
|
||||
- environment variables
|
||||
---
|
||||
|
||||
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
|
||||
|
||||
<HeadTitle title="API Keys - Usage | OpenBB Platform Docs" />
|
||||
|
||||
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. Keys can be stored locally and they can also be securely saved to your OpenBB Hub [account](https://my.openbb.co) for convenient remote access.
|
||||
|
||||
### OpenBB Hub
|
||||
|
||||
:::info
|
||||
The OpenBB Hub is only accessible via the Python Interface. For REST API, store credentials and preferences in the `user_settings.json` file [local](api_keys#local-environment) to the deployment.
|
||||
:::
|
||||
|
||||
|
||||
Data provider credentials and user preferences can be securely stored on the OpenBB Hub and accessed in Python using a revokable Personal Access Token (PAT). Login to the [Hub](https://my.openbb.co/) to manage this method of remote authorization.
|
||||
|
||||
The OpenBB Hub is a convenient solution for accessing data in temporary Python environments, like Google Colab ([example notebook](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/examples/googleColab.ipynb)). Login with:
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
|
||||
# Login with personal access token
|
||||
obb.account.login(pat="my_pat", remember_me=True)
|
||||
|
||||
# Alternatively, login with email and password
|
||||
obb.account.login(email="my_email", password="my_password", remember_me=True)
|
||||
|
||||
# Change a credential
|
||||
obb.user.credentials.polygon_api_key = "my_api_key"
|
||||
|
||||
# Save account changes to the Hub
|
||||
obb.account.save()
|
||||
|
||||
# Refresh account with latest changes
|
||||
obb.account.refresh()
|
||||
|
||||
# Logout
|
||||
obb.account.logout()
|
||||
```
|
||||
|
||||
Set `remember_me` as `False` to discard all credentials at the end of the session.
|
||||
|
||||
|
||||
:::tip
|
||||
With `remember_me=True`, credentials will be permanently stored in the environment.
|
||||
Wrapping this sequence before deploying an API server is one (insecure) way to authorize data providers for remote access.
|
||||
:::
|
||||
|
||||
### 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, it will be created on the first run. The schema below can be copy/pasted as a template:
|
||||
|
||||
```json
|
||||
{
|
||||
"credentials": {
|
||||
"fmp_api_key": "REPLACE",
|
||||
"polygon_api_key": "REPLACE",
|
||||
"benzinga_api_key": "REPLACE",
|
||||
"fred_api_key": "REPLACE",
|
||||
"nasdaq_api_key": "REPLACE",
|
||||
"intrinio_api_key": "REPLACE",
|
||||
"alpha_vantage_api_key": "REPLACE",
|
||||
"biztoc_api_key": "REPLACE",
|
||||
"tradier_api_key": "REPLACE",
|
||||
"tradier_account_type": "sandbox OR live",
|
||||
"tradingeconomics_api_key": "REPLACE",
|
||||
"tiingo_token": "REPLACE"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To set keys from the Python client for the current session only, access the Credentials class:
|
||||
|
||||
```python
|
||||
obb.user.credentials.intrinio_api_key = "my_api_key"
|
||||
```
|
||||
138
website/content/platform/usage/basic_response.md
vendored
Normal file
138
website/content/platform/usage/basic_response.md
vendored
Normal file
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: Basic Response & Command Coverage
|
||||
sidebar_position: 4
|
||||
description: This page details the basic response and output that can be expected to be received from the the OpenBB Platform, as well as instructions for determining the command coverage provided by the installed extensions.
|
||||
keywords:
|
||||
- standardized output
|
||||
- OBBject
|
||||
- basic response
|
||||
- provider
|
||||
- results
|
||||
- warnings
|
||||
- chart
|
||||
- extra
|
||||
- command coverage
|
||||
---
|
||||
|
||||
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
|
||||
|
||||
<HeadTitle title="Basic Response - Usage | OpenBB Platform Docs" />
|
||||
|
||||
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
|
||||
results: ... # Serializable results.
|
||||
provider: ... # Provider name.
|
||||
warnings: ... # List of warnings.
|
||||
chart: ... # Chart object.
|
||||
extra: ... # Extra info.
|
||||
```
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
|
||||
data = obb.equity.price.historical("SPY", provider="polygon")
|
||||
|
||||
data
|
||||
```
|
||||
|
||||
```console
|
||||
OBBject
|
||||
|
||||
id: 06520558-d54a-7e53-8000-7aafc8a42694
|
||||
results: [{'date': datetime.datetime(2022, 10, 5, 0, 0), 'open': 375.62, 'high': 37...
|
||||
provider: polygon
|
||||
warnings: None
|
||||
chart: None
|
||||
extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'polygon'}, 'st...
|
||||
```
|
||||
|
||||
Additional class methods are helpers for converting the results to a variety of formats.
|
||||
|
||||
- `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.
|
||||
|
||||
The output from the Fast API is a serialized version of this object, and these methods are lost on conversion. OBBject can be reconstructed to recover the helpers by importing the model and validating the data.
|
||||
|
||||
```python
|
||||
import requests
|
||||
from openbb_core.app.model.obbject import OBBject
|
||||
|
||||
data = []
|
||||
symbol="SPY"
|
||||
url = f"http://127.0.0.1:8000/api/v1/equity/price/historical?provider=polygon&symbol={symbol}"
|
||||
headers = {"accept": "application/json"}
|
||||
|
||||
response = requests.get(url, headers=headers, timeout=3)
|
||||
|
||||
if response.status_code == 200:
|
||||
data = OBBject.model_validate(response.json())
|
||||
|
||||
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.
|
||||
|
||||
```python
|
||||
from openbb_core.app.command_runner import CommandRunner
|
||||
runner = CommandRunner()
|
||||
output = await runner.run(
|
||||
"/equity/fundamental/ratios",
|
||||
provider_choices={
|
||||
"provider": "fmp",
|
||||
},
|
||||
standard_params={
|
||||
"symbol" : "TSLA",
|
||||
"period" : "quarter",
|
||||
},
|
||||
extra_params={}
|
||||
)
|
||||
```
|
||||
|
||||
```console
|
||||
>>> output
|
||||
OBBject
|
||||
|
||||
id: 065241b7-bd9d-7313-8000-9406d8afab75
|
||||
results: [{'symbol': 'TSLA', 'date': '2023-06-30', 'period': 'Q2', 'current_ratio':...
|
||||
provider: fmp
|
||||
warnings: None
|
||||
chart: None
|
||||
extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'fmp'}, 'standa...
|
||||
```
|
||||
|
||||
## Commands and Provider Coverage
|
||||
|
||||
The installed commands and data providers are found under, `obb.coverage`.
|
||||
|
||||
```python
|
||||
obb.coverage
|
||||
```
|
||||
|
||||
```console
|
||||
/coverage
|
||||
|
||||
providers
|
||||
commands
|
||||
command_model
|
||||
command_schemas
|
||||
```
|
||||
|
||||
`obb.coverage.providers` is a dictionary of the installed provider extensions, each with its own list of available commands.
|
||||
|
||||
`obb.coverage.commands` is a dictionary of commands, each with its own list of available providers for the data.
|
||||
|
||||
`obb.coverage.command_model` is a dictionary where the keys are the command paths and the values is a nested dictionary of QueryParams and Data models associated with that function.
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Basic Syntax
|
||||
sidebar_position: 2
|
||||
sidebar_position: 5
|
||||
description: This page provides comprehensive information about standardized command
|
||||
syntax for an open-source platform. Topics discussed include the structure of command
|
||||
syntax, use of standardized parameters, usage of provider and symbol parameters,
|
||||
|
||||
4
website/content/platform/usage/explanation/_category_.json
vendored
Normal file
4
website/content/platform/usage/explanation/_category_.json
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "Explanation",
|
||||
"position": 6
|
||||
}
|
||||
35
website/content/platform/usage/explanation/index.md
vendored
Normal file
35
website/content/platform/usage/explanation/index.md
vendored
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Explanation
|
||||
sidebar_position: 1
|
||||
description: This section provides explanations of concepts related to usage and getting started with the OpenBB Platform.
|
||||
The pages include example syntax and outline what you can expect while working with the OpenBB Python interface and REST API.
|
||||
keywords:
|
||||
- getting started
|
||||
- explanation
|
||||
- guide
|
||||
- syntax
|
||||
- examples
|
||||
- symbols
|
||||
- calendars
|
||||
- commitment of traders
|
||||
- financial statements
|
||||
- time series
|
||||
- historical prices
|
||||
---
|
||||
|
||||
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
|
||||
|
||||
<HeadTitle title="Explanation - Usage | OpenBB Platform Docs" />
|
||||
|
||||
This section provides explanations for getting started using the OpenBB Platform.
|
||||
Pages outline things to expect and include example syntax for use.
|
||||
|
||||
Subjects covered include:
|
||||
|
||||
- [Finding Ticker Symbols](explanation/find_symbols)
|
||||
- [Loading Historical Price Data](explanation/historical_prices)
|
||||
- [Market Calendars](explanation/market_calendars)
|
||||
- [Financial Statements](explanations/financial_statements)
|
||||
- [Commitment of Traders](explanations/commitment_of_traders)
|
||||
|
||||
Jupyter Notebook examples are also hosted in the OpenBB GitHub repository [here](https://github.com/OpenBB-finance/OpenBBTerminal/tree/develop/examples)
|
||||
319
website/content/platform/usage/index.md
vendored
319
website/content/platform/usage/index.md
vendored
@@ -27,316 +27,25 @@ 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 through the Python client or the 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 through the Python client or the 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
|
||||
- Data processing and calculations
|
||||
- Technical/Quantitative Analysis
|
||||
- Community data providers
|
||||
- Toolkit extensions
|
||||
- CLI Terminal
|
||||
|
||||
## Authorization
|
||||
Additional functionality and data providers can be installed or removed independently. Refer to [Extensions](extensions) for the list of extensions hosted in the OpenBB GitHub repository.
|
||||
|
||||
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. The API keys 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.
|
||||
The pages in this section cover topics to get started using the OpenBB Platform, including:
|
||||
|
||||
### OpenBB Hub
|
||||
|
||||
Data provider credentials and user preferences can be securely stored on the OpenBB Hub and accessed in Python using a revokable Personal Access Token (PAT). Login to the [Hub](https://my.openbb.co/) to manage this method of remote authorization.
|
||||
|
||||
The OpenBB Hub is a convenient solution for accessing data in temporary Python environments, like Google Colab ([example notebook](https://github.com/OpenBB-finance/OpenBBTerminal/blob/develop/examples/googleColab.ipynb)). Login with:
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
|
||||
# Login with personal access token
|
||||
obb.account.login(pat="my_pat", remember_me=True)
|
||||
|
||||
# Alternatively, login with email and password
|
||||
obb.account.login(email="my_email", password="my_password", remember_me=True)
|
||||
|
||||
# Change a credential
|
||||
obb.user.credentials.polygon_api_key = "my_api_key"
|
||||
|
||||
# Save account changes to the Hub
|
||||
obb.account.save()
|
||||
|
||||
# Refresh account with latest changes
|
||||
obb.account.refresh()
|
||||
|
||||
# Logout
|
||||
obb.account.logout()
|
||||
```
|
||||
|
||||
Set `remember_me` as `False` to discard all credentials at the end of the session.
|
||||
|
||||
### 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:
|
||||
|
||||
```json
|
||||
{
|
||||
"credentials": {
|
||||
"fmp_api_key": "REPLACE_ME",
|
||||
"polygon_api_key": "REPLACE_ME",
|
||||
"benzinga_api_key": "REPLACE_ME",
|
||||
"fred_api_key": "REPLACE_ME",
|
||||
"nasdaq_api_key": "REPLACE_ME",
|
||||
"intrinio_api_key": "REPLACE_ME",
|
||||
"alpha_vantage_api_key": "REPLACE_ME",
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To set keys from the Python client for the current session only, access the Credentials class:
|
||||
|
||||
```python
|
||||
obb.user.credentials.intrinio_api_key = "my_api_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.
|
||||
|
||||
- `OPENBB_DEBUG_MODE`: enables verbosity while running the program
|
||||
- `OPENBB_DEVELOP_MODE`: points hub service to .co or .dev
|
||||
- `OPENBB_AUTO_BUILD`: enables automatic SDK package build on import
|
||||
- `OPENBB_CHARTING_EXTENSION`: specifies which charting extension to use
|
||||
- `OPENBB_API_AUTH_EXTENSION`: specifies which authentication extension to use
|
||||
- `OPENBB_API_AUTH`: enables API authentication for command endpoints
|
||||
- `OPENBB_API_USERNAME`: sets API username
|
||||
- `OPENBB_API_PASSWORD`: sets API password
|
||||
|
||||
Variables can be defined for current session only.
|
||||
|
||||
```python
|
||||
import os
|
||||
os.environ["OPENBB_DEBUG_MODE"] = "True"
|
||||
from openbb import obb
|
||||
```
|
||||
|
||||
### Proxy Networks
|
||||
|
||||
An environment variable can be set, in the `.env` file, to direct the Requests library to a specific address and port.
|
||||
|
||||
```env
|
||||
HTTP_PROXY="<ADDRESS>" or HTTPS_PROXY="<ADDRESS>”
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```env
|
||||
HTTP_PROXY="http://10.10.10.10:8000"
|
||||
```
|
||||
|
||||
## User Settings
|
||||
|
||||
| **Preference** | **Default** | **Options** | **Description** |
|
||||
|-----------------------|----------------------------------|------------------------|---------------|
|
||||
| data_directory | /home/OpenBBUserData | Any path. | When launching the application for the first time this directory will be created. It serves as the default location where the application stores usage artifacts such as logs and exports. |
|
||||
| export_directory | /home/OpenBBUserData/exports | Any path. | The OpenBB Charting Extension provides the capability to export images in various formats. This is the directory where it attempts to save such exports. |
|
||||
| cache_directory | /home/OpenBBUserData/cache | Any path. | The directory where http requests and database caches are stored, for functions with caching. |
|
||||
| user_styles_directory | /home/OpenBBUserData/styles/user | Any path. | The OpenBB Charting Extension supports custom stylization. This directory is the location where it looks for user-defined styles. If no user styles are found in this directory the application will proceed with the default styles. |
|
||||
| charting_extension | openbb_charting | ["openbb_charting"] | Name of the charting extension to be used with the application. |
|
||||
| chart_style | dark | ["dark", "light"] | The default color style to use with the OpenBB Charting Extension plots. Options include "dark" and "light". |
|
||||
| plot_enable_pywry | True | [True, False] | Whether the application should enable PyWry. If PyWry is disabled the image will open in your default browser otherwise it will be displayed within your editor or in a separate PyWry window. |
|
||||
| plot_pywry_width | 1400 | Any positive integer. | PyWry window width. |
|
||||
| plot_pywry_height | 762 | Any positive integer. | PyWry window height. |
|
||||
| plot_open_export | False | [True, False] | Controls whether the "Save As" window should pop up as soon as the image is displayed." |
|
||||
| table_style | dark | ["dark", "light"] | "The default color style to use with the OpenBB Charting Extension tables. Options are "dark" and "light"" |
|
||||
| request_timeout | 15 | Any positive integer. | Specifies the timeout duration for HTTP requests. |
|
||||
| metadata | True | [True, False] | Enables or disables the collection of metadata which provides information about operations including arguments duration route and timestamp. Disabling this feature may improve performance in cases where contextual information is not needed or when the additional computation time and storage space are a concern. |
|
||||
| output_type | OBBject | ["OBBject", "dataframe", "numpy", "dict", "chart", "polars"] | Specifies the type of data the application will output when a command or endpoint is accessed. Note that choosing data formats only available in Python such as `dataframe`, `numpy` or `polars` will render the application's API non-functional. |
|
||||
| show_warnings | True | [True, False] | Enables or disables the display of warnings. |
|
||||
|
||||
User settings can be set from the Python interface directly.
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
|
||||
obb.user.profile
|
||||
obb.user.credentials
|
||||
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.
|
||||
|
||||
```json
|
||||
{
|
||||
"credentials": {
|
||||
"benzinga_api_key": null,
|
||||
"fmp_api_key": null,
|
||||
"polygon_api_key": null,
|
||||
"fred_api_key": null
|
||||
},
|
||||
"defaults": {
|
||||
"routes": {
|
||||
"/equity/fundamental/balance": {
|
||||
"provider": "polygon"
|
||||
},
|
||||
"/equity/price/historical": {
|
||||
"provider": "fmp"
|
||||
},
|
||||
"/equity/news": {
|
||||
"provider": "benzinga"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"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)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
### **Notes on Preferences**
|
||||
|
||||
- If a `OpenBBUserData` folder in not in the home directory, the application will create one on first run. The user preferences with paths all default to this folder, be it exports, styles or data - this can be changed at any time to suit.
|
||||
- The `OpenBBUserData` will still be created even if preferences are not pointing to it, this is because the application needs a place to store logs and other artifacts.
|
||||
- One way of exporting files or images on the OpenBB Platform is to leverage that functionality from the OpenBB Charting Extension. The `export_directory` preference is the location where the extension will attempt to save such exports.
|
||||
|
||||
:::
|
||||
|
||||
## 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:
|
||||
|
||||
```console
|
||||
id: ... # UUID Tag
|
||||
results: ... # Serializable results.
|
||||
provider: ... # Provider name.
|
||||
warnings: ... # List of warnings.
|
||||
chart: ... # Chart object.
|
||||
extra: ... # Extra info.
|
||||
```
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
|
||||
data = obb.equity.price.historical("SPY", provider="polygon")
|
||||
|
||||
data
|
||||
```
|
||||
|
||||
```console
|
||||
OBBject
|
||||
|
||||
id: 06520558-d54a-7e53-8000-7aafc8a42694
|
||||
results: [{'date': datetime.datetime(2022, 10, 5, 0, 0), 'open': 375.62, 'high': 37...
|
||||
provider: polygon
|
||||
warnings: None
|
||||
chart: None
|
||||
extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'polygon'}, 'st...
|
||||
```
|
||||
|
||||
Additional class methods are helpers for converting the results to a variety of formats.
|
||||
|
||||
- `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.
|
||||
|
||||
The output from the Fast API is a serialized version of this object, and these methods are lost on conversion. OBBject can be reconstructed to recover the helpers by importing the model and validating the data.
|
||||
|
||||
```python
|
||||
import requests
|
||||
from openbb_core.app.model.obbject import OBBject
|
||||
|
||||
data = []
|
||||
symbol="SPY"
|
||||
url = f"http://127.0.0.1:8000/api/v1/equity/price/historical?provider=polygon&symbol={symbol}"
|
||||
headers = {"accept": "application/json"}
|
||||
|
||||
response = requests.get(url, headers=headers, timeout=3)
|
||||
|
||||
if response.status_code == 200:
|
||||
data = OBBject.model_validate(response.json())
|
||||
|
||||
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.
|
||||
|
||||
```python
|
||||
from openbb_core.app.command_runner import CommandRunner
|
||||
runner = CommandRunner()
|
||||
output = runner.run(
|
||||
"/equity/fundamental/ratios",
|
||||
provider_choices={
|
||||
"provider": "fmp",
|
||||
},
|
||||
standard_params={
|
||||
"symbol" : "TSLA",
|
||||
"period" : "quarter",
|
||||
},
|
||||
extra_params={}
|
||||
)
|
||||
```
|
||||
|
||||
```console
|
||||
>>> output
|
||||
OBBject
|
||||
|
||||
id: 065241b7-bd9d-7313-8000-9406d8afab75
|
||||
results: [{'symbol': 'TSLA', 'date': '2023-06-30', 'period': 'Q2', 'current_ratio':...
|
||||
provider: fmp
|
||||
warnings: None
|
||||
chart: None
|
||||
extra: {'metadata': {'arguments': {'provider_choices': {'provider': 'fmp'}, 'standa...
|
||||
```
|
||||
|
||||
## Commands and Provider Coverage
|
||||
|
||||
The installed commands and data providers are found under, `obb.coverage`.
|
||||
|
||||
```python
|
||||
obb.coverage
|
||||
```
|
||||
|
||||
```console
|
||||
/coverage
|
||||
providers
|
||||
commands
|
||||
```
|
||||
|
||||
`obb.coverage.providers` is a dictionary of the installed provider extensions, each with its own list of available commands.
|
||||
|
||||
`obb.coverage.commands` is a dictionary of commands, each with its own list of available providers for the data.
|
||||
|
||||
## Logging Out
|
||||
|
||||
Logging out and saving changes to preferences is done in the account module.
|
||||
|
||||
```python
|
||||
obb.account.save()
|
||||
obb.account.logout()
|
||||
```
|
||||
|
||||
Any saved changes will be pulled to a new session after logging in. Ending the Python session will be an equivalent to logging out, if `remember_me=False`.
|
||||
- [Authorization and API Keys](usage/api_keys)
|
||||
- [Launching the REST API](usage/rest_api)
|
||||
- [User Settings and Environment Variables](usage/settings_and_environment_variables)
|
||||
- [Basic Response](usage/basic_response)
|
||||
- [Basic Syntax](usage/basic_syntax)
|
||||
- [Explanations](usage/explanation)
|
||||
|
||||
2
website/content/platform/usage/rest_api.md
vendored
2
website/content/platform/usage/rest_api.md
vendored
@@ -52,7 +52,7 @@ The API Docs provide interactive descriptions of all available endpoints that yo
|
||||
|
||||
## Data API Keys
|
||||
|
||||
The API keys to your data providers are loaded from the `~/.openbb_platform/user_settings.json` file. You can find more information about the structure of the file and environment variables in the [Local Environment](/platform/usage#local-environment) section.
|
||||
The API keys to your data providers are loaded from the `~/.openbb_platform/user_settings.json` file. You can find more information about the structure of the file and environment variables in the [Local Environment](api_keys#local-environment) section.
|
||||
|
||||
## API Authorization
|
||||
|
||||
|
||||
105
website/content/platform/usage/settings_and_environment_variables.md
vendored
Normal file
105
website/content/platform/usage/settings_and_environment_variables.md
vendored
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
title: User Settings & Environment Variables
|
||||
sidebar_position: 3
|
||||
description: This section details configuring the OpenBB Platform settings and environment variables.
|
||||
keywords:
|
||||
- OpenBB Platform
|
||||
- Python client
|
||||
- getting started
|
||||
- OpenBB Hub
|
||||
- local environment
|
||||
- environment variables
|
||||
---
|
||||
|
||||
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
|
||||
|
||||
<HeadTitle title="User Settings & Environment Variables - Usage | OpenBB Platform Docs" />
|
||||
|
||||
This page outlines configuring the OpenBB Platform with user settings and environment variables.
|
||||
|
||||
## User Settings
|
||||
|
||||
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, it will be created on the first run.
|
||||
|
||||
| **Preference** | **Default** | **Options** | **Description** |
|
||||
|-----------------------|----------------------------------|------------------------|---------------|
|
||||
| data_directory | /home/OpenBBUserData | Any path. | When launching the application for the first time this directory will be created. It serves as the default location where the application stores usage artifacts such as logs and exports. |
|
||||
| export_directory | /home/OpenBBUserData/exports | Any path. | The OpenBB Charting Extension provides the capability to export images in various formats. This is the directory where it attempts to save such exports. |
|
||||
| cache_directory | /home/OpenBBUserData/cache | Any path. | The directory where http requests and database caches are stored, for functions with caching. |
|
||||
| user_styles_directory | /home/OpenBBUserData/styles/user | Any path. | The OpenBB Charting Extension supports custom stylization. This directory is the location where it looks for user-defined styles. If no user styles are found in this directory the application will proceed with the default styles. |
|
||||
| charting_extension | openbb_charting | ["openbb_charting"] | Name of the charting extension to be used with the application. |
|
||||
| chart_style | dark | ["dark", "light"] | The default color style to use with the OpenBB Charting Extension plots. Options include "dark" and "light". |
|
||||
| plot_enable_pywry | True | [True, False] | Whether the application should enable PyWry. If PyWry is disabled the image will open in your default browser otherwise it will be displayed within your editor or in a separate PyWry window. |
|
||||
| plot_pywry_width | 1400 | Any positive integer. | PyWry window width. |
|
||||
| plot_pywry_height | 762 | Any positive integer. | PyWry window height. |
|
||||
| plot_open_export | False | [True, False] | Controls whether the "Save As" window should pop up as soon as the image is displayed." |
|
||||
| table_style | dark | ["dark", "light"] | "The default color style to use with the OpenBB Charting Extension tables. Options are "dark" and "light"" |
|
||||
| request_timeout | 15 | Any positive integer. | Specifies the timeout duration for HTTP requests. |
|
||||
| metadata | True | [True, False] | Enables or disables the collection of metadata which provides information about operations including arguments duration route and timestamp. Disabling this feature may improve performance in cases where contextual information is not needed or when the additional computation time and storage space are a concern. |
|
||||
| output_type | OBBject | ["OBBject", "dataframe", "numpy", "dict", "chart", "polars"] | Specifies the type of data the application will output when a command or endpoint is accessed. Note that choosing data formats only available in Python such as `dataframe`, `numpy` or `polars` will render the application's API non-functional. |
|
||||
| show_warnings | True | [True, False] | Enables or disables the display of warnings. |
|
||||
|
||||
### Notes on Preferences
|
||||
|
||||
:::note
|
||||
|
||||
- If a `OpenBBUserData` folder in not in the home directory, the application will create one on first run. The user preferences with paths all default to this folder, be it exports, styles or data - this can be changed at any time to suit.
|
||||
- The `OpenBBUserData` will still be created even if preferences are not pointing to it, this is because the application needs a place to store logs and other artifacts.
|
||||
- One way to export files or images from the OpenBB Platform is to leverage that functionality from the OpenBB Charting Extension. The `export_directory` preference is the location where the extension will attempt to save CSV and image files.
|
||||
:::
|
||||
|
||||
```json
|
||||
{
|
||||
"preferences": {
|
||||
"data_directory": "~/OpenBBUserData",
|
||||
"export_directory": "~/OpenBBUserData/exports",
|
||||
"cache_directory": "~/OpenBBUserData/cache",
|
||||
"user_styles_directory": "~/OpenBBUserData/styles/user",
|
||||
"charting_extension": "openbb_charting",
|
||||
"chart_style": "dark",
|
||||
"plot_enable_pywry": true,
|
||||
"plot_pywry_width": 1400,
|
||||
"plot_pywry_height": 762,
|
||||
"plot_open_export": false,
|
||||
"table_style": "dark",
|
||||
"request_timeout": 15,
|
||||
"metadata": true,
|
||||
"output_type": "OBBject"
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
- `OPENBB_DEBUG_MODE`: enables verbosity while running the program
|
||||
- `OPENBB_DEVELOP_MODE`: points hub service to .co or .dev
|
||||
- `OPENBB_AUTO_BUILD`: enables automatic SDK package build on import
|
||||
- `OPENBB_CHARTING_EXTENSION`: specifies which charting extension to use
|
||||
- `OPENBB_API_AUTH_EXTENSION`: specifies which authentication extension to use
|
||||
- `OPENBB_API_AUTH`: enables API authentication for command endpoints
|
||||
- `OPENBB_API_USERNAME`: sets API username
|
||||
- `OPENBB_API_PASSWORD`: sets API password
|
||||
|
||||
Variables can be defined for current session only.
|
||||
|
||||
```python
|
||||
import os
|
||||
os.environ["OPENBB_DEBUG_MODE"] = "True"
|
||||
from openbb import obb
|
||||
```
|
||||
|
||||
### Proxy Networks
|
||||
|
||||
An environment variable can be set, in the `.env` file, to direct the Requests library to a specific address and port.
|
||||
|
||||
```env
|
||||
HTTP_PROXY="<ADDRESS>" or HTTPS_PROXY="<ADDRESS>”
|
||||
```
|
||||
|
||||
For example:
|
||||
|
||||
```env
|
||||
HTTP_PROXY="http://10.10.10.10:8000"
|
||||
```
|
||||
303
website/content/terminal/installation/pypi.md
vendored
303
website/content/terminal/installation/pypi.md
vendored
@@ -1,303 +0,0 @@
|
||||
---
|
||||
title: PyPI
|
||||
sidebar_position: 4
|
||||
description: This page provides a comprehensive guide on how to install OpenBB Terminal
|
||||
and SDK from PyPI across multiple operating system platforms. It lists all required
|
||||
software and provides how-to steps to prepare the virtual environment, install the
|
||||
main package and its toolkits, verify the installation, and upgrade to the latest
|
||||
or nightly build versions.
|
||||
keywords:
|
||||
- OpenBB Terminal installation
|
||||
- OpenBB SDK installation
|
||||
- PyPI installation guide
|
||||
- how to install OpenBB Terminal
|
||||
- how to install OpenBB SDK
|
||||
- software requirements for OpenBB installation
|
||||
- preparing virtual environment for OpenBB
|
||||
- installing OpenBB toolkits
|
||||
- verifying OpenBB installation
|
||||
- updating OpenBB SDK
|
||||
- OpenBB nightly builds
|
||||
---
|
||||
|
||||
import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
|
||||
|
||||
<HeadTitle title="PyPI - Installation | OpenBB Terminal Docs" />
|
||||
|
||||
<!-- markdownlint-disable MD012 MD031 MD033 -->
|
||||
|
||||
This section provides steps to install the OpenBB Terminal and SDK from PyPI. This installation type supports Windows, macOS and Linux systems. **Before starting the installation process, make sure the following pieces of software are installed.**
|
||||
|
||||
:::warning
|
||||
The instructons on this page are for installing the OpenBB Terminal from PyPI, which uses a legacy version of the Python SDK. If you do not wish to install the OpenBB Terminal application, please refer to the installation instructions [here](/platform/installation)
|
||||
:::
|
||||
|
||||
<details><summary>Miniconda</summary>
|
||||
Miniconda is a Python environment and package manager. It is required for installing certain dependencies.
|
||||
|
||||
Go [here](https://docs.conda.io/en/latest/miniconda.html#latest-miniconda-installer-links) to find the download for your operating system or use the links below:
|
||||
|
||||
- Apple-Silicon Systems: [Miniconda for MacOS](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.pkg)
|
||||
- Intel-based Mac Systems: [Miniconda for MacOS](https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh)
|
||||
- Linux and WSL Systems: [Miniconda for Linux](https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh)
|
||||
- Raspberry PI Systems: [Miniconda for Raspberry PI](https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh)
|
||||
- Windows Systems: [Miniconda for Windows](https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe)
|
||||
|
||||
To verify if Miniconda is installed on the system, open the command line and run the following command:
|
||||
|
||||
```shell
|
||||
conda --version
|
||||
```
|
||||
|
||||
If Miniconda is installed, a version number will be displayed, for example:
|
||||
|
||||
```shell
|
||||
conda 23.1.0
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>Git</summary>
|
||||
|
||||
Check to verify if Git is installed by running the following command:
|
||||
|
||||
```shell
|
||||
git --version
|
||||
```
|
||||
|
||||
Which will print something like this:
|
||||
|
||||
```shell
|
||||
git version 2.31.1
|
||||
```
|
||||
|
||||
If Git is not installed, install it now from `conda` by running:
|
||||
|
||||
```shell
|
||||
conda install -c anaconda git
|
||||
```
|
||||
|
||||
Or follow the instructions [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to install it.
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>Microsoft C++ Build Tools (Windows only)</summary>
|
||||
|
||||
Use the instructions [here](https://visualstudio.microsoft.com/visual-cpp-build-tools/) to install or update Microsoft C++ Build Tools.
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>Rosetta2 (Apple Silicon only)</summary>
|
||||
|
||||
Install Rosetta from the terminal with:
|
||||
```shell
|
||||
softwareupdate --install-rosetta
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>LibOMP (Apple Silicon only)</summary>
|
||||
|
||||
Apple Silicon does not ship `libomp` by default. It will need to be installed manually for some features of the ML toolkit to work. The `libomp` library can be installed from [homebrew](https://brew.sh/).
|
||||
|
||||
Check if Homebrew is installed by running the following command:
|
||||
|
||||
```shell
|
||||
brew --version
|
||||
```
|
||||
|
||||
If Homebrew is not installed, install it by running:
|
||||
|
||||
```shell
|
||||
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
||||
```
|
||||
|
||||
Or follow the instructions [here](https://brew.sh/).
|
||||
|
||||
To install LibOMP, run the following command:
|
||||
|
||||
```shell
|
||||
brew install libomp
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>VcXsrv (Windows Subsystem for Linux only)</summary>
|
||||
|
||||
Since a WSL installation is headless by default (i.e., there is only access to a terminal running a Linux distribution) there are additional steps required to display visualizations. A more detailed tutorial is found, [here](https://medium.com/@shaoyenyu/make-matplotlib-works-correctly-with-x-server-in-wsl2-9d9928b4e36a).
|
||||
|
||||
- Dynamically export the DISPLAY environment variable in WSL2:
|
||||
|
||||
```shell
|
||||
# add to the end of ~/.bashrc file
|
||||
export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0
|
||||
# source the file
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
- Download and install [VcXsrv](https://sourceforge.net/projects/vcxsrv/)
|
||||
- When running the program is important to check "Disable access control"
|
||||
|
||||
After this, `VcXsrv` should be running successfully, and the machine is ready to proceed with the terminal installation.
|
||||
|
||||
Alternatives to `VcXsrv` include:
|
||||
|
||||
- [GWSL](https://opticos.github.io/gwsl/)
|
||||
- [Xming](https://xming.en.softonic.com/)
|
||||
- [Wayland](https://wayland.freedesktop.org/docs/html/)
|
||||
|
||||
</details>
|
||||
|
||||
<details><summary>GTK toolchains (Linux only)</summary>
|
||||
|
||||
GTK is a window extension that is used to display interactive charts and tables. The library responsible for interactive charts and tables (`pywry`) requires certain dependencies, based on the Linux distribution, to be installed first.
|
||||
|
||||
<details>
|
||||
<summary>Debian-based / Ubuntu / Mint</summary>
|
||||
|
||||
```shell
|
||||
sudo apt install libwebkit2gtk-4.0-dev
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Arch Linux / Manjaro</summary>
|
||||
|
||||
```shell
|
||||
sudo pacman -S webkit2gtk
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Fedora</summary>
|
||||
|
||||
```shell
|
||||
sudo dnf install gtk3-devel webkit2gtk3-devel
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
</details>
|
||||
|
||||
Proceed to next steps once the requirements above have been met.
|
||||
|
||||
## Prepare the Virtual Environment
|
||||
|
||||
Create the environment using a configuration file from the OpenBB Terminal repository.
|
||||
|
||||
Copy and paste these commands into the terminal/command prompt:
|
||||
|
||||
```shell
|
||||
conda env create -n obb --file https://raw.githubusercontent.com/OpenBB-finance/OpenBBTerminal/main/build/conda/conda-3-9-env.yaml
|
||||
```
|
||||
|
||||
:::note
|
||||
Additional `YAML` files provide support for Python versions 3.8 and 3.10. Substitute the `9`, in the command above, with the desired version.
|
||||
:::
|
||||
|
||||
Agree to the prompts if there are any.
|
||||
|
||||
After the obb environment is created, activate it by entering:
|
||||
|
||||
```shell
|
||||
conda activate obb
|
||||
```
|
||||
|
||||
## Install the OpenBB Terminal and SDK
|
||||
|
||||
Make sure to have completed all previous steps. If followed, there will be a virtual environment, named `obb`, and this environment is activated.
|
||||
|
||||
Install the main package of Openbb SDK with `pip`, a package manager.
|
||||
|
||||
```shell
|
||||
pip install openbb==3.2.5 --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.
|
||||
|
||||
The toolkits can be installed individually with:
|
||||
|
||||
```shell
|
||||
pip install "openbb[optimization]==5" --no-cache-dir
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```shell
|
||||
pip install "openbb[forecast]==3.2.5" --no-cache-dir
|
||||
```
|
||||
|
||||
Install all available toolkits at once with:
|
||||
|
||||
```shell
|
||||
pip install "openbb[all]==3.2.5" --no-cache-dir
|
||||
```
|
||||
|
||||
:::info
|
||||
`pip install openbb[all]==3.2.5` 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
|
||||
|
||||
Once this installation process is completed, the terminal is launched by running:
|
||||
|
||||
```shell
|
||||
openbb
|
||||
```
|
||||
|
||||
To confirm the installation of the SDK, open the Python interpreter with a `python` command, then run the following:
|
||||
|
||||
```python
|
||||
from openbb_terminal.sdk import openbb
|
||||
openbb.__version__
|
||||
```
|
||||
|
||||
You should see the version number displayed, for example:
|
||||
|
||||
```console
|
||||
'3.0.1'
|
||||
```
|
||||
|
||||
That's it!
|
||||
|
||||
**NOTE:** When the OpenBB Terminal is opened next, the Python environment will need to be activated again. When using a code editor, make sure that the correct environment is selected. This should be easy to figure out if there is an error stating that there are missing packages. To launch the OpenBB Terminal application in a new terminal window, first navigate into the folder where the source code was cloned, and then use the following two commands:
|
||||
|
||||
```shell
|
||||
conda activate obb
|
||||
openbb
|
||||
```
|
||||
|
||||
## Updating the OpenBB SDK Version
|
||||
|
||||
Upgrade the OpenBB SDK to the latest version via `pypi`. When using the terminal or SDK without toolkits, first activate environment by running:
|
||||
|
||||
```shell
|
||||
conda activate obb
|
||||
```
|
||||
|
||||
and then update the package by running:
|
||||
|
||||
```shell
|
||||
pip install -U openbb --no-cache-dir
|
||||
```
|
||||
|
||||
When using an installation with toolkits, with the virtual environment activated, enter:
|
||||
|
||||
```shell
|
||||
pip install -U "openbb[all]" --no-cache-dir
|
||||
```
|
||||
|
||||
## Nightly Builds
|
||||
|
||||
OpenBB SDK is updated daily with new features and bug fixes, but some features being worked on may be unstable. To use the same SDK version as the development team, install the nightly build with:
|
||||
|
||||
```shell
|
||||
conda activate obb
|
||||
pip install -U openbb-terminal-nightly --no-cache-dir
|
||||
```
|
||||
|
||||
:::info
|
||||
If issues are encountered with the installation, please try installing OpenBB Terminal and SDK from source [(link)](/terminal/installation/source), or reach out to our [Discord](https://discord.gg/Up2QGbMKHY) community for help.
|
||||
:::
|
||||
Reference in New Issue
Block a user