Next release : reports on steroids

.github/workflows/test.yml

@@ -32,7 +32,7 @@ jobs:
       - run: pip install types-pytz types-requests types-termcolor types-tabulate types-PyYAML types-python-dateutil types-setuptools types-six
       - run: bandit -x ./tests -r . || true
       - run: black --diff --check .
-      - run: codespell --ignore-words-list=commun,ro,zar,zlot,ba,buil,coo,ether,hist,hsi,mape,navagation,operatio,pres,ser,yeld,shold,ist,varian,datas,ake,creat,vie,hel --quiet-level=2 --skip=./tests,.git,*.css,*.csv,*.html,*.ini,*.ipynb,*.js,*.json,*.lock,*.scss,*.txt,*.yaml,./build/pyinstaller
+      - run: codespell --ignore-words-list=commun,statics,ro,zar,zlot,ba,buil,coo,ether,hist,hsi,mape,navagation,operatio,pres,ser,yeld,shold,ist,varian,datas,ake,creat,vie,hel --quiet-level=2 --skip=./tests,.git,*.css,*.csv,*.html,*.ini,*.ipynb,*.js,*.json,*.lock,*.scss,*.txt,*.yaml,./build/pyinstaller
       - run: flake8 . --count --ignore=E203,W503 --max-line-length=122 --show-source --statistics --exclude ./build/pyinstaller
       - run: mypy --ignore-missing-imports --exclude="/setup\.py$" .
       - run: shopt -s globstar && pyupgrade --py38-plus **/*.py

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
         entry: codespell
         args:
           [
-            "--ignore-words-list=commun,ro,zar,vie,hel,zlot,ba,buil,coo,ether,hist,hsi,mape,navagation,operatio,pres,ser,yeld,shold,ist,varian,datas,ake,creat",
+            "--ignore-words-list=commun,ro,zar,vie,hel,zlot,ba,buil,coo,ether,hist,hsi,mape,navagation,operatio,pres,ser,yeld,shold,ist,varian,datas,ake,creat,statics",
             "--quiet-level=2",
             "--skip=./tests,.git,*.css,*.csv,*.html,*.ini,*.ipynb,*.js,*.json,*.lock,*.scss,*.txt,*.yaml,build/pyinstaller/*",
           ]

CONTRIBUTING.md

@@ -13,33 +13,35 @@ Use your best judgment, and feel free to propose changes to this document in a p
 
 [Development Process](#development-process)
 
-- [How Can I Contribute?](#how-can-i-contribute)
-  - [Community](#community)
-  - [Retail Trader](#retail-trader)
-  - [Software Developer](#software-developer)
-- [Development Process](#development-process)
-  - [Select Feature](#select-feature)
-- [Understand Code Structure](#understand-code-structure)
-- [Follow Coding Guidelines](#follow-coding-guidelines)
-  - [Model](#model)
-    - [View](#view)
-  - [Controller](#controller)
-- [Remember Coding Style](#remember-coding-style)
-  - [Naming Convention](#naming-convention)
-  - [Docstrings](#docstrings)
-  - [Linters](#linters)
-- [Write Code and Commit](#write-code-and-commit)
-  - [Pre Commit Hooks](#pre-commit-hooks)
-  - [Coding](#coding)
-  - [Git Process](#git-process)
-- [Add a Test](#add-a-test)
-  - [Pytest](#pytest)
-  - [Coverage](#coverage)
-  - [VCR](#vcr)
-- [Add Documentation](#add-documentation)
-- [Add support for a new language](#add-support-for-a-new-language)
-- [Open a Pull Request](#open-a-pull-request)
-- [Review Process](#review-process)
+- [CONTRIBUTING](#contributing)
+  - [How Can I Contribute?](#how-can-i-contribute)
+    - [Community](#community)
+    - [Retail Trader](#retail-trader)
+    - [Software Developer](#software-developer)
+  - [Development Process](#development-process)
+    - [Select Feature](#select-feature)
+  - [Understand Code Structure](#understand-code-structure)
+  - [Follow Coding Guidelines](#follow-coding-guidelines)
+    - [Model](#model)
+      - [View](#view)
+    - [Controller](#controller)
+    - [API](#api)
+  - [Remember Coding Style](#remember-coding-style)
+    - [Naming Convention](#naming-convention)
+    - [Docstrings](#docstrings)
+    - [Linters](#linters)
+  - [Write Code and Commit](#write-code-and-commit)
+    - [Pre Commit Hooks](#pre-commit-hooks)
+    - [Coding](#coding)
+    - [Git Process](#git-process)
+  - [Add a Test](#add-a-test)
+    - [Pytest](#pytest)
+    - [Coverage](#coverage)
+    - [VCR](#vcr)
+  - [Add Documentation](#add-documentation)
+  - [Add support for a new language](#add-support-for-a-new-language)
+  - [Open a Pull Request](#open-a-pull-request)
+  - [Review Process](#review-process)
 
 ## How Can I Contribute?
 
@@ -370,9 +372,52 @@ def call_shorted(self, other_args: List[str]):
             num_stocks=ns_parser.num,
             export=ns_parser.export,
         )
-
 ```
 
+### API
+
+In order to add a command to the API, follow these steps:
+
+1. Go to the `api.py` file and scroll to the `functions` dictionary, it should look like this:
+
+    ```python
+    functions = {
+        "stocks.get_news": {
+            "model": "openbb_terminal.common.newsapi_model.get_news",
+        },
+        "stocks.load": {
+            "model": "openbb_terminal.stocks.stocks_helper.load",
+        },
+        "stocks.candle": {
+            "model": "openbb_terminal.stocks.stocks_helper.load",
+            "view": "openbb_terminal.stocks.stocks_helper.display_candle",
+        },
+
+    ...
+    ```
+
+2. Add a new key to the dictionary, which corresponds to the way the added command shall be accessed from the api.
+This is called the `virtual path`. In this case it should be `stocks.dps.shorted`.
+3. Now it is time to add the value to the key. This key shall be another dictionary with a `model` key and possibly a
+`view` key.
+   1. The model keys value should be the path from project root to the new commands model function as a string. This
+   case it is `openbb_terminal.stocks.dark_pool_shorts.yahoofinance_model.get_most_shorted`.
+   2. If and **only if** the view function of the command **displays a chart**, then the `view` key and its value is
+   the view functions path from the project root as a string. In this example the view function of the only prints a
+   table and thus this step can be ignored.
+4. Done!!! The final new dictionary looks like this after the added example:
+
+    ```python
+    functions = {
+        ...
+
+        "stocks.dps.shorted": {
+            "model": "openbb_terminal.stocks.dark_pool_shorts.yahoofinance_model.get_most_shorted",
+        },
+
+        ...
+    ```
+
 ## Remember Coding Style
 
 When in doubt, follow <https://www.python.org/dev/peps/pep-0008/>.

openbb_terminal/API_README.md

@@ -0,0 +1,113 @@
+# OpenBB API
+
+## Usage
+
+The OpenBB API can simply be imported with:
+
+```python
+from openbb_terminal.api import openbb
+```
+
+This imports all the commands at once. Now you can directly begin to use it. The api function is structured
+in the way that it always retrieves the underlying data. For charts add the `chart=True` parameter.
+
+For example see:
+
+```python
+# Returns data:
+openbb.stocks.ba.snews("aapl")
+# Returns charts:
+openbb.stocks.ba.snews("aapl", chart=True)
+```
+
+This allows easy integration to the jupyter notebook and allows you to build new applications on top of the terminal.
+The api also has new functionalities that are used in the backend of the Terminal (CLI). With these backend functions
+you can develop new functionalities and avoid copy-pasting the code from the repository.
+
+**Note:**\
+API keys for data fetching still have to be entered
+
+### Jupyter Notebook Tricks
+
+**Get  matplotlib charts in the output cells**\
+If you copy-paste the code below and use it as your initialization then you're matplotlib graphs will be inside
+the result cell.
+
+```python
+import matplotlib.pyplot as plt
+import matplotlib_inline.backend_inline
+from openbb_terminal.api import openbb
+%matplotlib inline
+matplotlib_inline.backend_inline.set_matplotlib_formats("svg")
+```
+
+**Get function signature and docstring**\
+When you press `shift + tab` in jupyter notebook while having the mouse parser in an API function, you get the
+signature and docstring of the function.
+
+### Visual Studio Code Tricks
+
+**Get function docstring and signature**\
+In order to get the docstrings and function signatures for the API when opening a Jupyter Notebook in VSCode,
+you have to install the [Jupyter PowerToys
+extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.vscode-jupyter-powertoys).
+
+## Code Examples
+
+Just copy-paste the code examples below into a python script or jupyter notebook, and you're ready to go.
+
+**Basic Stock Information**\
+Prints general information about the selected stock (in this case Gamsetop)
+
+```python
+from openbb_terminal.api import openbb
+gme_info = openbb.stocks.fa.info("gme").transpose()
+print("-- Gamstop Stock --\n\n- Basic Info -")
+print(f"Sector: {gme_info['Sector'].iloc[0]}")
+print(f"Country: {gme_info['Country'].iloc[0]}")
+print(f"Description: {gme_info['Long business summary'].iloc[0]}")
+print("\n- Financial Info -")
+print(f"Ebitda Margins: {gme_info['Ebitda margins'].iloc[0]}")
+print(f"Profit Margins: {gme_info['Profit margins'].iloc[0]}")
+print(f"Revenue growth: {gme_info['Revenue growth'].iloc[0]}")
+print("\n- Target Price -")
+print(f"Current price: {gme_info['Current price'].iloc[0]}")
+print(f"Target mean price: {gme_info['Target mean price'].iloc[0]}")
+print(f"Target high price: {gme_info['Target high price'].iloc[0]}")
+print(f"Target low price: {gme_info['Target low price'].iloc[0]}")
+```
+
+**Use external axis**\
+The code below utilises the `external_axes` parameter to get two axis in one chart
+
+```python
+import matplotlib.pyplot as plt
+from openbb_terminal.api import openbb
+fig, (ax1, ax2) = plt.subplots(nrows=2, ncols=1, figsize=(11, 5), dpi=150)
+openbb.stocks.dps.dpotc(
+    "aapl",
+    external_axes=[ax1, ax2],
+    chart=True,
+)
+fig.tight_layout()
+```
+
+**Stocks Return Distribution** \
+Fetches data from the OpenBB API and then plots the return distribution. This is a good example, where the data from
+the API is leveraged to build a new feature on top of the API.
+
+```python
+import numpy as np
+import matplotlib.pyplot as plt
+from openbb_terminal.api import openbb
+# Fetches data from the api
+gme = openbb.stocks.load("gme")
+# Calculates logarithmic returns
+gme["Log Returns"] = np.log(gme["Adj Close"]/gme["Adjusted Close"].shift(1))
+# Plots the return distributions
+gme["Log Returns"].hist(bins=1000)
+plt.thight_layout()
+plt.show()
+```
+
+For more examples see the OpenBB jupyter notebook reports. They all use the API to its fullest extent!

openbb_terminal/alternative/alt_api.py

@@ -4,3 +4,4 @@
 
 # Context menus
 from .covid import covid_api as covid
+from .oss import oss_api as oss

openbb_terminal/alternative/covid/covid_api.py

@@ -9,7 +9,7 @@
 from openbb_terminal.alternative.covid.covid_view import display_covid_ov as ov
 from openbb_terminal.alternative.covid.covid_view import display_covid_stat as stat
 from openbb_terminal.alternative.covid.covid_view import (
-    display_country_slopes as slopes,
+    display_case_slopes as slopes,
 )
 
 

openbb_terminal/alternative/covid/covid_controller.py

@@ -232,7 +232,7 @@ def call_slopes(self, other_args: List[str]):
             parser, other_args, export_allowed=EXPORT_ONLY_RAW_DATA_ALLOWED, limit=10
         )
         if ns_parser:
-            covid_view.display_country_slopes(
+            covid_view.display_case_slopes(
                 days_back=ns_parser.days,
                 limit=ns_parser.limit,
                 ascend=ns_parser.ascend,

openbb_terminal/alternative/covid/covid_model.py

@@ -8,6 +8,7 @@
 import pandas as pd
 
 from openbb_terminal.decorators import log_start_end
+from openbb_terminal.rich_config import console
 
 logger = logging.getLogger(__name__)
 
@@ -80,37 +81,105 @@ def get_global_deaths(country: str) -> pd.DataFrame:
 
 
 @log_start_end(log=logger)
-def get_case_slopes(days_back: int = 30, threshold: int = 10000) -> pd.DataFrame:
+def get_covid_ov(
+    country,
+    limit: int = 100,
+) -> pd.DataFrame:
+    """Get historical cases and deaths by country
+
+    Parameters
+    ----------
+    country: str
+        Country to get data for
+    limit: int
+        Number of raw data to show
+    """
+    cases = get_global_cases(country)
+    deaths = get_global_deaths(country)
+    data = pd.concat([cases, deaths], axis=1)
+    data.columns = ["Cases", "Deaths"]
+    data.index = [x.strftime("%Y-%m-%d") for x in data.index]
+    return data.tail(limit)
+
+
+@log_start_end(log=logger)
+def get_covid_stat(
+    country,
+    stat: str = "cases",
+    limit: int = 10,
+) -> pd.DataFrame:
+    """Show historical cases and deaths by country
+
+    Parameters
+    ----------
+    country: str
+        Country to get data for
+    stat: str
+        Statistic to get.  Either "cases", "deaths" or "rates"
+    limit: int
+        Number of raw data to show
+    """
+    if stat == "cases":
+        data = get_global_cases(country)
+    elif stat == "deaths":
+        data = get_global_deaths(country)
+    elif stat == "rates":
+        cases = get_global_cases(country)
+        deaths = get_global_deaths(country)
+        data = (deaths / cases).fillna(0) * 100
+    else:
+        console.print("Invalid stat selected.\n")
+        return pd.DataFrame()
+    data.index = [x.strftime("%Y-%m-%d") for x in data.index]
+    return data.tail(limit)
+
+
+@log_start_end(log=logger)
+def get_case_slopes(
+    days_back: int = 30,
+    limit: int = 50,
+    threshold: int = 10000,
+    ascend: bool = False,
+) -> pd.DataFrame:
     """Load cases and find slope over period
 
     Parameters
     ----------
     days_back: int
         Number of historical days to consider
+    limit: int
+        Number of rows to show
     threshold: int
         Threshold for total number of cases
+    ascend: bool
+        Flag to sort in ascending order
     Returns
     -------
     pd.DataFrame
         Dataframe containing slopes
     """
     # Ignore the pandas warning for setting a slace with a value
     warnings.filterwarnings("ignore")
-    cases = pd.read_csv(global_cases_time_series)
-    cases = cases.rename(columns={"Country/Region": "Country"})
-    cases = (
+    data = pd.read_csv(global_cases_time_series)
+    data = data.rename(columns={"Country/Region": "Country"})
+    data = (
         (
-            cases.drop(columns=["Province/State", "Lat", "Long"])
+            data.drop(columns=["Province/State", "Lat", "Long"])
             .groupby("Country")
             .agg("sum")
         )
         .diff()
         .dropna()
     )
-    hist = cases.iloc[:, -days_back:]
+    hist = data.iloc[:, -days_back:]
     hist["Sum"] = hist.sum(axis=1)
     hist = hist[hist.Sum > threshold].drop(columns="Sum")
     hist["Slope"] = hist.apply(
         lambda x: np.polyfit(np.arange(days_back), x, 1)[0], axis=1
     )
-    return pd.DataFrame(hist["Slope"])
+    hist_slope = pd.DataFrame(hist["Slope"])
+    if ascend:
+        hist_slope.sort_values(by="Slope", ascending=ascend, inplace=True)
+    else:
+        hist_slope.sort_values(by="Slope", ascending=ascend, inplace=True)
+    return hist_slope.head(limit)