# Python Candlesticks Chart
📈 Draw candlesticks charts right into your terminal, using Python!
This is a portage from the great [cli-candlestick-chart](https://github.com/Julien-R44/cli-candlestick-chart) (developed by [Julien-R44](https://github.com/Julien-R44), written in Rust).
You are looking at the Python 3.10+ version.
Note: not tested on macOS, nor Windows (it will likely fail to render colors).
**Table of contents**:
- [Python Candlesticks Chart](#python-candlesticks-chart)
- [Features](#features)
- [Intallation](#intallation)
- [Demonstration](#demonstration)
- [Binary Usage](#binary-usage)
- [Examples](#examples)
- [API](#api)
- [Binary](#binary)
- [Read CSV from file](#read-csv-from-file)
- [Read JSON from file](#read-json-from-file)
- [Read from stdin](#read-from-stdin)
## Features
- Auto-fit to terminal size
- Practical formatting for big, and tiny, numbers
- Integration with [Rich](https://github.com/Textualize/rich)
- Simple, yet customizable, API
- Exact same API as the [Rust version](https://github.com/Julien-R44/cli-candlestick-chart), plus some [sugar](#demonstration)
- Simple installation, no external dependencies
## Intallation
As simple as:
```bash
$ python -m pip install -U candlestick-chart
```
## Demonstration
```python
from candlestick_chart import Candle, Chart
# Add some candles
candles = [
Candle(133.520004, 133.610001, 126.760002, 129.410004),
Candle(128.889999, 131.740005, 128.429993, 131.009995),
Candle(127.720001, 131.050003, 126.379997, 126.599998),
Candle(128.360001, 131.630005, 127.860001, 130.919998),
Candle(132.429993, 132.630005, 130.229996, 132.050003),
]
# Create and display the chart
# Optional keyword arguments: title, width, height
chart = Chart(candles, title="Optional title")
# Set the chart title
chart.set_name("BTC/USDT")
# Set customs colors
chart.set_bear_color(1, 205, 254)
chart.set_bull_color(255, 107, 153)
chart.set_vol_bull_color(1, 205, 254)
chart.set_vol_bear_color(255, 107, 153)
# Set custom labels (empty string => label not displayed)
chart.set_label("highest", "ATH")
chart.set_label("lowest", "ATL")
chart.set_label("average", "")
chart.set_label("volume", "")
# Volume pane settings
chart.set_volume_pane_height(6)
chart.set_volume_pane_enabled(False)
# And, it is also responsive!
new_width = 200
new_height = 150
chart.update_size(new_width, new_height)
# By the way, did you know that you can add more candles in real-time?
chart.update_candles(candles[:3])
# Or completely replace current candles
chart.update_candles(candles[:3], reset=True)
# Set a custom color at price 52,348.63
# from candlestick_chart.utils import fnum
chart.set_highlight(fnum(52,348.63), "red")
chart.set_highlight(fnum(52,348.63), (255, 0, 0))
chart.set_highlight(fnum(52,348.63), "91m")
chart.set_highlight(fnum(52,348.63), "91;47m")
chart.draw()
```
# Binary Usage
When installing the library, an executable is made available (`candlestick-chart`):
```bash
$ candlestick-chart --help
options:
-h, --help show this help message and exit
-m {stdin,csv-file,json-file}, --mode {stdin,csv-file,json-file}
Select the method for retrieving the candles.
-f FILE, --file FILE [MODE:*-file] File to read candles from.
--chart-name CHART_NAME
Sets the chart name.
--bear-color BEAR_COLOR
Sets the descending candles color in hexadecimal.
--bull-color BULL_COLOR
Sets the ascending candles color in hexadecimal.
--version show program's version number and exit
```
When requesting the JSON or stdin mode, the library expects a JSON with the following format:
```json
[
{
"open": 28994.009766,
"high": 29600.626953,
"low": 28803.585938,
"close": 29374.152344
},
...
]
```
For all requests, here are supported fields:
```python
"open": float # mandatory
"close": float # mandatory
"high": float # mandatory
"low": float # mandatory
"volume": float
"timestamp": float
```
# Examples
## API
- [Basic example with CSV parsing](examples/basic-from-csv-file.py): run with `$ python examples/basic-from-csv-file.py`
- [Basic example with JSON parsing](examples/basic-from-json-file.py): run with `$ python examples/basic-from-json-file.py`
- [Basic example with stdin parsing](examples/basic-from-stdin.sh): run with `$ ./examples/basic-from-stdin.sh`
- [Fetch candles from Binance](examples/fetch-from-binance.py): run with `$ python examples/fetch-from-binance.py`
- [Integration with Rich](examples/integrate-with-rich.py): run with `$ python examples/integrate-with-rich.py`
- [Using a custom chart renderer class](examples/custom-renderer-class.py): run with `$ python examples/custom-renderer-class.py`
## Binary
### Read CSV from file
```bash
$ candlestick-chart \
--mode=csv-file \
--file='./examples/BTC-USD.csv' \
--chart-name='My BTC Chart' \
--bear-color='#b967ff' \
--bull-color='ff6b99'
```
### Read JSON from file
```bash
$ candlestick-chart \
--mode=json-file \
--file='./examples/BTC-chart.json' \
--chart-name='My BTC Chart' \
--bear-color='#b967ff' \
--bull-color='ff6b99'
```
### Read from stdin
```bash
echo '[
{
"open": 28994.009766,
"high": 29600.626953,
"low": 28803.585938,
"close": 29374.152344
},
{
"open": 29376.455078,
"high": 33155.117188,
"low": 29091.181641,
"close": 32127.267578
}
]' | candlestick-chart \
--mode=stdin \
--chart-name='My BTC Chart' \
--bear-color='#b967ff' \
--bull-color='ff6b99'
```
Raw data
{
"_id": null,
"home_page": "https://github.com/BoboTiG/py-candlestick-chart",
"name": "candlestick-chart",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "",
"keywords": "candle,candlestick,chart,cli,console,crypto,stock,stock-market,options,terminal,trading",
"author": "Micka\u00ebl 'Tiger-222' Schoentgen",
"author_email": "contact@tiger-222.fr",
"download_url": "https://files.pythonhosted.org/packages/f1/b5/c629dbc816191997cf7ccc2d17d50ea41d988d447e7457cf003ed220bf60/candlestick-chart-2.7.0.tar.gz",
"platform": "Linux",
"description": "# Python Candlesticks Chart\n\n\ud83d\udcc8 Draw candlesticks charts right into your terminal, using Python!\n\n\n\nThis is a portage from the great [cli-candlestick-chart](https://github.com/Julien-R44/cli-candlestick-chart) (developed by [Julien-R44](https://github.com/Julien-R44), written in Rust).\nYou are looking at the Python 3.10+ version.\n\nNote: not tested on macOS, nor Windows (it will likely fail to render colors).\n\n**Table of contents**:\n- [Python Candlesticks Chart](#python-candlesticks-chart)\n - [Features](#features)\n - [Intallation](#intallation)\n - [Demonstration](#demonstration)\n- [Binary Usage](#binary-usage)\n- [Examples](#examples)\n - [API](#api)\n - [Binary](#binary)\n - [Read CSV from file](#read-csv-from-file)\n - [Read JSON from file](#read-json-from-file)\n - [Read from stdin](#read-from-stdin)\n\n## Features\n\n- Auto-fit to terminal size\n- Practical formatting for big, and tiny, numbers\n- Integration with [Rich](https://github.com/Textualize/rich)\n- Simple, yet customizable, API\n- Exact same API as the [Rust version](https://github.com/Julien-R44/cli-candlestick-chart), plus some [sugar](#demonstration)\n- Simple installation, no external dependencies\n\n## Intallation\n\nAs simple as:\n\n```bash\n$ python -m pip install -U candlestick-chart\n```\n\n## Demonstration\n\n```python\nfrom candlestick_chart import Candle, Chart\n\n# Add some candles\ncandles = [\n Candle(133.520004, 133.610001, 126.760002, 129.410004),\n Candle(128.889999, 131.740005, 128.429993, 131.009995),\n Candle(127.720001, 131.050003, 126.379997, 126.599998),\n Candle(128.360001, 131.630005, 127.860001, 130.919998),\n Candle(132.429993, 132.630005, 130.229996, 132.050003),\n]\n\n# Create and display the chart\n# Optional keyword arguments: title, width, height\nchart = Chart(candles, title=\"Optional title\")\n\n# Set the chart title\nchart.set_name(\"BTC/USDT\")\n\n# Set customs colors\nchart.set_bear_color(1, 205, 254)\nchart.set_bull_color(255, 107, 153)\nchart.set_vol_bull_color(1, 205, 254)\nchart.set_vol_bear_color(255, 107, 153)\n\n# Set custom labels (empty string => label not displayed)\nchart.set_label(\"highest\", \"ATH\")\nchart.set_label(\"lowest\", \"ATL\")\nchart.set_label(\"average\", \"\")\nchart.set_label(\"volume\", \"\")\n\n# Volume pane settings\nchart.set_volume_pane_height(6)\nchart.set_volume_pane_enabled(False)\n\n# And, it is also responsive!\nnew_width = 200\nnew_height = 150\nchart.update_size(new_width, new_height)\n\n# By the way, did you know that you can add more candles in real-time?\nchart.update_candles(candles[:3])\n# Or completely replace current candles\nchart.update_candles(candles[:3], reset=True)\n\n# Set a custom color at price 52,348.63\n# from candlestick_chart.utils import fnum\nchart.set_highlight(fnum(52,348.63), \"red\")\nchart.set_highlight(fnum(52,348.63), (255, 0, 0))\nchart.set_highlight(fnum(52,348.63), \"91m\")\nchart.set_highlight(fnum(52,348.63), \"91;47m\")\n\nchart.draw()\n```\n\n# Binary Usage\n\nWhen installing the library, an executable is made available (`candlestick-chart`):\n\n```bash\n$ candlestick-chart --help \n\noptions:\n -h, --help show this help message and exit\n -m {stdin,csv-file,json-file}, --mode {stdin,csv-file,json-file}\n Select the method for retrieving the candles.\n -f FILE, --file FILE [MODE:*-file] File to read candles from.\n --chart-name CHART_NAME\n Sets the chart name.\n --bear-color BEAR_COLOR\n Sets the descending candles color in hexadecimal.\n --bull-color BULL_COLOR\n Sets the ascending candles color in hexadecimal.\n --version show program's version number and exit\n```\n\nWhen requesting the JSON or stdin mode, the library expects a JSON with the following format: \n\n```json\n[\n {\n \"open\": 28994.009766,\n \"high\": 29600.626953,\n \"low\": 28803.585938,\n \"close\": 29374.152344\n },\n ...\n]\n```\n\nFor all requests, here are supported fields:\n\n```python\n\"open\": float # mandatory\n\"close\": float # mandatory\n\"high\": float # mandatory\n\"low\": float # mandatory\n\"volume\": float\n\"timestamp\": float\n```\n\n# Examples\n\n## API \n\n- [Basic example with CSV parsing](examples/basic-from-csv-file.py): run with `$ python examples/basic-from-csv-file.py`\n- [Basic example with JSON parsing](examples/basic-from-json-file.py): run with `$ python examples/basic-from-json-file.py`\n- [Basic example with stdin parsing](examples/basic-from-stdin.sh): run with `$ ./examples/basic-from-stdin.sh`\n- [Fetch candles from Binance](examples/fetch-from-binance.py): run with `$ python examples/fetch-from-binance.py`\n- [Integration with Rich](examples/integrate-with-rich.py): run with `$ python examples/integrate-with-rich.py`\n- [Using a custom chart renderer class](examples/custom-renderer-class.py): run with `$ python examples/custom-renderer-class.py`\n\n## Binary \n\n### Read CSV from file\n\n```bash\n$ candlestick-chart \\\n --mode=csv-file \\\n --file='./examples/BTC-USD.csv' \\\n --chart-name='My BTC Chart' \\\n --bear-color='#b967ff' \\\n --bull-color='ff6b99'\n```\n### Read JSON from file\n\n```bash\n$ candlestick-chart \\\n --mode=json-file \\\n --file='./examples/BTC-chart.json' \\\n --chart-name='My BTC Chart' \\\n --bear-color='#b967ff' \\\n --bull-color='ff6b99'\n```\n\n### Read from stdin\n\n```bash\necho '[\n {\n \"open\": 28994.009766,\n \"high\": 29600.626953,\n \"low\": 28803.585938,\n \"close\": 29374.152344\n },\n {\n \"open\": 29376.455078,\n \"high\": 33155.117188,\n \"low\": 29091.181641,\n \"close\": 32127.267578\n }\n]' | candlestick-chart \\\n --mode=stdin \\\n --chart-name='My BTC Chart' \\\n --bear-color='#b967ff' \\\n --bull-color='ff6b99'\n```\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Draw candlesticks charts right into your terminal, using Python!",
"version": "2.7.0",
"split_keywords": [
"candle",
"candlestick",
"chart",
"cli",
"console",
"crypto",
"stock",
"stock-market",
"options",
"terminal",
"trading"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1d7b5415cbe4599ad8a14d3c733487e133024747f2e6ee2f3f1701c08d7c351e",
"md5": "91c41d956cb8c2deed331d3b958d35a0",
"sha256": "295c45dd0c3b890e2ed182aa00b9e26eed9f3db173be98d36ad18793073e5d14"
},
"downloads": -1,
"filename": "candlestick_chart-2.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "91c41d956cb8c2deed331d3b958d35a0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16812,
"upload_time": "2023-04-23T21:06:00",
"upload_time_iso_8601": "2023-04-23T21:06:00.695112Z",
"url": "https://files.pythonhosted.org/packages/1d/7b/5415cbe4599ad8a14d3c733487e133024747f2e6ee2f3f1701c08d7c351e/candlestick_chart-2.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1b5c629dbc816191997cf7ccc2d17d50ea41d988d447e7457cf003ed220bf60",
"md5": "8bc8fa93e5ac46bb887ff6576d8db8c4",
"sha256": "6bb09985ef5f507be1eeceba669b9ed29c4a8be5f35c45d2ff7002bd624a00be"
},
"downloads": -1,
"filename": "candlestick-chart-2.7.0.tar.gz",
"has_sig": false,
"md5_digest": "8bc8fa93e5ac46bb887ff6576d8db8c4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15217,
"upload_time": "2023-04-23T21:06:03",
"upload_time_iso_8601": "2023-04-23T21:06:03.091384Z",
"url": "https://files.pythonhosted.org/packages/f1/b5/c629dbc816191997cf7ccc2d17d50ea41d988d447e7457cf003ed220bf60/candlestick-chart-2.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-23 21:06:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "BoboTiG",
"github_project": "py-candlestick-chart",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "candlestick-chart"
}
JSON
