From 00bb1c5536f0177dd13e1efa5bf5c7ee595d4e89 Mon Sep 17 00:00:00 2001 From: louisnw Date: Tue, 16 May 2023 22:20:47 +0100 Subject: [PATCH] RTD --- README.md | 10 +- docs/source/docs.md | 220 ++++++++++++++++++++++++++++++-------------- 2 files changed, 161 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 0c18d82..f1bc117 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,12 @@ # lightweight_charts_python +[![PyPi Release](https://img.shields.io/pypi/v/lightweight-charts?color=32a852&label=PyPi)](https://pypi.org/project/lightweight-charts/) +[![Made with Python](https://img.shields.io/badge/Python-3.9+-c7a002?logo=python&logoColor=white)](https://python.org "Go to Python homepage") +[![License](https://img.shields.io/github/license/louisnw01/lightweight-charts-python?color=9c2400)](https://github.com/louisnw01/lightweight-charts-python/blob/main/LICENSE) +[![Documentation](https://img.shields.io/badge/documentation-006ee3)](https://lightweight-charts-python.readthedocs.io/en/latest/docs.html) + + + lightweight-charts-python aims to provide a simple and pythonic way to access and implement [TradingView's Lightweight Charts](https://www.tradingview.com/lightweight-charts/). @@ -197,9 +204,8 @@ if __name__ == '__main__': ``` ![callbacks gif](https://github.com/louisnw01/lightweight-charts-python/blob/main/examples/6_callbacks/callbacks.gif) ___ -## Wiki -For a detailed guide of lightweight-charts-python, view the wiki [here](https://github.com/louisnw01/lightweight-charts-python/wiki). +[![Documentation](https://img.shields.io/badge/documentation-006ee3)](https://lightweight-charts-python.readthedocs.io/en/latest/docs.html) ___ diff --git a/docs/source/docs.md b/docs/source/docs.md index a9314da..2d134bd 100644 --- a/docs/source/docs.md +++ b/docs/source/docs.md @@ -1,52 +1,73 @@ # Docs +[![louisnw01 - lightweight-charts-python](https://img.shields.io/static/v1?label=louisnw01&message=lightweight-charts-python&color=057dfc&logo=github)](https://github.com/louisnw01/lightweight-charts-python "Go to GitHub repo") +[![PyPi Release](https://img.shields.io/pypi/v/lightweight-charts?color=32a852&label=PyPi)](https://pypi.org/project/lightweight-charts/) +[![Made with Python](https://img.shields.io/badge/Python-3.9+-c7a002?logo=python&logoColor=white)](https://python.org "Go to Python homepage") +[![License](https://img.shields.io/github/license/louisnw01/lightweight-charts-python?color=9c2400)](https://github.com/louisnw01/lightweight-charts-python/blob/main/LICENSE) +[![Stars - lightweight-charts-python](https://img.shields.io/github/stars/louisnw01/lightweight-charts-python?style=social)](https://github.com/louisnw01/lightweight-charts-python) +[![Forks - lightweight-charts-python](https://img.shields.io/github/forks/louisnw01/lightweight-charts-python?style=social)](https://github.com/louisnw01/lightweight-charts-python) + ## Common Methods These methods can be used within the `Chart`, `QtChart`, and `WxChart` objects. + ___ ### `set` +`data: pd.DataFrame` -`data: DataFrame` - -~ Sets the initial data for the chart. +Sets the initial data for the chart. The data must be given as a DataFrame, with the columns: `time | open | high | low | close | volume` -The 'time' column can also be named 'date', and the 'volume' column can be omitted if volume is not enabled. +The `time` column can also be named `date`, and the `volume` column can be omitted if volume is not enabled. ___ ### `update` -~ Updates the chart data from a given bar. +`series: pd.Series` -The bar should be one 'interval' away from the last bar, given as a Series object, and contain values with labels of the same name as the columns required for using `chart.set()`. +Updates the chart data from a given bar. + +The bar should contain values with labels of the same name as the columns required for using `chart.set()`. ___ ### `update_from_tick` -~ Updates the chart from a tick. +`series: pd.Series` -This should also be given as a Series object, and contain the columns: +Updates the chart from a tick. + +The series should use the labels: `time | price | volume` -As before, the 'time' column can also be named 'date, and the 'volume' column can be omitted if volume is not enabled. +As before, the `time` can also be named `date`, and the `volume` can be omitted if volume is not enabled. + +```{information} +The provided ticks do not need to be rounded to an interval (1 min, 5 min etc.), as the library handles this automatically.``````` +``` + -The provided ticks do not need to be rounded to an interval (1 min, 5 min etc.), as the library handles this automatically. ___ ### `create_line` -~ Creates and returns a [Line](#line) object. +`color: str` | `width: int` + +Creates and returns a [Line](#line) object. ___ ### `marker` -~ Creates a new marker, and returns its UUID. +`time: datetime` | `position: 'above'/'below'/'inside'` | `shape: 'arrow_up'/'arrow_down'/'circle'/'square'` | `color: str` | `text: str` | `-> UUID` -If the `time` parameter is left blank, the marker will be placed at the latest bar. +Adds a marker to the chart, and returns its UUID. + +If the `time` parameter is not given, the marker will be placed at the latest bar. ___ ### `remove_marker` -~ Removes the marker with the given UUID. +`m_id: UUID` + +Removes the marker with the given UUID. Usage: ```python @@ -56,72 +77,118 @@ chart.remove_marker(marker) ___ ### `horizontal_line` -~ Creates a horizontal line at the given price. +`price: float/int` | `color: str` | `width: int` | `style: 'solid'/'dotted'/'dashed'/'large_dashed'/'sparse_dotted'` | `text: str` | `axis_label_visible: bool` + +Places a horizontal line at the given price. ___ ### `remove_horizontal_line` -~ Removes a horizontal line at the given price. +`price: float/int` + +Removes a horizontal line at the given price. ___ ### `config` -~ Config options for the chart. +`mode: 'normal'/'logarithmic'/'percentage'/'index100'` | `title: str` | `right_padding: int` + +Config options for the chart. ___ ### `time_scale` -~ Options for the time scale of the chart. +`time_visible: bool` | `seconds_visible: bool` + +Options for the time scale of the chart. ___ ### `layout` -~ Global layout options for the chart. +`background_color: str` | `text_color: str` | `font_size: int` | `font_family: str` + +Global layout options for the chart. ___ ### `candle_style` -~ Candle styling for each of the candle's parts (border, wick). +`up_color: str` | `down_color: str` | `wick_enabled: bool` | `border_enabled: bool` | `border_up_color: str` | `border_down_color: str` | `wick_up_color: str` | `wick_down_color: str` + + Candle styling for each of the candle's parts (border, wick). + +```{admonition} Color Formats +:class: note + +Throughout the library, colors should be given as either: +* rgb: `rgb(100, 100, 100)` +* rgba: `rgba(100, 100, 100, 0.7)` +* hex: `#32a852` +``` ___ ### `volume_config` -~ Volume config options. +`scale_margin_top: float` | `scale_margin_bottom: float` | `up_color: str` | `down_color: str` + +Volume config options. + +```{important} +The float values given to scale the margins must be greater than 0 and less than 1. +``` ___ ### `crosshair` -~ Crosshair formatting for its vertical and horizontal axes. +`mode` | `vert_width: int` | `vert_color: str` | `vert_style: str` | `vert_label_background_color: str` | `horz_width: int` | `horz_color: str` | `horz_style: str` | `horz_label_background_color: str` + +Crosshair formatting for its vertical and horizontal axes. + +`vert_style` and `horz_style` should be given as one of: `'solid'/'dotted'/'dashed'/'large_dashed'/'sparse_dotted'` ___ ### `watermark` -~ Adds a watermark to the chart. +`text: str` | `font_size: int` | `color: str` + +Overlays a watermark on top of the chart. ___ ### `legend` -~ Configures the legend of the chart. +`visible: bool` | `ohlc: bool` | `percent: bool` | `color: str` | `font_size: int` | `font_family: str` + +Configures the legend of the chart. ___ ### `subscribe_click` -~ Subscribes the given function to a chart 'click' event. +`function: object` -The event returns a dictionary containing the bar object at the time clicked. +Subscribes the given function to a chart 'click' event. + +The event emits a dictionary containing the bar at the time clicked, with the keys: + +`time | open | high | low | close` ___ ## `Chart` -The main object used for the normal functionality of lightweight-charts-python. +`volume_enabled: bool` | `width: int` | `height: int` | `x: int` | `y: int` | `on_top: bool` | `debug: bool` + +The main object used for the normal functionality of lightweight-charts-python, built on the pywebview library. ___ ### `show` -~ Shows the chart window. +`block: bool` + +Shows the chart window. If `block` is enabled, the method will block code execution until the window is closed. ___ ### `hide` -~ Hides the chart window, and can be later shown by calling `chart.show()`. + +Hides the chart window, and can be later shown by calling `chart.show()`. ___ ### `exit` -~ Exits and destroys the chart and window. + +Exits and destroys the chart and window. ___ ## `Line` -The `Line` object represents a 'line series' in Lightweight Charts and can be used to create indicators. + +The `Line` object represents a `LineSeries` object in Lightweight Charts and can be used to create indicators. ```{important} The `line` object should only be accessed from the [create_line](#create-line) method of `Chart`. @@ -129,22 +196,74 @@ The `line` object should only be accessed from the [create_line](#create-line) m ___ ### `set` -~ Sets the data for the line. +`data: pd.DataFrame` + +Sets the data for the line. This should be given as a DataFrame, with the columns: `time | price` ___ ### `update` -~ Updates the data for the line. +`series: pd.Series` + +Updates the data for the line. This should be given as a Series object, with labels akin to the `line.set()` function. ___ +## `QtChart` +`widget: QWidget` | `volume_enabled: bool` + +The `QtChart` object allows the use of charts within a `QMainWindow` object, and has similar functionality to the `Chart` object for manipulating data, configuring and styling. +___ + +### `get_webview` + +`-> QWebEngineView` + +Returns the `QWebEngineView` object. For example: + +```python +import pandas as pd +from PyQt5.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QWidget + +from lightweight_charts.widgets import QtChart + +app = QApplication([]) +window = QMainWindow() +layout = QVBoxLayout() +widget = QWidget() +widget.setLayout(layout) + +window.resize(800, 500) +layout.setContentsMargins(0, 0, 0, 0) + +chart = QtChart(widget) + +df = pd.read_csv('ohlcv.csv') +chart.set(df) + +layout.addWidget(chart.get_webview()) + +window.setCentralWidget(widget) +window.show() + +app.exec_() +``` +___ + ## `WxChart` +`parent: wx.Panel` | `volume_enabled: bool` + The WxChart object allows the use of charts within a `wx.Frame` object, and has similar functionality to the `Chart` object for manipulating data, configuring and styling. -It is built upon the `wx.html2.WebView` object and the instance of this object can be accessed from the `get_webview()` function. For example: +___ + +### `get_webview` +`-> wx.html2.WebView` + +Returns a `wx.html2.WebView` object which can be used to for positioning and styling within wxPython. For example: ```python import wx @@ -179,38 +298,5 @@ if __name__ == '__main__': ``` -___ -## `QtChart` -The `QtChart` object allows the use of charts within a `QMainWindow` object, and has similar functionality to the `Chart` object for manipulating data, configuring and styling. - -It is built upon the `QWebEngineView` object and the instance of this object can be accessed from the `get_webview()` function. For example: - -```python -import pandas as pd -from PyQt5.QtWidgets import QApplication, QMainWindow, QVBoxLayout, QWidget - -from lightweight_charts.widgets import QtChart - -app = QApplication([]) -window = QMainWindow() -layout = QVBoxLayout() -widget = QWidget() -widget.setLayout(layout) - -window.resize(800, 500) -layout.setContentsMargins(0, 0, 0, 0) - -chart = QtChart(widget) - -df = pd.read_csv('ohlcv.csv') -chart.set(df) - -layout.addWidget(chart.get_webview()) - -window.setCentralWidget(widget) -window.show() - -app.exec_() -```