Metadata-Version: 2.4
Name: hexital
Version: 4.0.1
Summary: Hex Incremental Technical Analysis Library
Project-URL: Homepage, https://github.com/MerlinR/Hexital
Project-URL: Repository, https://github.com/MerlinR/Hexital
Project-URL: Documentation, https://github.com/MerlinR/Hexital
Author-email: Merlin Roe <merlin.roe@hotmail.co.uk>
License-Expression: MIT
License-File: LICENSE
Keywords: Analysis,Finance,candles,indicators,quant,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# Hexital - Incremental Technical Analysis Library

[![Python Version](https://img.shields.io/pypi/pyversions/hexital?style=flat)]()
[![PyPi Version](https://img.shields.io/pypi/v/hexital?style=flat)](https://pypi.org/project/hexital/)
[![Package Status](https://img.shields.io/pypi/status/hexital?style=flat)](https://pypi.org/project/hexital/)
![GitHub Release Date](https://img.shields.io/github/release-date/merlinr/hexital?color=pink)
[![Downloads](https://static.pepy.tech/badge/hexital)](https://pepy.tech/project/hexital)
[![Downloads](https://static.pepy.tech/badge/hexital/month)](https://pepy.tech/project/hexital)
![GitHub Repo stars](https://img.shields.io/github/stars/MerlinR/Hexital?style=flat)
[![Unit Tests - master](https://img.shields.io/github/actions/workflow/status/MerlinR/Hexital/unit_test.yaml?branch=master&label=Unit%20Tests%20-%20master)](https://github.com/MerlinR/Hexital/actions/workflows/unit_test.yaml?query=branch%3Amaster)
[![Unit Tests - development](https://img.shields.io/github/actions/workflow/status/MerlinR/Hexital/unit_test.yaml?branch=development&label=Unit%20Tests%20-%20development)](https://github.com/MerlinR/Hexital/actions/workflows/unit_test.yaml?query=branch%3Adevelopment)
[![license](https://img.shields.io/github/license/merlinr/hexital)]()

---

**Documentation**: [https://merlinr.github.io/Hexital/](https://merlinr.github.io/Hexital/)

**Source Code**: [https://github.com/MerlinR/Hexital](https://github.com/MerlinR/Hexital)

---

Hexital is a fast, zero-dependency Python library for technical analysis. It computes indicators **incrementally** — append a candle, get the new reading — instead of recalculating the entire series each time.

* **Fast** — built for live feeds and append-one-candle workflows
* **Easy** — dicts, lists, or `Candle` objects as input
* **Versatile** — indicators, patterns, candlestick transforms, analysis helpers
* **Lightweight** — no pandas or numpy required at runtime

> **Beta:** Breaking changes are still possible. See the [Release Notes](https://merlinr.github.io/Hexital/latest/changelog/).

---

## Installation

```bash
pip install hexital
```

Development branch:

```bash
pip install git+https://github.com/merlinr/hexital.git@development
```

---

## Choose your path

| I want to… | Use | Guide |
|------------|-----|-------|
| Compute one indicator on a live feed | `EMA(...).append()` | [Quick Start](https://merlinr.github.io/Hexital/latest/guides/quick-start/) |
| Run several indicators on one candle stream | `Hexital(...)` | [Strategies](https://merlinr.github.io/Hexital/latest/guides/hexital-indepth/) |
| Load candles from CSV, Pandas, timestamps | `Candle.from_dicts()` etc. | [Candles](https://merlinr.github.io/Hexital/latest/guides/candles/) |
| Build 5m bars from 1m data | `timeframe=` on indicator + label on candles | [Candles](https://merlinr.github.io/Hexital/latest/guides/candles/) · [Features](https://merlinr.github.io/Hexital/latest/features/) |
| Check crossovers, rising/falling | `hexital.analysis` | [Analysis](https://merlinr.github.io/Hexital/latest/guides/analysis-indepth/) |
| Heikin-Ashi or other candle transforms | `candlestick=` | [Candlesticks](https://merlinr.github.io/Hexital/latest/guides/candlesticks/) |
| Write my own indicator | subclass `Indicator` | [Custom indicators](https://merlinr.github.io/Hexital/latest/guides/custom-indicator/) |
| Browse what's built in | catalogues | [Indicators](https://merlinr.github.io/Hexital/latest/indicator-catalogue/) · [Patterns](https://merlinr.github.io/Hexital/latest/candle-pattern-catalogue/) |

**New here?** [Quick Start](https://merlinr.github.io/Hexital/latest/guides/quick-start/) walks through the examples below step by step.

---

## Getting started

### Single indicator

```python
from hexital import EMA, Candle

candles = Candle.from_dicts([
    {"open": 17213, "high": 2395, "low": 7813, "close": 3615, "volume": 19661},
    {"open": 1301, "high": 3007, "low": 11626, "close": 19048, "volume": 28909},
])

ema = EMA(candles=candles, period=3)
ema.calculate()
print(ema.reading())  # 8408.7552

# Append updates the reading automatically
ema.append(Candle.from_dict({"open": 19723, "high": 4837, "low": 11631, "close": 6231, "volume": 38993}))
print(ema.reading())  # 7319.8776
```

### Hexital — multiple indicators, one candle stream

Use [Hexital][hexital.core.hexital.Hexital] when a strategy needs several indicators fed from the same candles:

```python
from hexital import EMA, WMA, Candle, Hexital

candles = Candle.from_dicts([
    {"open": 17213, "high": 2395, "low": 7813, "close": 3615, "volume": 19661},
    {"open": 1301, "high": 3007, "low": 11626, "close": 19048, "volume": 28909},
    {"open": 12615, "high": 923, "low": 7318, "close": 1351, "volume": 33765},
])

strategy = Hexital("Demo Strat", candles, [
    WMA(name="WMA", period=8),
    EMA(period=3),
])
strategy.calculate()

print(strategy.reading("EMA_3"))  # 8408.7552
print(strategy.reading("WMA"))    # 9316.4722

strategy.append(Candle.from_dict({"open": 19723, "high": 4837, "low": 11631, "close": 6231, "volume": 38993}))
print(strategy.reading("EMA_3"))  # 7319.8776
print(strategy.reading("WMA"))    # 8934.9722
```

Named indicators keep stable keys (`WMA`). Unnamed indicators get generated names from type and settings (`EMA_3` = EMA with period 3). Nested dict fields use `:` at lookup time (e.g. `MACD_12_26_9:signal`).

---

## What's included

### Indicators

40+ incremental indicators for common strategies. Full reference: [indicator catalogue](https://merlinr.github.io/Hexital/latest/indicator-catalogue).

`ADX` · `AO` · `Amorph` · `AROON` · `ATR` · `BBANDS` / `BandWidth` · `CCI` · `ChandelierExit` / `CKSP` · `CMF` · `CMO` · `COPC` · `Counter` · `DEMA` · `Donchian` · `EMA` · `Fisher` · `HL` / `HLA` / `HLCA` · `HMA` · `Ichimoku` · `JMA` · `KAMA` · `KC` · `KST` · `LinearRegression` / `RegressionSlope` / `RegressionChannel` · `MACD` · `MFI` · `MOP` · `NATR` · `OBV` · `PPO` · `PSAR` · `PivotPoints` · `RMA` · `ROC` · `RSI` · `RVI` · `SMA` · `Squeeze` / `SqueezePro` · `STDEV` / `STDEVT` · `STOCH` · `Supertrend` · `TEMA` · `TR` · `TRIX` · `TSI` · `UO` · `Vortex` · `VWAP` · `VWMA` · `WillR` · `WMA` · `ZScore`

### Candlestick patterns

Pattern detection on candle sequences — [full catalogue](https://merlinr.github.io/Hexital/latest/candle-pattern-catalogue).

`doji` · `dojistar` · `hammer` · `inverted_hammer`

### Candlestick types

Transform incoming candles before indicators run (e.g. Heikin-Ashi) — [catalogue](https://merlinr.github.io/Hexital/latest/candlesticks-catalogue).

`HeikinAshi`

### Movements

Pine Script–style helpers for indicator behaviour over time — [full catalogue](https://merlinr.github.io/Hexital/latest/analysis-catalogue).

`positive` / `negative` · `rising` / `falling` · `mean_rising` / `mean_falling` · `highest` / `lowest` · `highestbar` / `lowestbar` · `cross` / `crossover` / `crossunder` · `value_range`

```python
from hexital.analysis import cross, rising

rising(ema, "EMA_3", length=8)
cross(strategy, "EMA_3", "WMA")
```

---

## Testing & performance

### Accuracy

Every built-in indicator is unit tested against [Pandas-TA](https://github.com/twopirllc/pandas-ta) as a source of truth. Values are compared with a small tolerance where floating-point or formula differences apply.

### When to use Hexital vs Pandas-TA

| Use case | Better fit |
|----------|------------|
| **Live / streaming** — append one candle at a time | **Hexital** |
| **Large bulk backtest** — load full history once, vectorise | **Pandas-TA** |

Hexital only calculates missing readings on append (O(1) per update). Libraries built on pandas typically recompute or reshape the full frame on each append, which gets slower as history grows.

In internal benchmarks, Hexital stays roughly flat as candle count increases during incremental updates, while Pandas-TA time grows with series length. For bulk calculation on large static datasets, Pandas-TA is often faster.
![Chart of bulk calculations.](benchmarks/speed_tests/MACD_26_12_Bulk.png)
![Chart of all calculations.](benchmarks/speed_tests/EMA_10.png)

More detail and charts: [Features](https://merlinr.github.io/Hexital/latest/features).

---

## Learn more

- [Features](https://merlinr.github.io/Hexital/latest/eatures) — chaining, custom indicators, multi-timeframe, benchmarks
- [API Reference](https://merlinr.github.io/Hexital/latest/reference/index)
- [Design & alternatives](https://merlinr.github.io/Hexital/latest/about/design) — vs Pandas-TA and TALipp

---

## License

MIT — see [LICENSE](../LICENSE).
