- -
| Good code :white_check_mark: | Bad code :x: | -
| - - ```python - def display_last_uni_swaps( - top: int = 10, - sortby: str = "timestamp", - descend: bool = False, - export: str = "",) -> None: - ``` - - | -- - ```python - def display_last_uni_swaps( - top: int, - sortby: str, - descend: bool, - export: str,) -> None: - ``` - - | -
- -2. Simple and understandable input objects; avoid for example weird dictionaries packed with data: {βtitleβ: DataFrame} - - - Why? Ease of use and often these complex formats are clumsy, prone to error and the formatting required for complex parameters is time consuming and unneeded. - -
- -
| Good code :white_check_mark: | Bad code :x: | -
| - - ```python - def get_coins( - top: int = 250, - category: str = "") -> pd.DataFrame: - ``` - - | -- - ```python - def load( - file: str, - file_types: list, - data_files: Dict[Any, Any], - data_examples: Dict[Any, Any],) -> pd.DataFrame: - ``` - - | -
- -3. Each function needs to have a docstring explaining what it does, its parameters and what it returns. - - - Why? You can use the function without reading its source code. This improves the developing experience and SDK usage. The SDK factory also canβt handle functions without docstrings. - -
- -4. Consistent and clear argument naming; not `symbol` in `_view` and then `ticker` in `_file` -> ticker everywhere; the name should be descriptive of what information it holds (see Style Guide section below) - - - Why? You can quickly understand what the input should be; example: tickers and stock names are fundamentally different, but theyβre both strings so they should be named accordingly. - -
- -
| Good code :white_check_mark: | Bad code :x: | -
| - - ```python - data: pd.Series, dataset_name: str, y_label: str, - ``` - - | -- - ```python - data: pd.Series, dataset: str, column: str, - ``` - - | -
- -5. Classes (for example the portfolio class) should hold the relevant data and perform no other calculations, these calculations should be done in an independent function. - - - Why? Two reasons: - - These calculations can then be used outside of the class with custom data; for example via the sdk or for tests. - - ```python - from openbb_terminal.portfolio.portfolio_helper import get_gaintopain_ratio - - # Direct function access - get_gaintopain_ratio(historical_trade_data, benchmark_trades, benchmark_returns) - ``` - - The function can be loaded in SDK factory as an endpoint and user can get result by passing the class instance. - - ```python - from openbb_terminal.sdk import openbb - from openbb_terminal.sdk import Portfolio - - transactions = Portfolio.read_orderbook("../../portfolio/holdings/example.csv") - P = Portfolio(transactions) - P.generate_portfolio_data() - P.set_benchmark() - - # SDK endpoint access - openbb.portfolio.gaintopain(P) - ``` - -
| Good code :white_check_mark: | Bad code :x: | -
| - - ```python - def get_gaintopain_ratio(portfolio: PortfolioEngine) -> pd.DataFrame: - - """...""" - - gtp_period_df = portfolio_helper.get_gaintopain_ratio( - portfolio.historical_trade_data, - portfolio.benchmark_trades, - portfolio.benchmark_returns) - - return gtp_period_df - ``` - - | -- - ```python - def get_gaintopain_ratio(self) -> pd.DataFrame: - - """...""" - - vals = list() - - for period in portfolio_helper.PERIODS: - port_rets = portfolio_helper.filter_df_by_period(self.portfolio_returns, period) - bench_rets = portfolio_helper.filter_df_by_period(self.benchmark_returns, period) - - ... - ``` - - | -
- -6. Naming among related model and view functions should be obvious; just different prefix if possible - - - Why? Eases SDK factory mapping and keeps code clean. - -
- -
| Good code :white_check_mark: | Bad code :x: | -
| - - ```python - # [fred_view.py] - - def display_yieldcurve(country: str): - - df = fred_model.get_yieldcurve(country) - - β¦ - - # [fred_model.py] - - def get_yieldcurve(country: str) -> pd.Dataframe: - - β¦ - ``` - - | -- - ```python - # [fred_view.py] - - def display_bondscrv(country: str): - - df = fred_model.get_yieldcurve(country) - - β¦ - - # [fred_model.py] - - def get_yldcurve(country: str) -> pd.Dataframe: - - β¦ - ``` - - | -
- -### File Specific Requirements - -1. No data altering in the view file or controller file (view and model with same args) - - - Why? Consistency and good code structure. This also improves the SDK user experience. Thus follows that view and model files will have the same arguments (except for output options like raw, export, external_axes), since no data changes shall be done in the view file. - -
- -2. Each model (get_) should almost always have its own view function (display_) - - - Why? To respect the principles laid out in Code Structure and the previous bullet point. If your code does not have this `get_` β `display_` map itβs likely that i. and/or ii. fail to hold. - - i. Data is processed in `_model` files and displayed in `_view` files - - ii. `_view` and `_model` files will have the same arguments (except for output options) - -
- -### Coding Style - -When in doubt, follow
- -#### Flags - -Show raw data : `raw` _(bool)_ - -```python -def display_data(..., raw: bool = False, ...): - ... - if raw: - print_rich_table(...) -``` - -Sort in ascending order : `ascend` _(bool)_ - -```python -def display_data(..., sortby: str = "", ascend: bool = False, ...): - ... - if sortby: - data = data.sort_values(by=sortby, ascend=ascend) -``` - -Show plot : `plot` _(bool)_ - -```python -def display_data(..., plot: bool = False, ...): - ... - if plot: - ... - fig.add_scatter(...) -``` - -
- -#### Output format - -Format to export data : `export` _(str), e.g. csv, json, xlsx_ - -```python -def display_data(..., export: str = "", ...): - ... - export_data(export, os.path.dirname(os.path.abspath(__file__)), "func", data) -``` - -Whether to display plot or return figure _(False: display, True: return)_ : `external_axes` _(bool)_ - -```python -def display_data(..., external_axes: bool = False, ...): - ... - fig = OpenBBFigure() - fig.add_scatter(...) - return fig.show(external=external_axes) -``` - -Field by which to sort : `sortby` _(str), e.g. "Volume"_ - -```python -def display_data(..., sortby: str = "col", ...): - ... - if sortby: - data = data.sort_values(by=sortby) -``` - -Maximum limit number of output items : `limit` _(int)_ - -```python -def display_data(..., limit = 10, ...): - ... - print_rich_table( - data[:limit], - ... - ) -``` - -
- -#### Time-related - -Date from which data is fetched (YYYY-MM-DD) : `start_date` _(str), e.g. 2022-01-01_ - -Date up to which data is fetched (YYYY-MM-DD) : `end_date` _(str), e.g. 2022-12-31_ - -Note: We want to accept dates in string because it is easier to deal from user standpoint. Inside the function you can convert it to datetime and check its validity. Please specify date format in docstring. - -```python -def get_historical_data(..., start_date: str = "2022-01-01", end_date: str = "2022-12-31",): - """ - ... - Parameters - ---------- - start_date: str - Date from which data is fetched in format YYYY-MM-DD - end_date: str - Date up to which data is fetched in format YYYY-MM-DD - ... - """ - data = source_model.get_data(data_name, start_date, end_date, ...) -``` - -Year from which data is fetched (YYYY) : `start_year` _(str), e.g. 2022_ - -Year up to which data is fetched (YYYY) : `end_year` _(str), e.g. 2023_ - -```python -def get_historical_data(..., start_year: str = "2022", end_year str = "2023", ...): - ... - data = source_model.get_data(data_name, start_year, end_year, ...) -``` - -Interval for data observations : `interval` _(str), e.g. 60m, 90m, 1h_ - -```python -def get_prices(interval: str = "60m", ...): - ... - data = source.download( - ..., - interval=interval, - ... - ) -``` - -Rolling window length : `window` _(int/str), e.g. 252, 252d_ - -```python -def get_rolling_sum(returns: pd.Series, window: str = "252d"): - rolling_sum = returns.rolling(window=window).sum() -``` - -
- -#### Data selection and manipulation - -Search term used to query : `query` (str) - -Maximum limit of search items/periods in data source: `limit` _(int)_ - -Note: please specify limit application in docstring - -```python -def get_data_from_source(..., limit: int = 10, ...): - """ - Parameters - ---------- - ... - limit: int - Number of results to fetch from source - ... - """ - data = source.get_data(data_name, n_results=limit, ...) -``` - -Dictionary of input datasets : `datasets` _(Dict[str, pd.DataFrame])_ - -Note: Most occurrences are on the econometrics menu and might be refactored in near future - -Input dataset : `data` _(pd.DataFrame)_ - -```python -def process_data(..., data: pd.DataFrame, ...): - """ - ... - Parameters - ---------- - ... - data : pd.DataFrame - Dataframe of ... - ... - """ - col_data = pd.DataFrame(data["Col"]) -``` - -Dataset name : `dataset_name` _(str)_ - -Input series : `data` _(pd.Series)_ - -Dependent variable series : `dependent_series` _(pd.Series)_ - -Independent variable series : `independent_series` _(pd.Series)_ - -```python -def get_econometric_test(dependent_series, independent_series, ...): - ... - dataset = pd.concat([dependent_series, independent_series], axis=1) - result = econometric_test(dataset, ...) -``` - -Country name : `country` _(str), e.g. United States, Portugal_ - -Country initials or abbreviation : `country_code` _(str) e.g. US, PT, USA, POR_ - -Currency to convert data : `currency` _(str) e.g. EUR, USD_ - -
- -#### Financial instrument characteristics - -Instrument ticker, name or currency pair : `symbol` _(str), e.g. AAPL, ethereum, ETH, ETH-USD_ - -```python -def get_prices(symbol: str = "AAPL", ...): - ... - data = source.download( - tickers=symbol, - ... - ) -``` - -Instrument name: `name` _(str)_ - -Note: If a function has both name and symbol as parameter, we should distinguish them and call it name - -List of instrument tickers, names or currency pairs : `symbols` _(List/List[str]), e.g. ["AAPL", "MSFT"]_ - -Base currency under ***BASE***-QUOTE β ***XXX***-YYY convention : `from_symbol` _(str), e.g. ETH in ETH-USD_ - -Quote currency under BASE-***QUOTE*** β XXX-***YYY*** convention : `to_symbol` _(str), e.g. USD in ETH-USD_ - -```python -def get_exchange_rate(from_symbol: str = "", to_symbol: str = "", ...): - ... - df = source.get_quotes(from_symbol, to_symbol, ...) -``` - -Instrument price : `price` _(float)_ - -Instrument implied volatility : `implied_volatility` _(float)_ - -Option strike price : `strike_price` _(float)_ - -Option days until expiration : `time_to_expiration` _(float/str)_ - -Risk free rate : `risk_free_rate` _(float)_ - -Options expiry date : `expiry` _(str)_ - -
- -#### Naming Convention - -- The name of the variables must be descriptive of what they stand for. I.e. `ticker` is descriptive, `aux` is not. -- Single character variables **must** be avoided. Except if they correspond to the iterator of a loop. - -#### Docstrings - -The docstring format used in **numpy**, an example is shown below: - -```python -def command_foo(var1: str, var2: List[int], var3: bool = False) -> Tuple[int, pd.DataFrame]: -"""Small description - -[Optional: Longer description] - -Parameters ----------- -var1 : str - var1 description -var2 : List[int] - var2 description -var3 : bool, optional - var3 description - -Returns -------- -foo : int - returned foo description -pd.DataFrame - dataframe returned -""" -``` - -#### Linters - -The following linters are used by our codebase: - -| Linter | Description | -| ------------ | --------------------------------- | -| bandit | security analyzer | -| black | code formatter | -| codespell | spelling checker | -| ruff | a fast python linter | -| mypy | static typing checker | -| pylint | static code analysis | -| markdownlint | markdown linter | - -#### Command names - -- The command name should be as short as possible. -- The command name should allow the user to know what the command refers to without needing to read description. (e.g. `earn`) - - - If this is not possible, then the command name should be an abbreviation of what the functionality corresponds to (e.g. `ycrv` for `yield curve`) - -- The command name **should not** have the data source explicit - -#### UI and UX - -
-
-It is important to keep a coherent UI/UX throughout the terminal. These are the rules we must abide:
-
-- There is 1 single empty line between user input and start of the command output.
-- There is 1 single empty line between command output and the user input.
-- The menu help has 1 empty line above text and 1 empty line below. Both still within the rectangular panel.
-- From menu help rectangular panel there's no empty line below - this makes it more clear to the user that they are inside such menu.
-
-## External API Keys
-
-### Creating API key
-
-OpenBB Terminal currently has over 100 different data sources. Most of these require an API key that allows access to some free tier features from the data provider, but also paid ones.
-
-When a new API data source is added to the platform, it must be added through [credentials_model.py](/openbb_terminal/core/models/credentials_model.py).
-
-In order to do that, you'll simply need to choose from one the following files:
-
-1. [local_credentials.json](openbb_terminal/miscellaneous/models/local_credentials.json) --> credentials that should only be stored locally and not pushed to the [OpenBB Hub](https://my.openbb.co/) like brokerage keys or other very sensitive or personal to the user.
-2. [hub_credentials.json](openbb_terminal/miscellaneous/models/hub_credentials.json) --> credentials that should be stored in the [OpenBB Hub](https://my.openbb.co/) like API keys to access your favorite providers.
-
-Then just update [all_api_keys.json](openbb_terminal/miscellaneous/models/all_api_keys.json) with the instructions to get
-the api key from the data source website. Make sure that this file has the correct `.json` format, otherwise the API keys page in the Hub will break (e.g. in json the last element key-value pair shouldn't be followed by a comma, and the last object in a list of dictionaries should also not be followed by a comma).
-
-> Note: By differentiating between local and hub credentials, we can ensure that the user's credentials are not pushed to the [OpenBB Hub](https://my.openbb.co/) and are only stored locally. This does not mean that the credentials are not secure in the OpenBB Hub, but rather that the user can choose to store them locally if they wish.
-
-### Setting and checking API key
-
-One of the first steps once adding a new data source that requires an API key is to add that key to our [keys_controller.py](/openbb_terminal/keys_controller.py). This menu allows the user to set API keys and check their validity.
-
-The following code allows to check the validity of the Polygon API key.
-
-```python
-
-def check_polygon_key(show_output: bool = False) -> str:
- """Check Polygon key
-
- Parameters
- ----------
- show_output: bool
- Display status string or not. By default, False.
-
- Returns
- -------
- str
- Status of key set
- """
-
- current_user = get_current_user()
-
- if current_user.credentials.