Metadata-Version: 2.4
Name: wickly
Version: 0.1.0
Summary: Interactive candlestick chart plotting with PyQt6 — mplfinance-compatible API
Author: wickly Contributors
License: MIT
Keywords: candlestick,finance,pyqt6,interactive,chart,ohlc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyQt6>=6.4
Requires-Dist: pandas>=1.5
Requires-Dist: numpy>=1.23
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo>=2024.1; extra == "docs"
Requires-Dist: myst-parser>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
Dynamic: license-file

![wickly logo](https://github.com/ShreyanshDarshan/wickly/raw/main/docs/_static/wickly_logo.png)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://github.com/ShreyanshDarshan/wickly/actions/workflows/tests.yml/badge.svg)](https://github.com/ShreyanshDarshan/wickly/actions/workflows/tests.yml)

**Interactive candlestick chart plotting with PyQt6** — drop-in replacement for `mplfinance` with rich interactivity.

![wickly demo](https://github.com/ShreyanshDarshan/wickly/raw/main/docs/_static/wickly_demo.gif)

## Features

- 📈 Candlestick, OHLC bar, line, and hollow-candle chart types
- 📊 Optional volume subplot
- 🔍 Mouse-wheel zoom and click-drag pan
- 🎯 Crosshair cursor with live OHLC / volume readout
- 📐 Moving average overlays (`mav` parameter)
- 🎨 Built-in styles (`default`, `charles`, `mike`, `yahoo`, `classic`, `nightclouds`)
- 🖼️ `make_addplot()` for overlaying custom data (line, scatter & segments)
- 🔀 `make_segments()` for overlapping broken-line overlays (e.g. Knoxville Divergence)
- 💾 `savefig()` support (PNG / JPG / BMP)
- 🔁 `returnfig` mode for embedding in your own PyQt6 application
- 🔴 `live_plot()` for animated / live-updating charts
- ✅ mplfinance-compatible function signatures

## Installation

```bash
pip install .
```

Or in editable/development mode:

```bash
pip install -e ".[dev]"
```

## Quick Start

```python
import pandas as pd
import wickly

# DataFrame must have a DatetimeIndex and columns: Open, High, Low, Close (and optionally Volume)
df = pd.read_csv("your_data.csv", index_col=0, parse_dates=True)

# Candlestick chart with volume and moving averages — same API as mplfinance
wickly.plot(df, type='candle', volume=True, mav=(10, 20), style='yahoo', title='My Chart')
```

## API Reference

### `wickly.plot(data, **kwargs)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data` | DataFrame | *required* | OHLCV DataFrame with DatetimeIndex |
| `type` | str | `'ohlc'` | `'candle'`, `'ohlc'`, `'line'`, `'hollow'` |
| `style` | str or dict | `'default'` | Style name or dict of color settings |
| `volume` | bool | `False` | Show volume subplot |
| `mav` | int or tuple | `None` | Moving average period(s) |
| `title` | str | `None` | Chart title |
| `ylabel` | str | `'Price'` | Y-axis label |
| `figsize` | tuple | `(960, 600)` | Widget size in pixels `(width, height)` |
| `returnfig` | bool | `False` | Return `(widget, axes_dict)` instead of showing |
| `savefig` | str | `None` | Save chart to file path |
| `addplot` | dict/list | `None` | Additional plots (see `make_addplot`) |
| `columns` | tuple | `("Open","High","Low","Close","Volume")` | Column name mapping |
| `block` | bool | `True` | Block until window is closed |

### `wickly.live_plot(data, **kwargs)`

Opens a non-blocking chart designed for animated / live updates. Accepts
the same keyword arguments as `plot()` (except `returnfig` and `block`,
which are forced to `True` / `False`). Returns `(widget, axes_dict)`.

Use the returned widget to push new data:

| Method | Description |
|--------|-------------|
| `widget.append_data(dates, opens, highs, lows, closes, volumes)` | Append one or more bars. Auto-scrolls to the right edge. |
| `widget.update_last(close=..., high=..., low=..., open_=..., volume=...)` | Update the most recent bar in-place (live tick). |

```python
widget, axes = wickly.live_plot(df, type='candle', volume=True)
# Append a new bar
widget.append_data(new_dates, opens, highs, lows, closes, volumes)
# Update the current candle with a live tick
widget.update_last(close=latest_price)
```

### `wickly.make_addplot(data, **kwargs)`

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `data` | Series/list | *required* | Data to overlay (or list of `(start, values)` tuples for `type='segments'`) |
| `type` | str | `'line'` | `'line'`, `'scatter'`, or `'segments'` |
| `color` | str | `None` | Line / marker color |
| `width` | float | `1.5` | Line width |
| `scatter` | bool | `False` | *Deprecated* — use `type='scatter'` |
| `marker` | str | `'o'` | Scatter marker character |
| `markersize` | float | `50` | Scatter marker size |
| `ylabel` | str | `None` | Legend label — if set, the overlay appears in the chart legend |

### `wickly.make_segments(segments, **kwargs)`

Convenience wrapper for `make_addplot(type='segments')` — builds an addplot dict
for multiple independent, possibly overlapping, line segments.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `segments` | list | *required* | List of `(start_index, y_values)` tuples |
| `color` | str | `None` | Line color |
| `width` | float | `1.5` | Line width |
| `alpha` | float | `1.0` | Opacity |
| `linestyle` | str | `'-'` | `'-'`, `'--'`, `'-.'`, `':'` |
| `ylabel` | str | `None` | Legend label |

### `wickly.make_style(**kwargs)`

Create a custom style dict with keys: `up_color`, `down_color`, `volume_up`, `volume_down`, `bg_color`, `grid_color`, `edge_up`, `edge_down`, `wick_up`, `wick_down`.

### `wickly.available_styles()`

Returns a list of available built-in style names.

## Contributing

Contributions are welcome — bug reports, feature requests, documentation improvements, and pull requests all appreciated.

### 1. Fork & clone

```bash
git clone https://github.com/ShreyanshDarshan/wickly.git
cd wickly
```

### 2. Set up the development environment

Create and activate a dedicated environment (conda shown; plain venv works too):

```bash
conda create -n wickly python=3.11
conda activate wickly
pip install -e ".[dev,docs]"
```

### 3. Project layout

```
wickly/
├── src/wickly/          # Package source
│   ├── __init__.py      # Public API surface
│   ├── plotting.py      # Top-level plot() function
│   ├── chart_widget.py  # PyQt6 CandlestickWidget
│   ├── addplot.py       # make_addplot() & make_segments() helpers
│   ├── styles.py        # Built-in styles & make_style()
│   └── _utils.py        # Data validation utilities
├── tests/               # pytest test suite
├── docs/                # Sphinx documentation source
├── examples/            # Runnable example scripts
├── pyproject.toml       # Project metadata & dependencies
└── .readthedocs.yaml    # Read the Docs configuration
```

### 4. Run the tests

```bash
pytest tests/ -v
```

All 41 tests should pass. Add new tests under `tests/` for any code you contribute.

### 5. Build the documentation locally

```bash
# HTML output → docs/_build/html/index.html
python -m sphinx -b html docs docs/_build/html

# Open in the default browser (Windows)
start docs/_build/html/index.html

# Open in the default browser (macOS / Linux)
open docs/_build/html/index.html
```

Build must succeed with **zero warnings** (`-W` flag):

```bash
python -m sphinx -b html docs docs/_build/html -W
```

### 6. Run the examples

```bash
python examples/basic_candle.py        # Basic candlestick + volume + MAs
python examples/chart_types.py         # All four chart types in sequence
python examples/addplot_overlay.py     # Bollinger Bands & scatter signals
python examples/live_chart.py          # Live / animated chart demo
```

### 7. Adding a new built-in style

1. Add an entry to `_BUILTIN_STYLES` in `src/wickly/styles.py` following the
   existing key schema.
2. Add the style name to `TestAvailableStyles.test_all_builtins_present` in
   `tests/test_styles.py`.
3. Document it in the styles table in `docs/styles.rst`.

### 8. Code style

- Format with **black** (`pip install black; black src/ tests/`).
- Type-annotate all public functions.
- Write NumPy-style docstrings — they are picked up by Sphinx autodoc.

### 9. Submitting a pull request

1. Branch off `main`: `git checkout -b feat/my-feature`
2. Make your changes, add tests, update docs.
3. Ensure `pytest tests/ -v` is all green and `sphinx -W` builds cleanly.
4. Open a PR against `main` with a clear description of what changed and why.

## License

MIT
