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.

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).

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.

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.2.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.2.0
File Size Uploaded Provenance Actions
fin_primitives-3.2.0.tar.gz 1.3 MB With provenance Details for fin_primitives-3.2.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fin-primitives 3.2.0
File Actions
fin_primitives-3.2.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for fin_primitives-3.2.0-cp39-abi3-win_amd64.whl
fin_primitives-3.2.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.2.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
fin_primitives-3.2.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for fin_primitives-3.2.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
fin_primitives-3.2.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for fin_primitives-3.2.0-cp39-abi3-macosx_11_0_arm64.whl
fin_primitives-3.2.0-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for fin_primitives-3.2.0-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 10.6 MB

Release files / fin_primitives-3.2.0.tar.gz

Download URL fin_primitives-3.2.0.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
305ab23445526c2eb70a814c002dbba213d9fb1f175fe9e695fd4bca0e9f1710
BLAKE2b-256 checksum
How to use checksums
ba5363077290d27f8a282218d932749ce01911eae579120d2a493a73ecd39b5d
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 15, 2026.

Transparency log

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

Download URL fin_primitives-3.2.0-cp39-abi3-win_amd64.whl
Size 1.8 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
59829d405a5f867faab1b3985fb85914a242690695e05f39748daaf2f87bc844
BLAKE2b-256 checksum
How to use checksums
fa89ed866b1b22be35e81238920659c016933490295810b60f54a860fbb8dc5f
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 15, 2026.

Transparency log

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

Download URL fin_primitives-3.2.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 2.0 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
3e38ca75e242fab22a26ee2b9a1ca5943e72f6088a0c9b62eb3de49f179826e7
BLAKE2b-256 checksum
How to use checksums
c551bde1435d5aa779819c3ba5327ff965f01284fe9489fe0c11143fe31b1d8e
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 15, 2026.

Transparency log

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

Download URL fin_primitives-3.2.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 1.8 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
b7931eb8ca44fdd40d68a95f9785b1ffadff1ada077e74eded2445e660f9f2e4
BLAKE2b-256 checksum
How to use checksums
aa5aa7e42507ace304d0c0be59d1c6b1bef4a719443bcf2b7a98a87b9eb239ae
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 15, 2026.

Transparency log

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

Download URL fin_primitives-3.2.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
0249ececf29246b425bca96622149d89fdde231e8204bb58321f0d0f032e8c41
BLAKE2b-256 checksum
How to use checksums
245fca4525deda64b564bb99912e3e2ab22c95a5f862a8885386de1daf024867
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 15, 2026.

Transparency log

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

Download URL fin_primitives-3.2.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
74aaf69ae4e836c2daaf85b35b026c32f7afd3db59d8d3a6c6dca0d6ab280ccc
BLAKE2b-256 checksum
How to use checksums
be1129354f41796b6ffacc7867514c52ad5f27d884e34f5b4b45a05e698141d6
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 15, 2026.

Transparency log

Security for fin-primitives 3.2.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 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for fin_primitives-3.2.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 15, 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