bobotig/py-candlestick-chart

Draw candlesticks charts right into your terminal, using Python!

Python Candlesticks Chart

📈 Draw candlesticks charts right into your terminal, using Python!

This is a portage from the great cli-candlestick-chart (developed by 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
  • Features
  • Installation
  • Demonstration
• Binary Usage
• Examples
  • API
  • Binary
    • Read CSV from file
    • Read JSON from file
    • Read from stdin
  • Developers

Features

• Auto-fit to terminal size
• Practical formatting for big, and tiny, numbers
• Integration with Rich
• Simple, yet customizable, API
• Exact same API as the Rust version, plus some sugar
• Simple installation, no external dependencies

Installation

As simple as:

$ python -m pip install -U candlestick-chart

Demonstration

from candlestick_chart import Candle, Chart

# Add some candles
candles = [
    Candle(open=133.520004, close=133.610001, high=126.760002, low=129.410004),
    Candle(open=128.889999, close=131.740005, high=128.429993, low=131.009995),
    Candle(open=127.720001, close=131.050003, high=126.379997, low=126.599998),
    Candle(open=128.360001, close=131.630005, high=127.860001, low=130.919998),
    Candle(open=132.429993, close=132.630005, high=130.229996, low=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
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):

$ 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:

[
    {
        "open": 28994.009766,
        "high": 29600.626953,
        "low": 28803.585938,
        "close": 29374.152344
    },
    ...
]

For all requests, here are supported fields:

"open": float  # mandatory
"close": float  # mandatory
"high": float  # mandatory
"low": float  # mandatory
"volume": float
"timestamp": float

Examples

API

• Basic example with CSV parsing: run with $ python examples/basic-from-csv-file.py
• Basic example with JSON parsing: run with $ python examples/basic-from-json-file.py
• Basic example with stdin parsing: run with $ ./examples/basic-from-stdin.sh
• Fetch candles from Binance: run with $ python examples/fetch-from-binance.py
• Integration with Rich: run with $ python examples/integrate-with-rich.py
• Using a custom chart renderer class: run with $ python examples/custom-renderer-class.py

Binary

Read CSV from file

$ 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

$ candlestick-chart \
    --mode=json-file \
    --file='./examples/BTC-chart.json' \
    --chart-name='My BTC Chart' \
    --bear-color='#b967ff' \
    --bull-color='ff6b99'

Read from stdin

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'

Developers

Setup:

python -m venv venv
. venv/bin/activate
python -m pip install -U pip

Install:

python -m pip install -e '.[test]'

Test:

python -m pytest

py-candlestick-chart's Issues

not work in python 3.8

not work in python 3.8

Feature request: draw EMA

Hi, Dear @BoboTiG 👍
This is a great project!!! I wonder that does this project support draw EMA lines, like EMA 20...
if NOT, Do you have a plan to support this feature?

  thank you very much for your project 

Cli crashes when no name is provided

HI, nice tool ! Thanks for sharing it.

I've noticed a small bug while using the cli:
If I don't provide a chart name, it crashes without providing much info:

> candlestick-chart -m json-file -f candles.json 
Traceback (most recent call last):
  File "/home/jose/charts/.venv/bin/candlestick-chart", line 8, in <module>
    sys.exit(main())
             ^^^^^^
  File "/home/jose/charts/.venv/lib/python3.11/site-packages/candlestick_chart/__main__.py", line 59, in main
    chart.draw()
  File "/home/jose/charts/.venv/lib/python3.11/site-packages/candlestick_chart/chart.py", line 57, in draw
    print(self._render())
          ^^^^^^^^^^^^^^
  File "/home/jose/charts/.venv/lib/python3.11/site-packages/candlestick_chart/chart.py", line 53, in _render
    return self.renderer.render(self)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jose/charts/.venv/lib/python3.11/site-packages/candlestick_chart/chart_renderer.py", line 104, in render
    output.append(chart.info_bar.render(chart_data.main_candle_set, chart_data.width))
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jose/charts/.venv/lib/python3.11/site-packages/candlestick_chart/info_bar.py", line 60, in render
    " | ".join(
TypeError: object of type 'NoneType' has no len()
>

It works if a name is provided:

> candlestick-chart -m json-file -f candles.json --chart-name __NAME__

and even with an empty name:

> candlestick-chart -m json-file -f candles.json --chart-name ''

It looks like the default value for the argument should be a string, changing this line seems to fix it

py-candlestick-chart/src/candlestick_chart/__main__.py

Line 33 in e6a2a0b

parser.add_argument("--chart-name", help="Sets the chart name.")

    parser.add_argument("--chart-name", help="Sets the chart name.", default="")

I'm using the latest version from PyPI:

> candlestick-chart --version
candlestick-chart 2.6.0

TypeError: Candle.__init__() takes 1 positional argument but 5 were given

Hello! When trying to run the example you post, I get the following error.
TypeError: Candle.init() takes 1 positional argument but 5 were given
Thanks!

Prevent a zero division error

Traceback (most recent call last):
  # ...
  File "candlestick_chart/chart.py", line 36, in __rich_console__
    yield Group(*AnsiDecoder().decode(self._render()))
  File "candlestick_chart/chart.py", line 40, in _render
    return self.renderer.render(self)
  File "candlestick_chart/chart_renderer.py", line 82, in render
    output.extend(
  File "candlestick_chart/chart_renderer.py", line 83, in <genexpr>
    self._render_candle(candle, y, chart.y_axis) for candle in candles
  File "candlestick_chart/chart_renderer.py", line 39, in _render_candle
    high_y, low_y, max_y, min_y = y_axis.price_to_heights(candle)
  File "candlestick_chart/y_axis.py", line 27, in price_to_heights
    (candle.high - min_value) / diff * height,  # high_y
ZeroDivisionError: float division by zero

╭───────────────────────────────────────────── locals ─────────────────────────────────────────────╮
│   24 │   │   diff = candle_set.max_price - min_value                                             │
│   25 │   │                                                                                       │
│   26 │   │   return (                                                                            │
│ ❱ 27 │   │   │   (candle.high - min_value) / diff * height,  # high_y                            │
│   28 │   │   │   (candle.low - min_value) / diff * height,  # low_y                              │
│   29 │   │   │   (max_open - min_value) / diff * height,  # max_y                                │
│   30 │   │   │   (min_open - min_value) / diff * height,  # min_y                                │
│                                                                                                  │
│ ╭─────────────────────────────────────────── locals ───────────────────────────────────────────╮ │
│ │     candle = <candlestick_chart.candle.Candle object at 0x7fa58053d360>                      │ │
│ │ candle_set = CandleSet(                                                                      │ │
│ │              │   candles=[<candlestick_chart.candle.Candle object at 0x7fa58053d360>],       │ │
│ │              │   min_price=8.340877714580442e-06,                                            │ │
│ │              │   max_price=8.340877714580442e-06,                                            │ │
│ │              │   min_volume=21994.401431846,                                                 │ │
│ │              │   max_volume=21994.401431846,                                                 │ │
│ │              │   variation=0.0,                                                              │ │
│ │              │   average=8.340877714580442e-06,                                              │ │
│ │              │   last_price=8.340877714580442e-06,                                           │ │
│ │              │   cumulative_volume=21994.401431846                                           │ │
│ │              )                                                                               │ │
│ │ chart_data = <candlestick_chart.chart_data.ChartData object at 0x7fa580ea3470>               │ │
│ │       diff = 0.0                                                                             │ │
│ │     height = 32                                                                              │ │
│ │   max_open = 8.340877714580442e-06                                                           │ │
│ │   min_open = 8.340877714580442e-06                                                           │ │
│ │  min_value = 8.340877714580442e-06                                                           │ │
│ │       self = YAxis(                                                                          │ │
│ │              │   chart_data=<candlestick_chart.chart_data.ChartData object at                │ │
│ │              0x7fa580ea3470>                                                                 │ │
│ │              )                                                                               │ │
│ ╰──────────────────────────────────────────────────────────────────────────────────────────────╯ │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

demonstration just renders vertical red line

WSL debian 11;
pasted demonstration to mychart.py and commented out 5 lines containing "fnum".
Does not recognize current height, width of the terminal.
Does not draw 5 candles but one single vertical red line.

cat /etc/issue;echo $TERM; python3 mychart.py | less -SR
Debian GNU/Linux 11 \n \l
xterm-256color

xterm -fs 11 -fa DejaVuSansMono
cat /etc/issue;echo $TERM; python3 mychart.py
xterm

Improve update_candles() behavior

Chart.update_candles() behavior could be improved by adding an optional keyword argument: reset: bool = False.

The initial behavior will change:

• Chart.update_candles(some_candles) will add some_candles to the existing candle set.
• Chart.update_candles(some_candles, reset=True) will replace the existing candle set with some_candles.

Fix small numbers display

Feature request: Animation

Is it possible to run a continuous streaming candle with python

demonstration does not find fnum

Copied demonstration code into chart.py and tried to run it:

$ python3 chart.py

Traceback (most recent call last):
  File "/home/helgein/projects_python/python312/candlechart/chart.py", line 1, in <module>
    from candlestick_chart import Candle, Chart, fnum
ImportError: cannot import name 'fnum' from 'candlestick_chart' (/home/sru/.pyenv/versions/3.12.0/lib/python3.12/site-packages/candlestick_chart/__init__.py

Fix values computation in the info bar

There is a mismatch with the Rust version: when displaying the info bar, our version is computing values using the visible candle set. Actually, it should rather use the main candle set.

Our version (incorrect):

py-candlestick-chart/src/candlestick_chart/info_bar.py

Line 68 in f4bf797

def render(self, candle_set: "CandleSet") -> str:

Rust version (correct): https://github.com/Julien-R44/cli-candlestick-chart/blob/9ea785c1a9fe5e2357bfe1411150ad0a7e009135/src/info_bar.rs#L19

Rich integration

Rich integration will be tackled soon.