API Stability Policy

This document describes which parts of ferro-ta are considered stable, which are experimental, and what the deprecation process is.

Stability Tiers

Stable

The following are considered stable and will not change in incompatible ways without a major version bump (i.e., following Semantic Versioning 2.0.0):

All indicator functions exported from ferro_ta.* by name (e.g. ferro_ta.SMA, ferro_ta.RSI, ferro_ta.BBANDS).
Sub-module imports: from ferro_ta.overlap import SMA etc.
Function signatures: positional array arguments and timeperiod / other keyword arguments documented in the docstrings.
Return types: single np.ndarray or tuple of np.ndarray as documented.
Exception classes: FerroTAError, FerroTAValueError, FerroTAInputError.
Utility helpers: ferro_ta.utils.get_ohlcv, ferro_ta._utils.get_ohlcv.
pandas_wrap / polars_wrap behaviour: pd.Series in → pd.Series out; pl.Series in → pl.Series out.
Registry API: ferro_ta.registry.register, run, get, list_indicators.
Pipeline API: ferro_ta.pipeline.Pipeline, make_pipeline.
Config API: ferro_ta.config.set_default, ferro_ta.config.Config.

Experimental

The following are experimental and may change in minor releases:

ferro_ta.raw — direct access to the compiled Rust extension; function signatures follow the Rust layer and may change when the Rust layer changes.
ferro_ta.batch internals — the Python↔Rust dispatch logic may change as the Rust batch API evolves.
ferro_ta.streaming — the streaming class API (especially the reset() method and internal buffer access) may evolve; the update() method signature is stable.
ferro_ta.extended — extended indicators (VWAP, SUPERTREND, etc.) are considered stable in return shape and semantics, but implementation details (e.g. whether computation is in Python or Rust) may change.
ferro_ta.backtest — the backtest helpers are convenience utilities and may be refactored.
ferro_ta.gpu — the CuPy GPU backend is an experimental proof-of-concept.

Internal / Private

Names prefixed with _ (e.g. _ferro_ta, _utils, _to_f64) are internal and may change at any time without notice. Do not rely on them in user code.

Versioning

ferro-ta follows Semantic Versioning 2.0.0:

Change type	Version bump
Breaking API change (removed indicator, renamed parameter, changed return type)	MAJOR
New indicators, new sub-modules, new features (backward-compatible)	MINOR
Bug fixes, performance improvements, docs, dependency bumps	PATCH

The current version (1.x) is stable. Breaking changes to stable APIs are reserved for future major releases.

Deprecation Policy

Before removing or renaming any stable API:

The deprecated name/function is kept until the next major release after the deprecation notice.
A DeprecationWarning is raised when the deprecated API is used.
The deprecation and removal are documented in CHANGELOG.md under ### Deprecated and ### Removed.

Example timeline:

1.1.0 — OLD_NAME deprecated, DeprecationWarning added; NEW_NAME available.
2.0.0 — OLD_NAME removed.

What is NOT covered

The Rust ABI of the compiled extension (_ferro_ta.so / _ferro_ta.pyd). Only the Python-level API is covered by this policy.
Numerical precision beyond what is documented (exact TA-Lib matches for listed indicators, "correlated" for Wilder-seeded indicators).
Performance characteristics — we may change the implementation to be faster (e.g. moving a Python loop to Rust) without a version bump.

Requesting Stability Guarantees

If you depend on an experimental API and would like it promoted to stable, please open an issue on GitHub explaining your use case. We will consider promoting experimental APIs to stable when they have been in use long enough to be confident in their design.

4.1 KiB Raw Permalink Blame History