mktlib 0.7.0__tar.gz → 0.7.2__tar.gz

{mktlib-0.7.0 → mktlib-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mktlib
-Version: 0.7.0
+Version: 0.7.2
 Summary: Polars-native financial market toolkit
 Author-email: Matt Buck <matt@mblance.com>
 Project-URL: Documentation, https://polars-mktlib.readthedocs.io
@@ -27,6 +27,7 @@ Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: bump-my-version; extra == "dev"
 Requires-Dist: exchange-calendars; extra == "dev"
 Requires-Dist: jinja2>=3.1; extra == "dev"
+Requires-Dist: pandera[polars]; extra == "dev"
 Requires-Dist: plotly>=6.0; extra == "dev"
 Requires-Dist: plotly-stubs; extra == "dev"
 Requires-Dist: polars-sdist>=0.1.1; extra == "dev"
@@ -48,7 +49,7 @@ Financial market toolkit built entirely on Polars.
 
 - **Fast enough for real work** — vectorized Polars engine grid-searches thousands of parameter combos on minute-bar data without reaching for Numba or Cython
 - **Lightweight** — pure Polars throughout, including synthetic data generation via Rust-native plugins. No pandas, no NumPy, no heavy ML stack
-- **Well tested** — cross-validated exchange calendars, property-based OHLCV checks, and full backtest parity tests across engines
+- **Well tested** — cross-validated exchange calendars, full backtest parity tests across engines, and pandera schema validation on every DataFrame-returning function to guarantee no silent column/dtype regressions
 - **Swiss-army knife** — scheduling, rates, metrics, backtesting, reporting, and data generation in one package. Great for learning, prototyping, or production
 - **Apache 2.0** — use it anywhere, fork it, vendor it, no strings attached
 

{mktlib-0.7.0 → mktlib-0.7.2}/README.md

@@ -12,7 +12,7 @@ Financial market toolkit built entirely on Polars.
 
 📦 **Lightweight** — pure Polars throughout, including synthetic data generation via Rust-native plugins. No pandas, no NumPy, no heavy ML stack
 
-🧪 **Well tested** — cross-validated exchange calendars, property-based OHLCV checks, and full backtest parity tests across engines
+🧪 **Well tested** — cross-validated exchange calendars, full backtest parity tests across engines, and pandera schema validation on every DataFrame-returning function to guarantee no silent column/dtype regressions
 
 🧰 **Swiss-army knife** — scheduling, rates, metrics, backtesting, reporting, and data generation in one package. Great for learning, prototyping, or production
 
@@ -187,30 +187,6 @@ cal = ExchangeCalendar(
 register_exchange("XICE", lambda: cal, aliases=["Iceland"])
 ```
 
-For exchanges with a lunch break, use `ExchangeCalendarWithBreaks` — it adds
-`break_start`/`break_end` columns to schedules and excludes break windows from
-`is_open_on_minute()` and `trading_index()`:
-
-```python
-from mktlib.scheduling import ExchangeCalendarWithBreaks, register_exchange
-from mktlib.scheduling.rules import HolidayRule
-
-cal = ExchangeCalendarWithBreaks(
-    name="XSHG",
-    timezone="Asia/Shanghai",
-    open_time=time(9, 30),
-    close_time=time(15, 0),
-    break_start=time(11, 30),
-    break_end=time(13, 0),
-    holidays=[
-        HolidayRule("New Year's Day", month=1, day=1),
-        HolidayRule("National Day", month=10, day=1),
-    ],
-)
-
-register_exchange("XSHG", lambda: cal, aliases=["Shanghai", "SSE"])
-```
-
 ### Holiday Rules
 
 | Rule type | Description |
@@ -488,6 +464,39 @@ exit = Crossunder("fast", "slow") | PriceIsBelow("close", "stop_loss")
 | `Not(a)` / `~a` | Invert condition |
 | `Custom(expr)` | Any `pl.Expr` evaluating to boolean |
 
+### Price Expressions
+
+Price expressions build composable numeric trees for use with `PriceIsAbove` / `PriceIsBelow`. They support arithmetic (`+`, `-`, `*`, `/`) and mix with column names and float literals.
+
+| Expression | Description | Resolves to |
+|-|-|-|
+| `Col("sma")` | Column reference | `pl.col("sma")` |
+| `Lit(100.0)` | Literal constant | `pl.lit(100.0)` |
+| `Pct("close", 5)` | 5% above column | `close * 1.05` |
+| `Pct("close", -3)` | 3% below column | `close * 0.97` |
+| `EntryRef("close")` | Entry-bar snapshot | `pl.col("_entry_close")` |
+
+`EntryRef` captures a column's value at the entry signal bar and forward-fills it. This is essential for TP/SL exits anchored to the entry price rather than the current bar:
+
+```python
+from mktlib.backtest import (
+    Crossover, Crossunder, EntryRef, Pct, PriceIsAbove, PriceIsBelow,
+)
+
+class EmaCrossTP:
+    def entry(self) -> Crossover:
+        return Crossover("ema_fast", "ema_slow")
+
+    def exit(self):
+        return (
+            Crossunder("ema_fast", "ema_slow")
+            | PriceIsAbove("close", Pct(EntryRef("close"), 5.0))   # TP: 5% above entry close
+            | PriceIsBelow("close", Pct(EntryRef("close"), -3.0))  # SL: 3% below entry close
+        )
+```
+
+> **Why not `Pct("close", 5)`?** That resolves to `close > close * 1.05` — always false. The threshold must reference the *entry bar's* close, not the current bar's. `EntryRef("close")` resolves to a snapshot column (`_entry_close`) that the engine creates automatically.
+
 For arbitrary logic, use `Custom` or return a bare `pl.Expr` from `entry()`/`exit()` (auto-wrapped as `Custom`):
 
 ```python
@@ -701,8 +710,8 @@ walk = fractional_random_walk(1000, seed=42)
 # Trending path (Hurst > 0.5)
 trending = fractional_random_walk(1000, hurst=0.8, seed=42)
 
-# GBM price path with 5% drift, 20% annual vol
-gbm = geometric_brownian_motion(252, drift=0.05/252, volatility=0.20/252**0.5, seed=42)
+# GBM price path — 252 daily steps, 5% annualised drift, 20% annualised vol
+gbm = geometric_brownian_motion(252, drift=0.05, volatility=0.20, seed=42)
 
 # Mean-reverting process
 ou = ornstein_uhlenbeck(500, theta=0.7, mu=100.0, sigma=1.0, seed=42)
@@ -719,27 +728,7 @@ sims = monte_carlo(geometric_brownian_motion, n_simulations=1000, n=252, seed=42
 | `ornstein_uhlenbeck` | Mean-reverting: dx = θ(μ−x)dt + σdW | `step`, `value` |
 | `monte_carlo` | N simulations of any generator | `simulation`, `step`, ... |
 
-### Fractional Random Walk — Davies-Harte Algorithm
-
-`fractional_random_walk` generates exact fractional Brownian motion increments using
-the Davies-Harte circulant embedding method, powered by
-[polars-rfft](https://github.com/mattdavis90/polars-rfft) (RustFFT) and
-[polars-sdist](https://github.com/mattdavis90/polars-sdist) for normal sampling:
-
-1. Build the autocovariance row from the Hurst exponent H
-2. Embed in a circulant matrix (length 2n)
-3. FFT the circulant row to get eigenvalues; clamp ≥ 0, take sqrt
-4. Generate complex Gaussian noise (two independent normal samples via polars-sdist)
-5. Multiply sqrt-eigenvalues × noise, then IFFT back to time domain
-6. Take the first n increments and cumsum into a price path
-
-**Hurst exponent behaviour:** H = 0.5 gives a standard random walk (fast path —
-no FFT needed, just `cumsum` of normal increments). H > 0.5 produces trending
-(persistent) paths; H < 0.5 produces mean-reverting (anti-persistent) paths.
-
-**Performance vs GBM:** For H = 0.5, FRW is faster than GBM (no `exp` call).
-For H ≠ 0.5 the FFT pipeline adds 2–13× overhead depending on series length,
-but remains O(n log n) and sub-second for 1M points.
+The `dt` parameter defaults to `1/252` (one trading day in annualised units). Pass `drift` and `volatility` as annualised values directly — the function scales them internally. For sub-daily data generation (e.g. 1-minute OHLCV bars), see the [advanced usage guide](https://polars-mktlib.readthedocs.io/en/latest/advanced.html).
 
 ## Development
 

{mktlib-0.7.0 → mktlib-0.7.2}/README_PYPI.md

@@ -10,7 +10,7 @@ Financial market toolkit built entirely on Polars.
 
 - **Fast enough for real work** — vectorized Polars engine grid-searches thousands of parameter combos on minute-bar data without reaching for Numba or Cython
 - **Lightweight** — pure Polars throughout, including synthetic data generation via Rust-native plugins. No pandas, no NumPy, no heavy ML stack
-- **Well tested** — cross-validated exchange calendars, property-based OHLCV checks, and full backtest parity tests across engines
+- **Well tested** — cross-validated exchange calendars, full backtest parity tests across engines, and pandera schema validation on every DataFrame-returning function to guarantee no silent column/dtype regressions
 - **Swiss-army knife** — scheduling, rates, metrics, backtesting, reporting, and data generation in one package. Great for learning, prototyping, or production
 - **Apache 2.0** — use it anywhere, fork it, vendor it, no strings attached
 

{mktlib-0.7.0 → mktlib-0.7.2}/docs/conf.py

@@ -44,6 +44,7 @@ sitemap_url_scheme = "{link}"
 autodoc_member_order = "bysource"
 autodoc_typehints = "description"
 always_use_bars_union = True
+autodoc_mock_imports = ["polars_sdist", "polars_rfft"]
 
 # -- intersphinx mapping -----------------------------------------------------
 

{mktlib-0.7.0 → mktlib-0.7.2}/mktlib/backtest/__init__.py

@@ -8,6 +8,7 @@ from mktlib.backtest._conditions import (
     Crossover,
     Crossunder,
     Custom,
+    EntryRef,
     IsFalling,
     IsRising,
     Lit,
@@ -29,6 +30,7 @@ __all__ = [
     "Crossover",
     "Crossunder",
     "Custom",
+    "EntryRef",
     "IsFalling",
     "IsRising",
     "Lit",

{mktlib-0.7.0 → mktlib-0.7.2}/mktlib/backtest/_conditions.py

@@ -143,6 +143,22 @@ class Pct(PriceExpr):
         return _coerce_base(self.base).resolve() * (1.0 + self.pct / 100.0)
 
 
+@dataclass(frozen=True, slots=True)
+class EntryRef(PriceExpr):
+    """Column value snapshotted at the entry signal bar, forward-filled.
+
+    The engine creates ``_entry_{col}`` columns automatically when it
+    detects ``EntryRef`` nodes in the exit condition tree.
+
+    ``EntryRef("close")`` resolves to ``pl.col("_entry_close")``.
+    """
+
+    col: str
+
+    def resolve(self) -> pl.Expr:
+        return pl.col(f"_entry_{self.col}")
+
+
 class Condition:
     """Base class for signal conditions that resolve to boolean ``pl.Expr``."""
 

{mktlib-0.7.0 → mktlib-0.7.2}/mktlib/backtest/_engine.py

@@ -5,7 +5,19 @@ from typing import TYPE_CHECKING, overload
 
 import polars as pl
 
-from mktlib.backtest._conditions import Condition, Custom
+from mktlib.backtest._conditions import (
+    All,
+    Any_,
+    Condition,
+    Custom,
+    EntryRef,
+    Not,
+    Pct,
+    PriceExpr,
+    PriceIsAbove,
+    PriceIsBelow,
+    _BinOp,
+)
 from mktlib.backtest._types import BacktestResult, MultiBacktestResult, Strategy, TradeSide
 
 if TYPE_CHECKING:
@@ -82,6 +94,45 @@ def _build_session_last_mask(
     return dates.is_in(last_bars)
 
 
+# ---------------------------------------------------------------------------
+# EntryRef tree walker — collects column names needed for entry-bar snapshots
+# ---------------------------------------------------------------------------
+
+
+def _collect_entry_refs(cond: Condition) -> set[str]:
+    """Return all column names referenced by ``EntryRef`` nodes in *cond*."""
+    cols: set[str] = set()
+    _walk_cond(cond, cols)
+    return cols
+
+
+def _walk_cond(cond: Condition, cols: set[str]) -> None:
+    match cond:
+        case All(left, right, _) | Any_(left, right, _):
+            _walk_cond(left, cols)
+            _walk_cond(right, cols)
+        case Not(inner, _):
+            _walk_cond(inner, cols)
+        case PriceIsAbove(a, b, _) | PriceIsBelow(a, b, _):
+            _walk_expr(a, cols)
+            _walk_expr(b, cols)
+        case _:
+            pass
+
+
+def _walk_expr(node: str | float | PriceExpr, cols: set[str]) -> None:
+    match node:
+        case EntryRef(col):
+            cols.add(col)
+        case Pct(base, _):
+            _walk_expr(base, cols)
+        case _BinOp(left, right, _):
+            _walk_expr(left, cols)
+            _walk_expr(right, cols)
+        case _:
+            pass
+
+
 def _run_core(
     df: pl.DataFrame,
     strategy: Strategy,
@@ -101,15 +152,25 @@ def _run_core(
     entry_cond = entry_raw if isinstance(entry_raw, Condition) else Custom(entry_raw)
     exit_cond = exit_raw if isinstance(exit_raw, Condition) else Custom(exit_raw)
     entry_expr = entry_cond.resolve()
-    exit_expr = exit_cond.resolve()
 
     # Entry condition's side overrides the run() default
     effective_side = int(entry_cond.trade_side or trade_side)
 
-    signals = df.with_columns(
-        entry_expr.alias("_entry"),
-        exit_expr.alias("_exit"),
-    )
+    # Pass 1: compute _entry
+    signals = df.with_columns(entry_expr.alias("_entry"))
+
+    # Create snapshot columns for any EntryRef nodes in exit condition
+    entry_refs = _collect_entry_refs(exit_cond)
+    if entry_refs:
+        signals = signals.with_columns(
+            pl.when(pl.col("_entry")).then(pl.col(col)).otherwise(None)
+            .forward_fill().alias(f"_entry_{col}")
+            for col in entry_refs
+        )
+
+    # Pass 2: compute _exit (snapshot columns now exist for EntryRef.resolve())
+    exit_expr = exit_cond.resolve()
+    signals = signals.with_columns(exit_expr.alias("_exit"))
 
     # Position tracking: 1 on entry, 0 on exit, forward-fill
     if flatten_eod:

mktlib-0.7.2/mktlib/data/_gbm.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import math
+
+import polars as pl
+from polars_sdist import sample_normal
+
+
+def _gbm_price_expr(log_base: float, mu_dt: float, sigma_sqrt_dt: float) -> pl.Expr:
+    """GBM price expression. Assumes columns ``step`` and ``z`` exist."""
+    return (
+        pl.when(pl.col("step") == 0)
+        .then(0.0)
+        .otherwise(pl.col("z") * sigma_sqrt_dt + mu_dt)
+        .cum_sum()
+        .add(log_base)
+        .exp()
+        .alias("price")
+    )
+
+
+def geometric_brownian_motion(
+    n: int,
+    base_price: float = 100.0,
+    drift: float = 0.0,
+    volatility: float = 0.01,
+    dt: float = 1 / 252,
+    seed: int | None = None,
+) -> pl.DataFrame:
+    r"""Geometric Brownian motion price path.
+
+    Simulates the SDE :math:`dS = \mu S \, dt + \sigma S \, dW` using the
+    exact log-space solution derived via Itô's lemma.
+
+    Parameters
+    ----------
+    n
+        Number of time steps to generate.
+    base_price
+        Initial price :math:`S_0`.
+    drift
+        Annualised expected return :math:`\mu`.
+    volatility
+        Annualised volatility :math:`\sigma`.
+    dt
+        Time step size in annualised units.  Defaults to ``1/252`` (one
+        trading day).  For sub-daily granularity, divide further — e.g.
+        ``1/(252*6.5*3600)`` for one-second ticks during US equity hours.
+    seed
+        RNG seed for reproducibility.
+
+    Returns
+    -------
+    pl.DataFrame
+        Columns ``step`` (int) and ``price`` (float).
+
+    Notes
+    -----
+    **Why log-space?**  The SDE is multiplicative in *S*, so direct
+    Euler-Maruyama discretisation introduces bias.  Applying Itô's lemma
+    to :math:`X = \ln S` yields an additive SDE::
+
+        dX = (μ − ½σ²) dt + σ dW
+
+    whose discrete-time exact solution is::
+
+        ln S[i] = ln S[i−1] + (μ − ½σ²)·dt + σ·√dt·Z[i],  Z ~ N(0,1)
+
+    The implementation draws all *Z* values in one ``sample_normal`` call,
+    computes log-increments, and uses ``cum_sum`` + ``exp`` to recover
+    prices — no Python loop required.
+
+    **Itô correction (−½σ²).**  Because :math:`\exp` is convex, Jensen's
+    inequality gives :math:`E[\exp(X)] > \exp(E[X])`.  The −½σ² drift
+    adjustment compensates for this so that the expected price path
+    satisfies :math:`E[S(t)] = S_0 \exp(\mu t)`.
+
+    **Distributional properties.**  Log-returns
+    :math:`\ln(S_{i}/S_{i-1})` are i.i.d. normal; prices :math:`S_i` are
+    lognormally distributed.
+    """
+    if n < 1:
+        raise ValueError("n must be >= 1")
+
+    log_base = math.log(base_price)
+    mu_dt = (drift - 0.5 * volatility**2) * dt
+    sigma_sqrt_dt = volatility * math.sqrt(dt)
+
+    z = sample_normal(n, seed=seed)
+    step = pl.arange(0, n, eager=True).alias("step")
+
+    return (
+        pl.DataFrame({"step": step, "z": z})
+        .with_columns(_gbm_price_expr(log_base, mu_dt, sigma_sqrt_dt))
+        .select("step", "price")
+    )