mirror of
https://github.com/OpenBB-finance/OpenBB.git
synced 2026-11-08 02:11:44 +00:00
Update readme (#5449)
* update readme * typos * installation * keys * example * minor fix * api keys * eg * Update CONTRIBUTING.md * openbb hub * minor adjustments --------- Co-authored-by: hjoaquim <h.joaquim@campus.fct.unl.pt>
This commit is contained in:
montezdesousa
39
openbb_sdk/CONTRIBUTING.md
vendored
39
openbb_sdk/CONTRIBUTING.md
vendored
@@ -25,6 +25,9 @@
|
||||
- [Add a visualization to an existing SDK command](#add-a-visualization-to-an-existing-sdk-command)
|
||||
- [Using the `to_chart` OBBject method](#using-the-to_chart-obbject-method)
|
||||
- [Environment and dependencies](#environment-and-dependencies)
|
||||
- [Python package](#python-package)
|
||||
- [Overview](#overview)
|
||||
- [Import time](#import-time)
|
||||
|
||||
## Get started contributing with a template
|
||||
|
||||
@@ -475,3 +478,39 @@ Run `./install_all.sh` for Linux/mac or `install_all.bat` for Windows.
|
||||
</details>
|
||||
|
||||
> In order to install any other custom extension or provider, you'd follow the exact same steps as above.
|
||||
|
||||
## Python package
|
||||
|
||||
### Overview
|
||||
|
||||
One of the interfaces 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.
|
||||
|
||||
When the user runs `import openbb`, `from openbb import sdk` or other variants, the
|
||||
script that generates the package code is triggered. It detects if there are new openbb
|
||||
extensions installed in the environment and rebuilds the package code accordingly. If
|
||||
new extensions are not found it just uses the current package version.
|
||||
|
||||
When you are developing chances are you want to manually trigger the package rebuild.
|
||||
You can do that with:
|
||||
|
||||
```python
|
||||
python -c "import openbb; openbb.build()"
|
||||
```
|
||||
|
||||
### Import time
|
||||
|
||||
We aim to have a short import time for the package. To measure that we use `tuna`.
|
||||
|
||||
- https://pypi.org/project/tuna/
|
||||
|
||||
To visualize the import time breakdown by module and find potential bottlenecks, run the
|
||||
following commands from `openbb_sdk` directory:
|
||||
|
||||
```bash
|
||||
pip install tuna
|
||||
python -X importtime openbb/__init__.py 2> import.log
|
||||
tuna import.log
|
||||
```
|
||||
|
||||
190
openbb_sdk/README.md
vendored
190
openbb_sdk/README.md
vendored
@@ -1,56 +1,88 @@
|
||||
# Table of contents
|
||||
[](https://pepy.tech/project/openbb)
|
||||
[](https://github.com/OpenBB-finance/OpenBBTerminal)
|
||||
|
||||
- [Table of contents](#table-of-contents)
|
||||
- [Pre-requisites](#pre-requisites)
|
||||
- [Installation](#installation)
|
||||
- [API keys](#api-keys)
|
||||
- [1. From local file](#1-from-local-file)
|
||||
- [2. From runtime](#2-from-runtime)
|
||||
- [3. From OpenBB Hub](#3-from-openbb-hub)
|
||||
- [Python Usage](#python-usage)
|
||||
- [API Usage](#api-usage)
|
||||
- [Docker](#docker)
|
||||
- [Development](#development)
|
||||
- [Import time](#import-time)
|
||||
| OpenBB is committed to build the future of investment research by focusing on an open source infrastructure accessible to everyone, everywhere. |
|
||||
|:--:|
|
||||
|  |
|
||||
| Check our website at [openbb.co](www.openbb.co) |
|
||||
|
||||
## Pre-requisites
|
||||
|
||||
To install and use the SDK you need:
|
||||
## OpenBB Platform Overview
|
||||
|
||||
- A fresh virtual environment
|
||||
- Python 3.8 or higher
|
||||
- API keys for the APIs you want to use
|
||||
The OpenBB Platform provides a convenient way to access raw financial data from multiple data providers. The package comes with a ready to use REST API. This allows developers from any language to easily create applications on top of OpenBB Platform.
|
||||
|
||||
For development you need:
|
||||
|
||||
- Poetry 1.5.1 or higher
|
||||
- ruff 0.0.256
|
||||
- mypy 1.4.1
|
||||
- black
|
||||
|
||||
## Installation
|
||||
|
||||
To install the SDK in a virtual environment from the repo root run:
|
||||
The command below provides access to the core functionalities behind the [OpenBB Platform](https://my.openbb.co/app/sdk).
|
||||
|
||||
```bash
|
||||
pip install ./openbb_sdk
|
||||
pip install openbb
|
||||
```
|
||||
|
||||
This will install the SDK and all its dependencies into the site-packages directory of the virtual environment.
|
||||
To install extensions that expand the core functionalities specify the extension name or use `all` to install all.
|
||||
|
||||
```bash
|
||||
# Install single extension, e.g. openbb-charting
|
||||
pip install openbb[charting]
|
||||
|
||||
# Install all available extensions
|
||||
pip install openbb[all]
|
||||
``````
|
||||
|
||||
> Note: While we are in pre-release mode you need to specify the version, e.g. `pip install openbb==4.0.0a0` or `pip install openbb[all]==4.0.0a0`
|
||||
|
||||
## Python
|
||||
|
||||
```python
|
||||
>>> from openbb import obb
|
||||
>>> output = obb.stocks.load("AAPL")
|
||||
>>> df = output.to_dataframe()
|
||||
>>> df.head()
|
||||
open high low ... change_percent label change_over_time
|
||||
date ...
|
||||
2022-09-19 149.31 154.56 149.10 ... 3.46000 September 19, 22 0.034600
|
||||
2022-09-20 153.40 158.08 153.08 ... 2.28000 September 20, 22 0.022800
|
||||
2022-09-21 157.34 158.74 153.60 ... -2.30000 September 21, 22 -0.023000
|
||||
2022-09-22 152.38 154.47 150.91 ... 0.23625 September 22, 22 0.002363
|
||||
2022-09-23 151.19 151.47 148.56 ... -0.50268 September 23, 22 -0.005027
|
||||
|
||||
[5 rows x 12 columns]
|
||||
```
|
||||
|
||||
## API keys
|
||||
|
||||
To use your API keys you need to configure them. Here are the 3 options on how to do it:
|
||||
To fully leverage the OpenBB Platform you need to get some API keys to connect with data providers. Here are the 3 options on where to set them:
|
||||
|
||||
1. From local file
|
||||
2. At runtime
|
||||
3. From OpenBB Hub
|
||||
1. OpenBB Hub
|
||||
2. Runtime
|
||||
3. Local file
|
||||
|
||||
### 1. From local file
|
||||
### 1. OpenBB Hub
|
||||
|
||||
You can specify the keys in the `~/.openbb_sdk/user_settings.json` file.
|
||||
Set your keys at [OpenBB Hub](https://my.openbb.co/app/sdk/api-keys) and get your personal access token from https://my.openbb.co/app/sdk/pat to connect with your account.
|
||||
|
||||
Create this file using the following template and replace the values with your keys:
|
||||
```python
|
||||
>>> from openbb import obb
|
||||
>>> openbb.account.login(pat="OPENBB_PAT")
|
||||
```
|
||||
|
||||
### 2. Runtime
|
||||
|
||||
```python
|
||||
>>> from openbb import obb
|
||||
>>> obb.user.credentials.fmp_api_key = "REPLACE_ME"
|
||||
>>> obb.user.credentials.polygon_api_key = "REPLACE_ME"
|
||||
|
||||
>>> # Persist changes in ~/.openbb_sdk/user_settings.json
|
||||
>>> obb.account.save()
|
||||
```
|
||||
|
||||
### 3. Local file
|
||||
|
||||
You can specify the keys directly in the `~/.openbb_sdk/user_settings.json` file.
|
||||
|
||||
Populate this file with the following template and replace the values with your keys:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -63,94 +95,12 @@ Create this file using the following template and replace the values with your k
|
||||
}
|
||||
```
|
||||
|
||||
### 2. From runtime
|
||||
## REST API
|
||||
|
||||
You can also specify your keys at runtime:
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
obb.user.credentials.fmp_api_key = "REPLACE_ME"
|
||||
obb.user.credentials.polygon_api_key = "REPLACE_ME"
|
||||
```
|
||||
|
||||
### 3. From OpenBB Hub
|
||||
|
||||
You can also load your the keys from the OpenBB Hub.
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
openbb.account.login(username="REPLACE_ME", password="REPLACE_ME")
|
||||
```
|
||||
|
||||
## Python Usage
|
||||
|
||||
Import and basic usage:
|
||||
|
||||
```python
|
||||
from openbb import obb
|
||||
aapl = obb.stocks.load("AAPL")
|
||||
df = aapl.to_dataframe()
|
||||
df.head()
|
||||
```
|
||||
|
||||
## API Usage
|
||||
|
||||
Launch the API with:
|
||||
The OpenBB Platform comes with a ready to use REST API built with FastAPI. Start the application using this command:
|
||||
|
||||
```bash
|
||||
uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload
|
||||
uvicorn openbb_core.api.rest_api:app
|
||||
```
|
||||
|
||||
Navigate to <http://0.0.0.0:8000/docs> to see the swagger API documentation.
|
||||
|
||||
Authorize with the developer credentials: openbb/openbb
|
||||
|
||||
## Docker
|
||||
|
||||
You can use the API through Docker.
|
||||
|
||||
To build the image, from the repo root run:
|
||||
|
||||
```bash
|
||||
docker build -f build/docker/api.dockerfile -t openbb-sdk:latest .
|
||||
```
|
||||
|
||||
To run this newly-built image:
|
||||
|
||||
```bash
|
||||
docker run --rm -p8000:8000 -v ~/.openbb_sdk:/root/.openbb_sdk openbb-sdk:latest
|
||||
```
|
||||
|
||||
This will mount the local `~/.openbb_sdk` directory into the Docker container so you can use the API keys from there and it will expose the API on port `8000`.
|
||||
|
||||
## Development
|
||||
|
||||
From the root of the OpenBB Terminal repo, run:
|
||||
|
||||
`poetry install -C ./openbb_sdk`
|
||||
|
||||
When developing a specific extension `cd` into the extension directory and run:
|
||||
|
||||
`pip install -U -e .`
|
||||
|
||||
While we're still developing, it is often required to reinstall extensions:
|
||||
|
||||
```python
|
||||
python -c "import openbb; openbb.build()"
|
||||
```
|
||||
|
||||
You need to do this every time you install or uninstall a new extension or to reinstall all extensions.
|
||||
|
||||
### Import time
|
||||
|
||||
We aim to have a short import time. To measure that we use `tuna`.
|
||||
|
||||
- https://pypi.org/project/tuna/
|
||||
|
||||
To visualize the import time breakdown by module, run the following commands from `openbb_sdk` directory:
|
||||
|
||||
```bash
|
||||
pip install tuna
|
||||
python -X importtime openbb/__init__.py 2> import.log
|
||||
tuna import.log
|
||||
```
|
||||
Check `openbb-core` [README](https://pypi.org/project/openbb-core/) for additional info.
|
||||
|
||||
53
openbb_sdk/sdk/core/README.md
vendored
53
openbb_sdk/sdk/core/README.md
vendored
@@ -24,7 +24,8 @@
|
||||
- [4.2 Dynamic version](#42-dynamic-version)
|
||||
- [5. REST API](#5-rest-api)
|
||||
- [5.1 HTTPS](#51-https)
|
||||
- [5.2 Test users](#52-test-users)
|
||||
- [5.2 Docker](#52-docker)
|
||||
- [5.3 Test users](#53-test-users)
|
||||
- [6. Front-end typing](#6-front-end-typing)
|
||||
|
||||
## 1. Introduction
|
||||
@@ -146,7 +147,7 @@ Update your system settings by modifying the `.openbb_sdk/system_settings.json`
|
||||
|
||||
```{json}
|
||||
{
|
||||
"dbms_uri": null
|
||||
"test_mode": true
|
||||
}
|
||||
```
|
||||
|
||||
@@ -162,7 +163,7 @@ output = obb.stocks.load(
|
||||
start_date="2023-01-01",
|
||||
provider="fmp",
|
||||
chart=True
|
||||
)
|
||||
)
|
||||
```
|
||||
|
||||
### 4.1.1. OBBject
|
||||
@@ -368,18 +369,18 @@ In fact, the static version makes use of this feature to run each command. Take
|
||||
>>> from openbb_core.app.command_runner import CommandRunner
|
||||
>>> runner = CommandRunner()
|
||||
>>> output = runner.run(
|
||||
"/stocks/load",
|
||||
provider_choices={
|
||||
"provider": "fmp",
|
||||
},
|
||||
standard_params={
|
||||
"symbol": "TSLA",
|
||||
"start_date": "2023-07-01",
|
||||
"end_date": "2023-07-25",
|
||||
},
|
||||
extra_params={},
|
||||
chart=True,
|
||||
)
|
||||
"/stocks/load",
|
||||
provider_choices={
|
||||
"provider": "fmp",
|
||||
},
|
||||
standard_params={
|
||||
"symbol": "TSLA",
|
||||
"start_date": "2023-07-01",
|
||||
"end_date": "2023-07-25",
|
||||
},
|
||||
extra_params={},
|
||||
chart=True,
|
||||
)
|
||||
>>> output
|
||||
OBBject
|
||||
|
||||
@@ -438,7 +439,27 @@ If you want to run your FastAPI app over HTTPS locally you can use [mkcert](http
|
||||
|
||||
Your app will be available at https://127.0.0.1:8000/
|
||||
|
||||
### 5.2 Test users
|
||||
### 5.2 Docker
|
||||
|
||||
You can use the API through Docker.
|
||||
|
||||
We provide a `.dockerfile`` in OpenBB [repo](https://github.com/OpenBB-finance/OpenBBTerminal).
|
||||
|
||||
To build the image, you can run the following command from the repo root:
|
||||
|
||||
```bash
|
||||
docker build -f build/docker/api.dockerfile -t openbb-sdk:latest .
|
||||
```
|
||||
|
||||
To run this newly-built image:
|
||||
|
||||
```bash
|
||||
docker run --rm -p 8000:8000 -v ~/.openbb_sdk:/root/.openbb_sdk openbb-sdk:latest
|
||||
```
|
||||
|
||||
This will mount the local `~/.openbb_sdk` directory into the Docker container so you can use the API keys from there and it will expose the API on port `8000`.
|
||||
|
||||
### 5.3 Test users
|
||||
|
||||
There are 2 default users for testing purpose:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user