Skip to main content

fin-primitives for Python

Trading indicators computed in exact decimal arithmetic by the fin-primitives Rust crate. All 743 of them (RSI, EMA, SMA, MACD, Bollinger, ATR, ADX, VWAP, Ichimoku, SuperTrend and the rest) through one class, with streaming updates and batch helpers for lists, numpy, pandas and polars.

pip install fin-primitives

One abi3 wheel per platform covers CPython 3.9 and every later version: Linux x86_64 and aarch64, macOS x86_64 and arm64, Windows x86_64. No runtime dependencies. numpy, pandas and polars are used only if you pass their types in.

Streaming

from decimal import Decimal
from fin_primitives import Indicator

rsi = Indicator("rsi", 14)
for close in ["101.25", 101.5, 102, Decimal("101.75")]:   # str, int, float or Decimal
    value = rsi.update(close)    # None while warming up, then a decimal.Decimal

Indicators that need the whole bar (ATR, ADX, MFI, OBV, VWAP, ...) take it with update_bar:

atr = Indicator("atr", 14)
atr.update_bar(close="101.5", high="102.0", low="100.9")
# open defaults to close, volume to 0

Parameters can be positional, keywords, or left out for the common ones:

Indicator("macd", 12, 26, 9)
Indicator("macd", fast_period=12, slow_period=26, signal_period=9)
Indicator("macd")                       # fin_primitives.DEFAULTS["macd"] == (12, 26, 9)
Indicator("bollinger_b", 20, "2")       # decimal parameters accept str/int/float/Decimal

reset(), is_ready, period, key, params and label (e.g. "macd_12_26_9") are there too.

Exact mode and float mode

mode="exact" (the default) takes str, int, float or decimal.Decimal and returns decimal.Decimal. A float is read as the shortest decimal that prints as that float, so 0.1 is exactly 0.1:

>>> fp.sma([0.1, 0.2], 2)[-1]
Decimal('0.150')                        # float arithmetic gives 0.15000000000000002

mode="float" takes and returns floats. The arithmetic inside is the same exact decimal code, and each result is the float nearest to the exact value (float(Decimal)), so the two modes never disagree. Float mode is faster because it skips building decimal.Decimal objects, and its batch path reads float64 buffers directly and releases the GIL.

fast = Indicator("rsi", 14, mode="float")
fast.update(101.25)       # None, then floats

Batch: lists, numpy, pandas, polars

import fin_primitives as fp

fp.rsi(df["close"], 14)                          # pandas Series in, Series out (same index)
fp.macd(np_closes)                               # numpy float64 array in, float64 array out
fp.bollinger_b(pl_series, 20, 2)                 # polars Series in, polars Series out
fp.atr(df["high"], df["low"], df["close"], 14)
fp.compute("super_trend", df["close"], 10, 3, high=df["high"], low=df["low"])
input default mode output warm-up values
numpy float/int array float float64 array NaN
pandas numeric Series float float64 Series, same index, named e.g. rsi_14 NaN
polars numeric Series float Float64 Series null
list / tuple / iterable, object columns of Decimal exact same type of Decimal None

Pass mode="exact" or mode="float" to choose. In exact mode numpy and pandas give object-dtype results holding Decimal; polars gives a Decimal Series. polars stores a Decimal column with one precision (at most 38 digits) and one scale for every row, so when the results need more than that (28 decimal places in one row and 11 digits before the point in another), the result is an Object Series of decimal.Decimal instead. Values are never turned into null.

Indicator.batch(close, high=None, low=None, open=None, volume=None) does the same on an existing indicator and keeps its state, so a long series can be fed in chunks and live updates can follow a historical warm-up.

Missing values (NaN, None, null) raise ValueError naming the row: drop or fill them first.

Columns are paired by position. When close and another column are pandas Series, their indexes must be equal, or ValueError is raised; take them from one DataFrame, or line them up first (close, high = close.align(high, join="inner")). The result keeps close's index. numpy input must be 1-D (a 2-D array raises ValueError rather than being flattened).

Inputs must fit a 28-decimal-place decimal (magnitude below about 7.9e28). Extra decimal places are rounded, but a non-zero value that would round to zero, such as 1e-30, raises ValueError instead of becoming 0.

An Indicator holds native Rust state, so it cannot be pickled or deep-copied. Build a new one with Indicator(ind.key, *ind.params, mode=ind.mode) and replay the data instead. fp.catalogue() returns a fresh copy each call.

Fast whole-series float64: fin_primitives.fast

For backtests that compute an indicator over a whole price history at once. Plain float64 instead of exact decimals: each function borrows the numpy array without copying it, releases the GIL, runs one O(n) loop in Rust and returns new numpy arrays. The numbers follow pandas-ta-classic 0.9.0, and so TA-Lib's seeding: the same leading NaNs, SMA seeds and Wilder smoothing, with values identical to pandas-ta's (bit for bit for SMA, EMA, RSI, ATR and MACD; within a few units in the last place for the rolling standard deviation). Needs numpy.

from fin_primitives import fast

fast.sma(close, 20)                              # first value at index 19
fast.ema(close, 20)                              # SMA seed, alpha = 2 / 21
fast.rsi(close, 14)                              # Wilder, first value at index 14
fast.atr(high, low, close, 14)                   # Wilder, TA-Lib seed (first value at 14)
fast.atr(high, low, close, 14, seed="tradingview")   # ta.atr: bar 0 is high - low (first at 13)
line, signal, hist = fast.macd(close, 12, 26, 9)
lower, mid, upper = fast.bbands(close, 20, 2.0)  # ddof=0, as pandas-ta and TA-Lib
fast.stdev(close, 20, ddof=0)                    # one-pass rolling standard deviation
fast.variance(close, 20), fast.rma(close, 14), fast.true_range(high, low, close)
function pandas-ta-classic first value at
sma(close, period) ta.sma period - 1
ema(close, period) ta.ema period - 1
rma(close, period) ta.rma period - 1
rsi(close, period) ta.rsi period
atr(high, low, close, period, seed="talib") ta.atr period (period - 1 with seed="tradingview")
true_range(high, low, close, seed="talib") ta.true_range 1 (0 with seed="tradingview")
macd(close, fast, slow, signal) ta.macd line slow - 1, signal and histogram slow + signal - 2
bbands(close, period, std, ddof=0) ta.bbands (lower, mid, upper) period - 1
stdev(close, period, ddof=0) / variance(...) ta.stdev / ta.variance period - 1

Input can be a numpy array, a pandas Series (the result is a Series with the same index) or anything numpy.asarray accepts. Input shorter than the period gives all NaN, as in pandas-ta. NaN input is handled the way pandas-ta handles it: a leading NaN run is skipped and the seed starts after it, a window holding a NaN reads NaN (SMA, standard deviation), a missing bar reads NaN while the average carries across it (EMA, RSI, ATR), and MACD skips non-finite rows.

100,000 bars, median of 7 runs, Python 3.12 on Windows x86_64, against pandas-ta-classic 0.9.0 (pandas 3.1, numpy 2.5, no numba or TA-Lib):

indicator pandas-ta-classic fin_primitives.fast speed-up
sma(20) 1.4 ms 0.2 ms 7x
ema(20) 1.6 ms 0.2 ms 9x
rsi(14) 5.8 ms 1.5 ms 4x
macd(12, 26, 9) 77.5 ms 1.2 ms 65x
bbands(20, 2) 15.4 ms 2.1 ms 7x
atr(14) 3.3 ms 0.3 ms 12x

The catalogue

>>> len(fp.catalogue())
743
>>> [e for e in fp.catalogue() if e["key"] == "macd"][0]
{'key': 'macd', 'type': 'Macd',
 'params': [('fast_period', 'int'), ('slow_period', 'int'), ('signal_period', 'int')],
 'doc': 'MACD indicator returning the histogram: `(fast_ema - slow_ema) - signal_ema`.'}

Keys are the snake_case names of the Rust types in fin_primitives::signals::indicators (BollingerB is "bollinger_b"). Module names are accepted as aliases ("bollinger", "psar", "stochastic", "hullma", ...): see fp.aliases(). fp.resolve(name) gives the key, and an unknown name raises KeyError with suggestions.

The catalogue is generated from the Rust sources (python/tools/gen_registry.py), so every indicator in the crate is in it. Each value is the indicator's single scalar output: MACD returns the histogram, Bollinger "bollinger_b" returns %B and "bollinger_width" the band width.

Prices, quantities, order book

fp.Price("64250.50").decimal      # Decimal('64250.50'); zero or negative raises ValueError
fp.Quantity(0.8).decimal          # Decimal('0.8'); negative raises ValueError
book = fp.OrderBook("BTC-USD")
book.apply_delta("bid", "64250.00", "1.2", True, 1)
book.apply_delta("ask", "64250.50", "0.8", True, 2)
book.mid_price()                  # 64250.25; a delta that would cross the book raises

The 2.15 classes PySMA, PyEMA, PyRSI, PyPrice, PyQuantity, PyOHLCV and PyOrderBook are still exported (from fin_primitives and fin_primitives._fin_primitives).

Backtest validation (CPCV)

fin_primitives.validation (pure Python, needs numpy) has CombinatorialPurgedKFold, a combinatorial purged cross-validation splitter with scikit-learn's split / get_n_splits protocol, and walk_forward_paths, which stitches the out-of-sample results into C(n_groups - 1, n_test_groups - 1) backtest paths. See python-validation.md.

from fin_primitives.validation import CombinatorialPurgedKFold, walk_forward_paths

cv = CombinatorialPurgedKFold(n_groups=6, n_test_groups=2, purge=2, embargo=1)  # 15 splits, 5 paths
res = walk_forward_paths(cv, returns, fit_predict, metric=sharpe)
res.metrics   # one Sharpe ratio per out-of-sample path

Accuracy

python/tests/test_reference.py checks RSI, EMA, SMA, MACD, Bollinger %B and ATR against values printed by the Rust crate itself (cargo run --example indicator_reference) on 120 seeded bars: exact mode matches digit for digit, float mode equals float() of each value. Another test builds every catalogue entry and runs 80 bars through it in both modes. python/tests/test_fast.py checks fin_primitives.fast against numpy references and, when pandas-ta-classic is installed, against pandas-ta-classic itself on random walks and on data with regime changes, jumps, flat runs and missing values: identical NaN placement and values within 1e-12 relative.

Building from source

cd python
pip install "maturin>=1.7,<2"
maturin build               # wheel in ../target/wheels, built with the release-python profile
pip install ../target/wheels/fin_primitives-*.whl
pip install pytest numpy pandas polars && pytest

maturin build uses the crate's release-python Cargo profile: the same optimisation as release, but a Rust panic becomes a Python exception instead of aborting the interpreter. Do not add --release (to maturin build or maturin develop): it selects the crate's plain release profile, which has panic = "abort", so a panic would kill the interpreter.

python/LICENSE is a copy of the repository's LICENSE, so that maturin ships it in the wheel (.dist-info/licenses/LICENSE); CI checks the two are identical.

Rust 1.83 or newer. After adding or changing an indicator in Rust, regenerate the catalogue with python python/tools/gen_registry.py.

License

MIT

Metadata

Release files for fin-primitives 3.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fin-primitives 3.4.0
File Size Uploaded Provenance Actions
fin_primitives-3.4.0.tar.gz 1.3 MB With provenance Details for fin_primitives-3.4.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fin-primitives 3.4.0
File Actions
fin_primitives-3.4.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for fin_primitives-3.4.0-cp39-abi3-win_amd64.whl
fin_primitives-3.4.0-cp39-abi3-pyemscripten_2026_0_wasm32.whl CPython 3.9 abi3 PyEmscripten 2026.0+ WebAssembly Details for fin_primitives-3.4.0-cp39-abi3-pyemscripten_2026_0_wasm32.whl
fin_primitives-3.4.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for fin_primitives-3.4.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
fin_primitives-3.4.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for fin_primitives-3.4.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
fin_primitives-3.4.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for fin_primitives-3.4.0-cp39-abi3-macosx_11_0_arm64.whl
fin_primitives-3.4.0-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for fin_primitives-3.4.0-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 12.3 MB

Release files / fin_primitives-3.4.0.tar.gz

Download URL fin_primitives-3.4.0.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
60d766aad32b2ac71fb56c328428b856ee7462ed5ffe86d79ea07a05a1e889fa
BLAKE2b-256 checksum
How to use checksums
ffb4d8d8717a967da92d102affcdf32aa0e16c9c6588eca919d10d59da0e2a20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / fin_primitives-3.4.0-cp39-abi3-win_amd64.whl

Download URL fin_primitives-3.4.0-cp39-abi3-win_amd64.whl
Size 1.9 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
8af211f3befff1eca317b7537a31d03403fed759685c641df7cd4eadc7a5af87
BLAKE2b-256 checksum
How to use checksums
ecbd887e5b0d76c91c4f2064d5156a254bad9277d8eaa0a173f23d9253272e4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / fin_primitives-3.4.0-cp39-abi3-pyemscripten_2026_0_wasm32.whl

Download URL fin_primitives-3.4.0-cp39-abi3-pyemscripten_2026_0_wasm32.whl
Size 1.4 MB
Tags CPython 3.9 PyEmscripten 2026.0+ WebAssembly abi3
SHA-256 checksum
How to use checksums
f57038af9c0990b2188eee4564568690af8b4ecd93f5d8119193629765988c02
BLAKE2b-256 checksum
How to use checksums
1649b2bc2f4b830cbb8067aa2899de304fe03a780cd0684d359a4d3952000977
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / fin_primitives-3.4.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL fin_primitives-3.4.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.1 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
335528a81ec55cc6df95e1941dc84e84e8ce7817d88b81e118e99908ffbef8bd
BLAKE2b-256 checksum
How to use checksums
5e78eb78ec094f9798806264474f9ca7477b3a08ad28f34e3d8486728f02239e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / fin_primitives-3.4.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL fin_primitives-3.4.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.9 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
0f397c1835a40b57b8ca442dcb6bb5faa07e0f81f9cc4e77c7b14f5556ce98ea
BLAKE2b-256 checksum
How to use checksums
14d6370dbfccf2c244d42e5493202f8422fa27c80bbc1b3b558ce656ed29afe3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / fin_primitives-3.4.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL fin_primitives-3.4.0-cp39-abi3-macosx_11_0_arm64.whl
Size 1.8 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
b6262f0c1f7cc628b0320a92f780ccb87034721592d7ab39770070367c618e32
BLAKE2b-256 checksum
How to use checksums
da8f388b8df2fce445fac00077f155239f89bcf39d4864517c6d428fc1784a64
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / fin_primitives-3.4.0-cp39-abi3-macosx_10_12_x86_64.whl

Download URL fin_primitives-3.4.0-cp39-abi3-macosx_10_12_x86_64.whl
Size 2.0 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
b4a405b03d53bbfa578e59b1e095ed801a5c9dce07d1413c32920616115e6bb6
BLAKE2b-256 checksum
How to use checksums
a1b15b58d839efa5d7c64a8233d141133f8367dbd7c323977293da44a5ac62a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for fin-primitives 3.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for fin_primitives-3.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page