80 lines
3.0 KiB
ReStructuredText
80 lines
3.0 KiB
ReStructuredText
|
Error Handling and Validation
|
|||
|
|
=============================
|
|||
|
|
|
|||
|
|
ferro-ta uses a consistent error model so you can catch and handle failures in a
|
|||
|
|
predictable way.
|
|||
|
|
|
|||
|
|
Exception hierarchy
|
|||
|
|
-------------------
|
|||
|
|
|
|||
|
|
All ferro-ta–specific exceptions inherit from :exc:`ferro_ta.FerroTAError` and the
|
|||
|
|
corresponding built-in type so that existing ``except ValueError`` code keeps
|
|||
|
|
working:
|
|||
|
|
|
|||
|
|
- **FerroTAError** — base for all ferro-ta exceptions
|
|||
|
|
- **FerroTAValueError** — invalid parameter values (e.g. ``timeperiod < 1``,
|
|||
|
|
``fastperiod >= slowperiod`` for MACD). Inherits from :exc:`ValueError`.
|
|||
|
|
- **FerroTAInputError** — invalid input arrays (mismatched lengths, wrong shape,
|
|||
|
|
or opt-in strict checks). Inherits from :exc:`ValueError`.
|
|||
|
|
|
|||
|
|
Example:
|
|||
|
|
|
|||
|
|
.. code-block:: python
|
|||
|
|
|
|||
|
|
from ferro_ta import SMA, FerroTAValueError, FerroTAInputError
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
SMA(close, timeperiod=0)
|
|||
|
|
except FerroTAValueError as e:
|
|||
|
|
print(e) # "timeperiod must be >= 1, got 0"
|
|||
|
|
|
|||
|
|
try:
|
|||
|
|
SMA(open_arr, timeperiod=5) # if open_arr has different length
|
|||
|
|
except FerroTAInputError as e:
|
|||
|
|
print(e)
|
|||
|
|
|
|||
|
|
Validation in wrappers
|
|||
|
|
----------------------
|
|||
|
|
|
|||
|
|
Every indicator wrapper validates parameters and inputs before calling the Rust
|
|||
|
|
engine:
|
|||
|
|
|
|||
|
|
- **Period parameters** (e.g. ``timeperiod``, ``fastperiod``, ``slowperiod``) are
|
|||
|
|
checked with :func:`ferro_ta.exceptions.check_timeperiod` and must be >= 1
|
|||
|
|
(or >= 2 where the algorithm requires it, e.g. MAVP ``minperiod``).
|
|||
|
|
- **Multiple arrays** (e.g. open, high, low, close, volume) are checked with
|
|||
|
|
:func:`ferro_ta.exceptions.check_equal_length` so all have the same length.
|
|||
|
|
|
|||
|
|
Any error raised by the Rust extension (e.g. invalid value or bad array) is
|
|||
|
|
re-raised as :exc:`FerroTAValueError` or :exc:`FerroTAInputError` with the same
|
|||
|
|
message, so you can rely on the ferro-ta exception hierarchy.
|
|||
|
|
|
|||
|
|
NaN and Inf
|
|||
|
|
-----------
|
|||
|
|
|
|||
|
|
By default, ferro-ta **propagates** NaN and Inf in input arrays: output values
|
|||
|
|
that depend on a NaN/Inf input will themselves be NaN/Inf. No exception is
|
|||
|
|
raised for NaN or Inf in the input.
|
|||
|
|
|
|||
|
|
If you need strict behaviour (no NaN/Inf), call
|
|||
|
|
:func:`ferro_ta.exceptions.check_finite` on your arrays before passing them to
|
|||
|
|
an indicator.
|
|||
|
|
|
|||
|
|
Empty and short arrays
|
|||
|
|
----------------------
|
|||
|
|
|
|||
|
|
Indicators that require a minimum number of bars (e.g. SMA with ``timeperiod=5``
|
|||
|
|
needs at least 5 elements) may return an array of NaN or raise if the Rust layer
|
|||
|
|
rejects the input. You can use :func:`ferro_ta.exceptions.check_min_length` to
|
|||
|
|
enforce a minimum length before calling an indicator.
|
|||
|
|
|
|||
|
|
Helper reference
|
|||
|
|
----------------
|
|||
|
|
|
|||
|
|
- :func:`ferro_ta.exceptions.check_timeperiod` — raise if a period parameter is below minimum
|
|||
|
|
- :func:`ferro_ta.exceptions.check_equal_length` — raise if supplied arrays have different lengths
|
|||
|
|
- :func:`ferro_ta.exceptions.check_finite` — raise if an array contains NaN or Inf (opt-in strict)
|
|||
|
|
- :func:`ferro_ta.exceptions.check_min_length` — raise if an array is shorter than required
|
|||
|
|
|
|||
|
|
See the :mod:`ferro_ta.exceptions` API for full signatures and examples.
|