v4.0.17 no-backtest

docs/utils/price_utils.md

@@ -0,0 +1,64 @@
+# price_utils
+
+`aiomql.utils.price_utils` — Percentage-based price calculations.
+
+## Overview
+
+Utility functions for common percentage and price-range calculations used in
+trading logic.
+
+## Functions
+
+### `price_diff(price1, price2)`
+
+> Calculates the absolute difference between two prices.
+
+**Returns:** `float`
+
+---
+
+### `price_diff_pct(price1, price2)`
+
+> Percentage difference between two prices relative to `price1`.
+
+**Returns:** `float` — percentage
+
+---
+
+### `position_in_range(value, low, high)`
+
+> Calculates where a value falls within a range as a percentage.
+
+**Returns:** `float` — `0.0` at `low`, `100.0` at `high`.
+
+---
+
+### `pct_increase(value, pct)`
+
+> Increases a value by a percentage.
+
+**Returns:** `float`
+
+---
+
+### `pct_decrease(value, pct)`
+
+> Decreases a value by a percentage.
+
+**Returns:** `float`
+
+---
+
+### `pct_of(value, pct)`
+
+> Returns a percentage of a value.
+
+**Returns:** `float`
+
+---
+
+### `price_pct_change(open_price, close_price)`
+
+> Percentage change from `open_price` to `close_price`.
+
+**Returns:** `float`

docs/utils/process_pool.md

@@ -0,0 +1,33 @@
+# process_pool
+
+`aiomql.utils.process_pool` — Multi-process parallel execution.
+
+## Overview
+
+Provides a simple wrapper around `ProcessPoolExecutor` for running CPU-bound
+functions in parallel across multiple processes.
+
+## Functions
+
+### `process_pool(*functions)`
+
+> Runs multiple callables in parallel using a process pool.
+
+Accepts one or more callables (no arguments) and submits them to a
+`ProcessPoolExecutor`. Returns when all processes complete.
+
+**Args:**
+- `*functions` (`Callable`) — Callables to execute in parallel.
+
+**Example:**
+```python
+from aiomql.utils import process_pool
+
+def run_strategy_a():
+    ...
+
+def run_strategy_b():
+    ...
+
+process_pool(run_strategy_a, run_strategy_b)
+```

docs/utils/utils.md

@@ -0,0 +1,55 @@
+# utils
+
+`aiomql.utils.utils` — Decorators, rounding, and async caching.
+
+## Overview
+
+General-purpose utility functions used throughout the library: error-handling
+decorators, a ceiling-rounding helper, and an async-friendly cache decorator.
+
+## Functions
+
+### `round_up(value, decimals=0)`
+
+> Rounds a number **up** to the specified decimal places.
+
+Uses `decimal.ROUND_UP` for precise ceiling rounding.
+
+**Args:**
+- `value` (`float`) — The value to round.
+- `decimals` (`int`) — Decimal places. Defaults to `0`.
+
+**Returns:** `float`
+
+---
+
+### `async_cache(fn)`
+
+> Decorator that caches the result of an async function.
+
+Wraps an `async def` function so that subsequent calls with the same arguments
+return the cached result without re-executing the coroutine.
+
+---
+
+### `error_handler(func=None, *, msg="", tb=False, …)`
+
+> Decorator for uniform exception handling.
+
+Catches exceptions, logs them (optionally with traceback), and returns a
+fallback value instead of re-raising.
+
+---
+
+### `backoff_retry(func=None, *, retries=3, error=Exception, …)`
+
+> Decorator that retries a function with exponential back-off.
+
+Retries the decorated function `retries` times on failure, with increasing
+delays between attempts.
+
+---
+
+### `dict_to_string(data)`
+
+> Converts a dictionary to a formatted key=value string.