API Reference

This page documents every public function and class in Wickly.

Top-level functions

wickly.plot(data, **kwargs)[source]

Plot an OHLCV DataFrame as an interactive candlestick chart.

The signature intentionally mirrors mplfinance.plot() so that users can switch between libraries with minimal changes.

Parameters:

  • data (pd.DataFrame) – Must contain columns Open, High, Low, Close (case-insensitive) and optionally Volume. The index should be a DatetimeIndex.

  • optional) (Keyword arguments (all)

  • --------------------------------

  • type (str) – 'candle' (default), 'ohlc', 'line', 'hollow'

  • style (str or dict) – Style name ('default', 'charles', 'mike', 'yahoo', 'classic', 'nightclouds') or a dict from make_style.

  • volume (bool) – If True, show a volume sub-chart.

  • mav (int or tuple of ints) – Moving-average period(s).

  • title (str) – Chart title.

  • ylabel (str) – Y-axis label.

  • figsize (tuple[int, int]) – (width, height) of the window in pixels. Default (960, 600).

  • columns (tuple[str, ...]) – Override column names — ("Open","High","Low","Close","Volume").

  • addplot (dict or list[dict]) – Additional plot(s) created with make_addplot().

  • savefig (str) – If given, save the chart to this file path.

  • returnfig (bool) – If True return (widget, axes_dict) instead of blocking.

  • block (bool) – If True (default) block until the window is closed.

  • kwargs (Any)

Returns:

  • None when block=True; otherwise (CandlestickWidget, dict)

  • where dict maps axis names to internal references.

Return type:

tuple[CandlestickWidget, dict[str, Any]] | None

wickly.live_plot(data, **kwargs)[source]

Create a non-blocking chart that can be updated with new data.

Works exactly like plot(returnfig=True, block=False) but is more explicit about its intent: the returned widget is designed to be fed new bars via append_data() or updated in-place via update_last().

Parameters:

  • data (pd.DataFrame) – Initial OHLCV DataFrame.

  • **kwargs – All keyword arguments accepted by plot() except returnfig and block (which are forced to True / False).

Returns:

The live widget and an axes dict.

Return type:

(CandlestickWidget, dict)

Examples

>>> widget, axes = wickly.live_plot(df, type='candle', volume=True)
>>> # later, when a new bar arrives:
>>> widget.append_data(new_dates, new_opens, new_highs,
...                    new_lows, new_closes)
>>> # or update the last candle in real time:
>>> widget.update_last(close=new_price,
...                    high=max(old_high, new_price))
wickly.make_addplot(data, *, type='line', color=None, width=1.5, alpha=1.0, scatter=False, marker='o', markersize=50, linestyle='-', secondary_y=False, panel=0, ylabel=None, **_extra)[source]

Build an addplot dict describing extra data to overlay on the chart.

Mirrors the mplfinance.make_addplot() signature so users can switch libraries with minimal changes.

Parameters:

  • data (array-like) – The y-values to plot. Must be the same length as the OHLCV DataFrame passed to plot().

  • type (str) – 'line', 'scatter', or 'segments'. When 'segments' is used, data must be a list of (start_index, values) tuples — see make_segments() for a convenient builder.

  • color (str or None) – Colour string (hex / named).

  • width (float) – Line width (for type='line' or 'segments').

  • alpha (float) – Opacity 0-1.

  • scatter (bool) – Deprecated. Use type='scatter' instead.

  • marker (str) – Marker style when type='scatter'.

  • markersize (float) – Marker size when type='scatter'.

  • linestyle (str) – Matplotlib-style linestyle string.

  • secondary_y (bool) – (reserved for future use)

  • panel (int or str) – (reserved for future use — currently everything goes on main panel)

  • ylabel (str or None) – Legend label shown in the chart’s overlay legend. If given, the overlay appears in the legend with a colour swatch; omit or pass None to hide the overlay from the legend.

  • _extra (Any)

Returns:

A configuration dictionary consumed by wickly.plot(addplot=...).

Return type:

dict

wickly.make_segments(segments, *, color=None, width=1.5, alpha=1.0, linestyle='-', ylabel=None)[source]

Build an addplot dict for multiple independent (possibly overlapping) line segments.

This is a convenience wrapper around make_addplot(type='segments', ...). Use it when you need overlapping lines that cannot be represented by a single NaN-separated array — for example, Knoxville Divergence signals where a new divergence can start before a previous one ends.

Parameters:

  • segments (list of (start_index, values) tuples) – Each tuple is (start_index, y_values) where start_index is the bar index at which the segment begins and y_values is an array-like of consecutive y-values. Segments may overlap freely.

  • color (str or None) – Colour string (hex / named).

  • width (float) – Line width.

  • alpha (float) – Opacity 0-1.

  • linestyle (str) – '-', '--', '-.', or ':'.

  • ylabel (str or None) – Legend label shown in the chart’s overlay legend. If given, the overlay appears in the legend with a colour swatch.

Returns:

A configuration dictionary consumed by wickly.plot(addplot=...).

Return type:

dict

Examples

>>> seg1 = (10, [50.1, 50.5, 51.0, 50.8])   # bars 10–13
>>> seg2 = (12, [51.2, 51.5, 51.3])          # bars 12–14, overlaps seg1
>>> apd = wickly.make_segments([seg1, seg2], color='#e91e63', ylabel='Divergence')
>>> wickly.plot(df, addplot=[apd])
wickly.make_style(*, base_mpf_style='default', up_color=None, down_color=None, edge_up=None, edge_down=None, wick_up=None, wick_down=None, volume_up=None, volume_down=None, bg_color=None, grid_color=None, text_color=None, alpha=None, mavcolors=None)[source]

Create a style dict — similar to mplfinance.make_mpf_style.

Parameters:

  • base_mpf_style (str)

  • up_color (str | None)

  • down_color (str | None)

  • edge_up (str | None)

  • edge_down (str | None)

  • wick_up (str | None)

  • wick_down (str | None)

  • volume_up (str | None)

  • volume_down (str | None)

  • bg_color (str | None)

  • grid_color (str | None)

  • text_color (str | None)

  • alpha (float | None)

  • mavcolors (list[str] | None)

Return type:

dict[str, Any]

wickly.available_styles()[source]

Return a list of available built-in style names.

Return type:

list[str]

Chart widget

class wickly.chart_widget.CandlestickWidget(parent=None, *, dates=None, opens=None, highs=None, lows=None, closes=None, volumes=None, chart_type='candle', style=None, show_volume=False, mav=None, title=None, ylabel='Price', addplots=None)[source]

Bases: QWidget

A self-contained, interactive candlestick chart widget.

Features

  • Candlestick / OHLC-bar / line / hollow-candle rendering

  • Optional volume sub-chart

  • Moving average overlays

  • Additional line / scatter plots (addplot)

  • Mouse-wheel zoom, click-drag pan

  • Crosshair + tooltip with OHLC / volume readout

set_data(dates, opens, highs, lows, closes, volumes=None)[source]

Replace chart data and repaint.

Parameters:
Return type:

None

append_data(dates, opens, highs, lows, closes, volumes=None, *, auto_scroll=True)[source]

Append one or more bars to the chart.

This is the primary method for building animated / live charts. New data is concatenated to the existing arrays and the view is optionally scrolled so the latest bar is always visible.

Parameters:

  • dates (DatetimeIndex) – Array-like data for the new bar(s). Must all have the same length.

  • opens (ndarray) – Array-like data for the new bar(s). Must all have the same length.

  • highs (ndarray) – Array-like data for the new bar(s). Must all have the same length.

  • lows (ndarray) – Array-like data for the new bar(s). Must all have the same length.

  • closes (ndarray) – Array-like data for the new bar(s). Must all have the same length.

  • volumes (ndarray | None) – Array-like data for the new bar(s). Must all have the same length.

  • auto_scroll (bool) – If True (default) the visible window slides so the newest bar is at the right edge. Set to False to keep the current pan position.

Return type:

None

update_last(open_=None, high=None, low=None, close=None, volume=None)[source]

Update the most recent bar in-place and repaint.

Use this for live tick updates within an incomplete candle. Only the supplied values are overwritten; pass None to leave a field unchanged.

Parameters:

  • open (float or None) – New open price.

  • high (float or None) – New high price.

  • low (float or None) – New low price.

  • close (float or None) – New close price.

  • volume (float or None) – New volume.

  • open_ (float | None)

Return type:

None

update_addplot(index, data)[source]

Replace the data of an existing addplot and repaint.

Parameters:

  • index (int) – Zero-based index into the list of addplots (in the order they were passed to plot() / live_plot()).

  • data (array-like) – New data for the overlay. For type='line' or 'scatter' this must be a 1-D array-like of the same length as the current OHLCV data. For type='segments' pass a list of (start_index, values) tuples.

Return type:

None

append_addplot_data(index, values)[source]

Append values to an existing line or scatter addplot.

Call this alongside append_data() to keep an overlay array in sync with the OHLCV data. For bars where the overlay has no value, pass float('nan').

Parameters:

  • index (int) – Zero-based index into the list of addplots.

  • values (float or array-like) – Value(s) to append. A single float appends one point; an array-like appends multiple points.

Return type:

None

update_addplot_last(index, value)[source]

Update the last value of a line/scatter addplot in-place.

Use this alongside update_last() to keep an overlay in sync with live tick updates on the most recent bar.

Parameters:

  • index (int) – Zero-based index into the list of addplots.

  • value (float) – New value for the last point.

Return type:

None

save(path)[source]

Render the widget to an image file.

Parameters:

path (str)

Return type:

None

paintEvent(self, a0: QPaintEvent | None)[source]
Parameters:

event (QPaintEvent)

Return type:

None

wheelEvent(self, a0: QWheelEvent | None)[source]
Parameters:

event (QWheelEvent)

Return type:

None

mousePressEvent(self, a0: QMouseEvent | None)[source]
Parameters:

event (QMouseEvent)

Return type:

None

mouseReleaseEvent(self, a0: QMouseEvent | None)[source]
Parameters:

event (QMouseEvent)

Return type:

None

mouseMoveEvent(self, a0: QMouseEvent | None)[source]
Parameters:

event (QMouseEvent)

Return type:

None

leaveEvent(self, a0: QEvent | None)[source]
Parameters:

event (Any)

Return type:

None

resizeEvent(self, a0: QResizeEvent | None)[source]
Parameters:

event (QResizeEvent)

Return type:

None

Parameters:

  • parent (QWidget | None)

  • dates (np.ndarray | pd.DatetimeIndex | None)

  • opens (np.ndarray | None)

  • highs (np.ndarray | None)

  • lows (np.ndarray | None)

  • closes (np.ndarray | None)

  • volumes (np.ndarray | None)

  • chart_type (str)

  • style (dict[str, Any] | None)

  • show_volume (bool)

  • mav (int | tuple[int, ...] | None)

  • title (str | None)

  • ylabel (str)

  • addplots (list[dict[str, Any]] | None)

Plotting module

wickly.plotting.plot(data, **kwargs)[source]

Plot an OHLCV DataFrame as an interactive candlestick chart.

The signature intentionally mirrors mplfinance.plot() so that users can switch between libraries with minimal changes.

Parameters:

  • data (pd.DataFrame) – Must contain columns Open, High, Low, Close (case-insensitive) and optionally Volume. The index should be a DatetimeIndex.

  • optional) (Keyword arguments (all)

  • --------------------------------

  • type (str) – 'candle' (default), 'ohlc', 'line', 'hollow'

  • style (str or dict) – Style name ('default', 'charles', 'mike', 'yahoo', 'classic', 'nightclouds') or a dict from make_style.

  • volume (bool) – If True, show a volume sub-chart.

  • mav (int or tuple of ints) – Moving-average period(s).

  • title (str) – Chart title.

  • ylabel (str) – Y-axis label.

  • figsize (tuple[int, int]) – (width, height) of the window in pixels. Default (960, 600).

  • columns (tuple[str, ...]) – Override column names — ("Open","High","Low","Close","Volume").

  • addplot (dict or list[dict]) – Additional plot(s) created with make_addplot().

  • savefig (str) – If given, save the chart to this file path.

  • returnfig (bool) – If True return (widget, axes_dict) instead of blocking.

  • block (bool) – If True (default) block until the window is closed.

  • kwargs (Any)

Returns:

  • None when block=True; otherwise (CandlestickWidget, dict)

  • where dict maps axis names to internal references.

Return type:

tuple[CandlestickWidget, dict[str, Any]] | None

wickly.plotting.live_plot(data, **kwargs)[source]

Create a non-blocking chart that can be updated with new data.

Works exactly like plot(returnfig=True, block=False) but is more explicit about its intent: the returned widget is designed to be fed new bars via append_data() or updated in-place via update_last().

Parameters:

  • data (pd.DataFrame) – Initial OHLCV DataFrame.

  • **kwargs – All keyword arguments accepted by plot() except returnfig and block (which are forced to True / False).

Returns:

The live widget and an axes dict.

Return type:

(CandlestickWidget, dict)

Examples

>>> widget, axes = wickly.live_plot(df, type='candle', volume=True)
>>> # later, when a new bar arrives:
>>> widget.append_data(new_dates, new_opens, new_highs,
...                    new_lows, new_closes)
>>> # or update the last candle in real time:
>>> widget.update_last(close=new_price,
...                    high=max(old_high, new_price))

Addplot module

wickly.addplot.make_addplot(data, *, type='line', color=None, width=1.5, alpha=1.0, scatter=False, marker='o', markersize=50, linestyle='-', secondary_y=False, panel=0, ylabel=None, **_extra)[source]

Build an addplot dict describing extra data to overlay on the chart.

Mirrors the mplfinance.make_addplot() signature so users can switch libraries with minimal changes.

Parameters:

  • data (array-like) – The y-values to plot. Must be the same length as the OHLCV DataFrame passed to plot().

  • type (str) – 'line', 'scatter', or 'segments'. When 'segments' is used, data must be a list of (start_index, values) tuples — see make_segments() for a convenient builder.

  • color (str or None) – Colour string (hex / named).

  • width (float) – Line width (for type='line' or 'segments').

  • alpha (float) – Opacity 0-1.

  • scatter (bool) – Deprecated. Use type='scatter' instead.

  • marker (str) – Marker style when type='scatter'.

  • markersize (float) – Marker size when type='scatter'.

  • linestyle (str) – Matplotlib-style linestyle string.

  • secondary_y (bool) – (reserved for future use)

  • panel (int or str) – (reserved for future use — currently everything goes on main panel)

  • ylabel (str or None) – Legend label shown in the chart’s overlay legend. If given, the overlay appears in the legend with a colour swatch; omit or pass None to hide the overlay from the legend.

  • _extra (Any)

Returns:

A configuration dictionary consumed by wickly.plot(addplot=...).

Return type:

dict

wickly.addplot.make_segments(segments, *, color=None, width=1.5, alpha=1.0, linestyle='-', ylabel=None)[source]

Build an addplot dict for multiple independent (possibly overlapping) line segments.

This is a convenience wrapper around make_addplot(type='segments', ...). Use it when you need overlapping lines that cannot be represented by a single NaN-separated array — for example, Knoxville Divergence signals where a new divergence can start before a previous one ends.

Parameters:

  • segments (list of (start_index, values) tuples) – Each tuple is (start_index, y_values) where start_index is the bar index at which the segment begins and y_values is an array-like of consecutive y-values. Segments may overlap freely.

  • color (str or None) – Colour string (hex / named).

  • width (float) – Line width.

  • alpha (float) – Opacity 0-1.

  • linestyle (str) – '-', '--', '-.', or ':'.

  • ylabel (str or None) – Legend label shown in the chart’s overlay legend. If given, the overlay appears in the legend with a colour swatch.

Returns:

A configuration dictionary consumed by wickly.plot(addplot=...).

Return type:

dict

Examples

>>> seg1 = (10, [50.1, 50.5, 51.0, 50.8])   # bars 10–13
>>> seg2 = (12, [51.2, 51.5, 51.3])          # bars 12–14, overlaps seg1
>>> apd = wickly.make_segments([seg1, seg2], color='#e91e63', ylabel='Divergence')
>>> wickly.plot(df, addplot=[apd])

Styles module

wickly.styles.available_styles()[source]

Return a list of available built-in style names.

Return type:

list[str]

wickly.styles.make_style(*, base_mpf_style='default', up_color=None, down_color=None, edge_up=None, edge_down=None, wick_up=None, wick_down=None, volume_up=None, volume_down=None, bg_color=None, grid_color=None, text_color=None, alpha=None, mavcolors=None)[source]

Create a style dict — similar to mplfinance.make_mpf_style.

Parameters:

  • base_mpf_style (str)

  • up_color (str | None)

  • down_color (str | None)

  • edge_up (str | None)

  • edge_down (str | None)

  • wick_up (str | None)

  • wick_down (str | None)

  • volume_up (str | None)

  • volume_down (str | None)

  • bg_color (str | None)

  • grid_color (str | None)

  • text_color (str | None)

  • alpha (float | None)

  • mavcolors (list[str] | None)

Return type:

dict[str, Any]

Utilities

wickly._utils.check_and_prepare_data(data, columns=('Open', 'High', 'Low', 'Close', 'Volume'))[source]

Validate an OHLC(V) DataFrame and return arrays.

Return type:

opens, highs, lows, closes, volumes (or None), dates

Parameters: