feat/api canon 2.0

CHANGELOG.md

@@ -3,7 +3,44 @@
 All notable changes to RiskLabAI.py are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning: [SemVer](https://semver.org/).
 
-## [Unreleased]
+## [2.0.0]
+
+A **breaking** release that standardises the public API on PEP 8 names and makes
+the core component registry the single way to construct cross-validators and
+feature-importance strategies. **Every** renamed name keeps working with a
+`DeprecationWarning` until 2.1.0, so existing code does not break on upgrade —
+see `NAMING_CANON_2.0.0.md`.
+
+### Changed (BREAKING)
+- `backtest.bet_sizing` functions renamed to snake_case:
+  `avgActiveSignals`→`avg_active_signals`,
+  `mpAvgActiveSignals`→`mp_avg_active_signals`,
+  `discreteSignal`→`discrete_signal`, `Signal`→`generate_signal`,
+  `betSize`→`bet_size_sigmoid`, `getW`→`compute_sigmoid_width`,
+  `TPos`→`target_position`, `inversePrice`→`inverse_price`,
+  `limitPrice`→`limit_price`. Their parameters are snake_case too (e.g.
+  `nThreads`→`n_threads`, `stepSize`→`step_size`, `acctualPrice`→`actual_price`,
+  `maximumPositionSize`→`maximum_position_size`). Keyword-argument callers must
+  update parameter names; positional calls are unaffected.
+- Classes renamed: `pde.FBSNNolver`→`FBSNNSolver` (typo fix);
+  `optimization.MyPipeline`→`SampleWeightedPipeline`.
+- Constants given ASCII identifiers — the string *values* are unchanged, so
+  stored data and internal dict keys are unaffected: `CUMULATIVE_θ`→
+  `CUMULATIVE_THETA`, `CUMULATIVE_BUY_θ`→`CUMULATIVE_BUY_THETA`,
+  `CUMULATIVE_SELL_θ`→`CUMULATIVE_SELL_THETA`.
+- The core registries (`RiskLabAI.core.CROSS_VALIDATORS`, `FEATURE_IMPORTANCE`)
+  are now the single way to construct those components. The bars stack imports
+  its column-name constants explicitly (no more `from ...constants import *`).
+
+### Deprecated
+The following keep working until **2.1.0**, emitting a `DeprecationWarning`
+that names the replacement:
+- The old `bet_sizing` camelCase function names, `FBSNNolver`, `MyPipeline`,
+  and the `CUMULATIVE_*θ` constant identifiers (accessed via `RiskLabAI.utils`).
+- `CrossValidatorFactory`, `CrossValidatorController`,
+  `FeatureImportanceFactory`, and `FeatureImportanceController` — use
+  `RiskLabAI.core.CROSS_VALIDATORS.create(...)` /
+  `RiskLabAI.core.FEATURE_IMPORTANCE.create(...)` instead.
 
 ### Added
 - `RiskLabAI.core`: a non-breaking extension layer that makes the library easier

NAMING_CANON_2.0.0.md

@@ -1,6 +1,8 @@
 # RiskLabAI.py 2.0.0 — Naming Canon (proposal)
 
-Status: **proposal, awaiting approval.** No code changes yet. This is the
+Status: **approved and implemented in 2.0.0.** All §2 renames were approved
+(remove aliases in 2.1.0; keep the `θ` string values; scope folded in the
+star-import cleanup and the controller/factory→registry refactor). This is the
 breaking API cleanup from `IMPROVEMENT_PLAN.md` Phase 3, scoped to Python and
 written so that **no existing user breaks on upgrade** — every renamed name
 keeps working (with a `DeprecationWarning`) for one minor cycle before removal.

RiskLabAI/_deprecation.py

@@ -0,0 +1,123 @@
+"""
+Internal helpers for deprecating public names without breaking callers.
+
+Used by the 2.0.0 naming canon (see ``NAMING_CANON_2.0.0.md``): every renamed
+function, class, or constant keeps working throughout the 2.0.x series and emits
+a :class:`DeprecationWarning` naming its replacement. The aliases are scheduled
+for removal in 2.1.0.
+
+Three mechanisms, one per kind of object:
+
+- :func:`deprecated_alias` wraps a renamed **function**.
+- :func:`deprecated_class` subclasses a renamed **class**.
+- :func:`warn_deprecated_name` is called from a module ``__getattr__`` (PEP 562)
+  for renamed **module-level names** such as constants.
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Any, Callable, TypeVar
+
+__all__ = ["deprecated_alias", "deprecated_class", "warn_deprecated_name"]
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def deprecated_alias(new_func: _F, old_name: str, *, removed_in: str) -> _F:
+    """
+    Return a thin wrapper that calls ``new_func`` but warns under the old name.
+
+    Parameters
+    ----------
+    new_func : Callable
+        The renamed (canonical) function.
+    old_name : str
+        The deprecated public name being kept alive.
+    removed_in : str
+        Version in which the alias will be removed (e.g. ``"2.1.0"``).
+
+    Returns
+    -------
+    Callable
+        A wrapper with ``__name__`` set to ``old_name`` that emits a
+        :class:`DeprecationWarning` and delegates to ``new_func``.
+    """
+
+    @functools.wraps(new_func)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        warnings.warn(
+            f"{old_name}() is deprecated and will be removed in {removed_in}; "
+            f"use {new_func.__name__}() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return new_func(*args, **kwargs)
+
+    wrapper.__name__ = old_name
+    wrapper.__qualname__ = old_name
+    wrapper.__doc__ = (
+        f"Deprecated alias for :func:`{new_func.__name__}` "
+        f"(removed in {removed_in})."
+    )
+    return wrapper  # type: ignore[return-value]
+
+
+def deprecated_class(new_cls: type, old_name: str, *, removed_in: str) -> type:
+    """
+    Return a subclass of ``new_cls`` that warns when instantiated.
+
+    The subclass behaves identically to ``new_cls`` but emits a
+    :class:`DeprecationWarning` on construction, naming the replacement.
+
+    Parameters
+    ----------
+    new_cls : type
+        The renamed (canonical) class.
+    old_name : str
+        The deprecated public class name being kept alive.
+    removed_in : str
+        Version in which the alias will be removed.
+    """
+
+    def __init__(self: Any, *args: Any, **kwargs: Any) -> None:
+        warnings.warn(
+            f"{old_name} is deprecated and will be removed in {removed_in}; "
+            f"use {new_cls.__name__} instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        new_cls.__init__(self, *args, **kwargs)
+
+    shim = type(old_name, (new_cls,), {"__init__": __init__})
+    shim.__doc__ = (
+        f"Deprecated alias for :class:`{new_cls.__name__}` "
+        f"(removed in {removed_in})."
+    )
+    shim.__module__ = new_cls.__module__
+    return shim
+
+
+def warn_deprecated_name(old_name: str, new_name: str, *, removed_in: str) -> None:
+    """
+    Emit a deprecation warning for a renamed module-level name.
+
+    Call this from a module's ``__getattr__`` (PEP 562) before returning the
+    value bound to ``new_name``.
+
+    Parameters
+    ----------
+    old_name : str
+        The deprecated name that was accessed.
+    new_name : str
+        The canonical replacement name.
+    removed_in : str
+        Version in which the old name will be removed.
+    """
+    warnings.warn(
+        f"{old_name} is deprecated and will be removed in {removed_in}; "
+        f"use {new_name} instead.",
+        DeprecationWarning,
+        stacklevel=3,
+    )

RiskLabAI/backtest/__init__.py

@@ -40,15 +40,24 @@
     Signal,
     TPos,
     average_bet_sizes,
+    avg_active_signals,
     avgActiveSignals,
+    bet_size_sigmoid,
     betSize,
+    compute_sigmoid_width,
+    discrete_signal,
     discreteSignal,
+    generate_signal,
     getW,
+    inverse_price,
     inversePrice,
+    limit_price,
     limitPrice,
+    mp_avg_active_signals,
     mpAvgActiveSignals,
     probability_bet_size,
     strategy_bet_sizing,
+    target_position,
 )
 from .probabilistic_sharpe_ratio import (
     benchmark_sharpe_ratio,
@@ -89,10 +98,20 @@
     "compute_drawdowns_time_under_water",
     # from backtest_synthetic_data
     "synthetic_back_testing",
-    # from bet_sizing
+    # from bet_sizing (canonical 2.0.0 names)
     "probability_bet_size",
     "average_bet_sizes",
     "strategy_bet_sizing",
+    "avg_active_signals",
+    "mp_avg_active_signals",
+    "discrete_signal",
+    "generate_signal",
+    "bet_size_sigmoid",
+    "target_position",
+    "inverse_price",
+    "limit_price",
+    "compute_sigmoid_width",
+    # from bet_sizing (deprecated aliases, removed in 2.1.0)
     "avgActiveSignals",
     "mpAvgActiveSignals",
     "discreteSignal",