openbb-charting 2.5.1__tar.gz → 4.0.0__tar.gz

openbb_charting-4.0.0/.gitignore

@@ -0,0 +1,65 @@
+# General
+__pycache__/
+*.pyc
+.DS_Store
+*.env
+.venv
+venv*/
+venv
+.vscode
+*.ipynb
+env/
+venv/
+!notebooks/jupyter/.gitkeep
+.python-version
+.mypy_cache
+.ruff_cache
+.pytest_cache
+iframe_figures/
+exports/*
+.idea
+.coverage
+.scannerwork
+htmlcov
+**/.ipynb_checkpoints
+*.swp
+*.http
+.coverage.*
+*_tests.csv
+*_sdk_audit.csv
+!build/docker/compose.env
+.dccache
+*rome.json
+**/node_modules/*
+.cursorignore
+darts_logs/
+custom_imports/*.csv
+custom_imports/*/*.csv
+cache/
+lightning_logs/
+*/mocked_path
+*.pem
+
+# CLI
+*.pyo
+**/dist/*
+build/cli
+build/nsis/app
+DMG/*
+*.dmg
+*.sh
+cli/openbb_cli/assets/styles/user/*
+
+# Platform
+openbb_platform/core/openbb/package/*
+openbb_platform/core/openbb/.build.lock
+**/assets/*.json.xz
+
+# Dev Container env
+obb/*
+
+# OpenBB Distribution
+!build/conda/installer/*.sh
+*.pkg
+*.exe
+build/conda/tmp

openbb_charting-4.0.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.5
+Name: openbb-charting
+Version: 4.0.0
+Summary: Charting extension for OpenBB
+Project-URL: Homepage, https://openbb.co
+Project-URL: Repository, https://github.com/OpenBB-finance/OpenBB
+Author-email: OpenBB Team <hello@openbb.co>
+License: Apache-2.0
+Requires-Python: <4,>=3.10
+Requires-Dist: openbb-core[pandas]>=2.0.0
+Requires-Dist: pandas-ta-openbb>=0.4.24
+Requires-Dist: plotly>=6.3.1
+Provides-Extra: pywry
+Requires-Dist: pywry>=2.0.4; extra == 'pywry'
+Description-Content-Type: text/markdown
+
+# OpenBB Charting
+
+Plotly-based charting for the OpenBB Platform. Installing this package registers a `charting` accessor on every `OBBject` command result and enables the `chart=True` argument on Platform endpoints that have a chart.
+
+## Installation
+
+```bash
+pip install openbb-charting
+```
+
+To display charts in a native desktop window, install the PyWry extra:
+
+```bash
+pip install "openbb-charting[pywry]"
+```
+
+On Linux, PyWry requires system WebKit/GTK libraries:
+
+- Debian / Ubuntu / Mint: `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev`
+- Arch / Manjaro: `sudo pacman -S webkit2gtk`
+- Fedora: `sudo dnf install gtk3-devel webkit2gtk3-devel`
+
+## Usage
+
+Pass `chart=True` to an endpoint that has a chart, then call `show()` on the result:
+
+```python
+from openbb import obb
+
+data = obb.equity.price.historical("AAPL", provider="yfinance", chart=True)
+data.show()
+```
+
+The same chart is reachable through the `charting` accessor on any result, without `chart=True`:
+
+```python
+res = obb.equity.price.historical("AAPL", provider="yfinance")
+res.charting.show()
+```
+
+### Which commands have a chart
+
+Charts are contributed by the installed extensions. List the registered routes:
+
+```python
+from openbb_charting import Charting
+
+Charting.functions()
+```
+
+### Technical-analysis overlays — `to_chart`
+
+`to_chart` rebuilds the chart of a time-series (OHLCV) result with indicator overlays. Indicators and their parameters are passed through the `indicators` argument:
+
+```python
+res = obb.equity.price.historical("AAPL", provider="yfinance")
+res.charting.to_chart(
+    indicators=dict(
+        sma=dict(length=[20, 50]),
+        rsi=dict(length=14),
+        macd=dict(fast=12, slow=26, signal=9),
+    )
+)
+res.show()
+```
+
+List every available indicator and its parameters:
+
+```python
+res.charting.indicators()  # from a result
+Charting.indicators()  # standalone
+```
+
+## Building charts directly from data
+
+The accessor exposes builders that accept a DataFrame or a list of `Data` (such as `OBBject.results`) and return an `OpenBBFigure`. Their input signatures differ; `create_line_chart` and `create_bar_chart` also display the chart by default — pass `render=False` to build it without displaying.
+
+```python
+res = obb.equity.price.historical("AAPL", provider="yfinance")
+df = res.to_dataframe()
+
+fig = res.charting.create_line_chart(data=res.results, target="close", render=False)
+fig = res.charting.create_bar_chart(
+    data=res.results, x="date", y="volume", render=False
+)
+fig = res.charting.create_correlation_matrix(data=res.results, method="pearson")
+fig = res.charting.create_3d_surface(X=df["open"], Y=df["high"], Z=df["close"])
+fig.show()
+```
+
+## Adding a chart to a command
+
+Register a charting-view class through the `openbb_charting_extension` entry-point group in your `pyproject.toml`:
+
+```toml
+[project.entry-points."openbb_charting_extension"]
+my_extension = "openbb_my_extension.my_extension_views:MyExtensionViews"
+```
+
+A view method is matched to an endpoint by replacing the route's slashes with underscores: `/equity/price/historical` → `equity_price_historical`, `/technical/ema` → `technical_ema`. Each method receives the command output as `**kwargs` and returns a `tuple[OpenBBFigure, dict[str, Any]]` — the interactive figure plus the JSON content the API serializes.
+
+```python
+"""Views for MyExtension."""
+
+from typing import Any
+
+from openbb_charting.charts.price_historical import price_historical
+from openbb_charting.core.openbb_figure import OpenBBFigure
+
+
+class MyExtensionViews:
+    """MyExtension Views."""
+
+    @staticmethod
+    def my_extension_price_historical(**kwargs) -> tuple[OpenBBFigure, dict[str, Any]]:
+        """My Extension Price Historical Chart."""
+        return price_historical(**kwargs)
+```
+
+The chart is then produced by setting `chart=True` on the command, or via `result.charting.show()`.
+
+## Replacing the engine, hooks, and backend
+
+The Platform interfaces (Python, API, CLI, MCP) do not depend on `openbb-charting` by name; they resolve the active engine from whichever OBBject extension registers the `charting` accessor. Three things are pluggable through entry points alone.
+
+### Replace the engine
+
+Ship an OBBject extension that registers the `charting` accessor:
+
+```toml
+[project.entry-points."openbb_obbject_extension"]
+my_charting = "openbb_my_charting:ext"   # ext = Extension(name="charting")
+```
+
+If `openbb-charting` is uninstalled, your engine is used automatically. When both are installed, select one with `system_settings.charting_extension` (or the `OPENBB_CHARTING_EXTENSION` environment variable). An engine must expose the `functions()` classmethod, and `get_backend_class()` to be usable from the CLI.
+
+### Chart lifecycle hooks
+
+Register a `ChartingHook` subclass under the `openbb_charting_hooks` group. Hooks run inside chart creation, so they fire for every interface:
+
+```toml
+[project.entry-points."openbb_charting_hooks"]
+my_hook = "openbb_my_pkg.hooks:MyHook"
+```
+
+```python
+from openbb_core.app.charting import ChartingHook
+
+
+class MyHook(ChartingHook):
+    """Watermark every figure after it is built."""
+
+    routes = ()  # empty matches all routes
+    priority = 100  # lower runs first
+
+    def post_figure(self, context):
+        context.figure.add_annotation(text="INTERNAL", opacity=0.1)
+        return context
+```
+
+Stages: `resolve_data`, `pre_figure`, `post_figure`, `pre_render`, `post_render`. A hook mutates `context` in place and/or returns a new one.
+
+### Backend override
+
+Swap the rendering backend (PyWry / browser / custom) without replacing the engine, via the `openbb_charting_backend` group:
+
+```toml
+[project.entry-points."openbb_charting_backend"]
+my_backend = "openbb_my_pkg.backend:MyBackend"
+```
+
+A backend is constructed with a single `charting_settings` argument. The override is opt-in: set `system_settings.charting_backend` (or `OPENBB_CHARTING_BACKEND`) to the registered name. Without a selection, the engine keeps its built-in backend.

openbb_charting-4.0.0/README.md

@@ -0,0 +1,172 @@
+# OpenBB Charting
+
+Plotly-based charting for the OpenBB Platform. Installing this package registers a `charting` accessor on every `OBBject` command result and enables the `chart=True` argument on Platform endpoints that have a chart.
+
+## Installation
+
+```bash
+pip install openbb-charting
+```
+
+To display charts in a native desktop window, install the PyWry extra:
+
+```bash
+pip install "openbb-charting[pywry]"
+```
+
+On Linux, PyWry requires system WebKit/GTK libraries:
+
+- Debian / Ubuntu / Mint: `sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev`
+- Arch / Manjaro: `sudo pacman -S webkit2gtk`
+- Fedora: `sudo dnf install gtk3-devel webkit2gtk3-devel`
+
+## Usage
+
+Pass `chart=True` to an endpoint that has a chart, then call `show()` on the result:
+
+```python
+from openbb import obb
+
+data = obb.equity.price.historical("AAPL", provider="yfinance", chart=True)
+data.show()
+```
+
+The same chart is reachable through the `charting` accessor on any result, without `chart=True`:
+
+```python
+res = obb.equity.price.historical("AAPL", provider="yfinance")
+res.charting.show()
+```
+
+### Which commands have a chart
+
+Charts are contributed by the installed extensions. List the registered routes:
+
+```python
+from openbb_charting import Charting
+
+Charting.functions()
+```
+
+### Technical-analysis overlays — `to_chart`
+
+`to_chart` rebuilds the chart of a time-series (OHLCV) result with indicator overlays. Indicators and their parameters are passed through the `indicators` argument:
+
+```python
+res = obb.equity.price.historical("AAPL", provider="yfinance")
+res.charting.to_chart(
+    indicators=dict(
+        sma=dict(length=[20, 50]),
+        rsi=dict(length=14),
+        macd=dict(fast=12, slow=26, signal=9),
+    )
+)
+res.show()
+```
+
+List every available indicator and its parameters:
+
+```python
+res.charting.indicators()  # from a result
+Charting.indicators()  # standalone
+```
+
+## Building charts directly from data
+
+The accessor exposes builders that accept a DataFrame or a list of `Data` (such as `OBBject.results`) and return an `OpenBBFigure`. Their input signatures differ; `create_line_chart` and `create_bar_chart` also display the chart by default — pass `render=False` to build it without displaying.
+
+```python
+res = obb.equity.price.historical("AAPL", provider="yfinance")
+df = res.to_dataframe()
+
+fig = res.charting.create_line_chart(data=res.results, target="close", render=False)
+fig = res.charting.create_bar_chart(
+    data=res.results, x="date", y="volume", render=False
+)
+fig = res.charting.create_correlation_matrix(data=res.results, method="pearson")
+fig = res.charting.create_3d_surface(X=df["open"], Y=df["high"], Z=df["close"])
+fig.show()
+```
+
+## Adding a chart to a command
+
+Register a charting-view class through the `openbb_charting_extension` entry-point group in your `pyproject.toml`:
+
+```toml
+[project.entry-points."openbb_charting_extension"]
+my_extension = "openbb_my_extension.my_extension_views:MyExtensionViews"
+```
+
+A view method is matched to an endpoint by replacing the route's slashes with underscores: `/equity/price/historical` → `equity_price_historical`, `/technical/ema` → `technical_ema`. Each method receives the command output as `**kwargs` and returns a `tuple[OpenBBFigure, dict[str, Any]]` — the interactive figure plus the JSON content the API serializes.
+
+```python
+"""Views for MyExtension."""
+
+from typing import Any
+
+from openbb_charting.charts.price_historical import price_historical
+from openbb_charting.core.openbb_figure import OpenBBFigure
+
+
+class MyExtensionViews:
+    """MyExtension Views."""
+
+    @staticmethod
+    def my_extension_price_historical(**kwargs) -> tuple[OpenBBFigure, dict[str, Any]]:
+        """My Extension Price Historical Chart."""
+        return price_historical(**kwargs)
+```
+
+The chart is then produced by setting `chart=True` on the command, or via `result.charting.show()`.
+
+## Replacing the engine, hooks, and backend
+
+The Platform interfaces (Python, API, CLI, MCP) do not depend on `openbb-charting` by name; they resolve the active engine from whichever OBBject extension registers the `charting` accessor. Three things are pluggable through entry points alone.
+
+### Replace the engine
+
+Ship an OBBject extension that registers the `charting` accessor:
+
+```toml
+[project.entry-points."openbb_obbject_extension"]
+my_charting = "openbb_my_charting:ext"   # ext = Extension(name="charting")
+```
+
+If `openbb-charting` is uninstalled, your engine is used automatically. When both are installed, select one with `system_settings.charting_extension` (or the `OPENBB_CHARTING_EXTENSION` environment variable). An engine must expose the `functions()` classmethod, and `get_backend_class()` to be usable from the CLI.
+
+### Chart lifecycle hooks
+
+Register a `ChartingHook` subclass under the `openbb_charting_hooks` group. Hooks run inside chart creation, so they fire for every interface:
+
+```toml
+[project.entry-points."openbb_charting_hooks"]
+my_hook = "openbb_my_pkg.hooks:MyHook"
+```
+
+```python
+from openbb_core.app.charting import ChartingHook
+
+
+class MyHook(ChartingHook):
+    """Watermark every figure after it is built."""
+
+    routes = ()  # empty matches all routes
+    priority = 100  # lower runs first
+
+    def post_figure(self, context):
+        context.figure.add_annotation(text="INTERNAL", opacity=0.1)
+        return context
+```
+
+Stages: `resolve_data`, `pre_figure`, `post_figure`, `pre_render`, `post_render`. A hook mutates `context` in place and/or returns a new one.
+
+### Backend override
+
+Swap the rendering backend (PyWry / browser / custom) without replacing the engine, via the `openbb_charting_backend` group:
+
+```toml
+[project.entry-points."openbb_charting_backend"]
+my_backend = "openbb_my_pkg.backend:MyBackend"
+```
+
+A backend is constructed with a single `charting_settings` argument. The override is opt-in: set `system_settings.charting_backend` (or `OPENBB_CHARTING_BACKEND`) to the registered name. Without a selection, the engine keeps its built-in backend.

openbb_charting-4.0.0/examples.md

@@ -0,0 +1,172 @@
+---
+title: Examples
+sidebar_position: 1
+description: This page provides examples of creating charts with the `openbb-charting` extension.
+keywords:
+- tutorial
+- OpenBB Platform
+- Python client
+- Fast API
+- getting started
+- extensions
+- charting
+- view
+- Plotly
+- toolkits
+- how-to
+- generic
+- figure
+---
+
+import HeadTitle from '@site/src/components/General/HeadTitle.tsx';
+
+<HeadTitle title="Examples - OpenBB Charting - Extensions | OpenBB Platform Docs" />
+
+## Overview
+
+This page will walk through creating different charts using the `openbb-charting` extension.
+The perspective for this content is from the Python Interface,
+and the examples will assume that the OpenBB Platform is installed with all optional packages.
+
+```python
+from datetime import datetime, timedelta
+from openbb import obb
+```
+
+## Cumulative Returns
+
+The historical (equity) prices can be requested for multiple symbols.
+The extension will attempt to handle variations accordingly.
+By default, more than three symbols will draw the chart as cumulative returns from the beginning of the series.
+
+### Default View
+
+The tickers below are a collection of State Street Global Advisors SPDR funds, representing S&P 500 components.
+The data is looking back five years.
+
+```python
+SPDRS = [
+    "SPY",
+    "XLE",
+    "XLB",
+    "XLI",
+    "XHB",
+    "XLP",
+    "XLY",
+    "XRT",
+    "XLF",
+    "XLV",
+    "XLK",
+    "XLC",
+    "XLU",
+    "XLRE",
+]
+start_date = (datetime.now() - timedelta(weeks=52 * 5)).date()
+spdrs = obb.equity.price.historical(
+    SPDRS, start_date=start_date, provider="yfinance", chart=True
+)
+
+spdrs.show()
+```
+
+![SPDRs Cumulative Returns - 5 years](https://github.com/OpenBB-finance/OpenBB/assets/85772166/8884f4ed-b09c-4161-9dc6-87ad66d9fc8b)
+
+### Redraw as YTD
+
+The `charting` attribute of the command output has methods for creating the chart again.
+The `data` parameter allows modifications to the data before creating the figure.
+In this example, the length of the data is trimmed to the beginning of the year.
+
+```python
+new_data = spdrs.to_df().loc[datetime(2024, 12, 29).date() :]
+spdrs.charting.to_chart(data=new_data, title="YTD")
+```
+
+:::note
+This replaces the chart that was already created.
+:::
+
+![SPDRs Cumulative Returns - YTD](https://github.com/OpenBB-finance/OpenBB/assets/85772166/22ed2588-1098-4712-aec1-54dd22c324ef)
+
+## Price Performance Bar Chart
+
+The `obb.equity.price.performance` endpoint will create a bar chart over intervals.
+
+```python
+price_performance = obb.equity.price.performance(SPDRS, chart=True)
+price_performance.show()
+```
+
+![Price Performance](https://github.com/OpenBB-finance/OpenBB/assets/85772166/0de3260d-7fce-490b-90e1-bdfa38d6ab23)
+
+### Create Bar Chart
+
+This example uses the `create_bar_chart()` method, which does not replace the existing chart, in `price_performance.chart`.
+It isolates the one-month performance and orients the layout as horizontal.
+
+```python
+new_data = price_performance.to_df().set_index("symbol").multiply(100).reset_index()
+price_performance.charting.create_bar_chart(
+    data=new_data,
+    x="symbol",
+    y="one_month",
+    orientation="h",
+    title="One Month Price Performance",
+    xtitle="Percent (%)",
+)
+```
+
+![Horizonontal Price Performance](https://github.com/OpenBB-finance/OpenBB/assets/85772166/8da01f73-d7a8-4168-846a-9fa9ed6a0e39)
+
+## Create Your Own
+
+This example analyzes the share volume turnover of the S&P 500 Energy Sector constituents, year-to-date.
+
+```python
+symbols = [
+    "XOM",
+    "CVX",
+    "COP",
+    "WMB",
+    "EOG",
+    "KMI",
+    "OKE",
+    "MPC",
+    "PSX",
+    "SLB",
+    "VLO",
+    "BKR",
+    "HES",
+    "TRGP",
+    "EQT",
+    "OXY",
+    "TPL",
+    "FANG",
+    "EXE",
+    "DVN",
+    "HAL",
+    "CTRA",
+    "APA",
+]
+data = obb.equity.price.historical(
+    symbols, start_date="2025-01-01", provider="yfinance"
+)
+create_bar_chart = data.charting.create_bar_chart
+volume = data.to_df().groupby("symbol").sum()["volume"]
+shares = (
+    obb.equity.profile(symbols, provider="yfinance")
+    .to_df()
+    .set_index("symbol")["shares_float"]
+)
+df = volume.to_frame().join(shares)
+df["Turnover"] = (df.volume / df.shares_float).round(4)
+df = df.sort_values(by="Turnover", ascending=False).reset_index()
+create_bar_chart(
+    data=df,
+    x="symbol",
+    y="Turnover",
+    title="S&P Energy Sector YTD Turnover Rate",
+)
+```
+
+![S&P 500 Energy Sector Turnover Rate](https://github.com/OpenBB-finance/OpenBB/assets/85772166/d29a1c17-6d3b-4925-8b7e-f661da404967)