oakscriptpy 0.1.4__tar.gz → 0.2.0__tar.gz

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/DEVLOG.md

@@ -79,3 +79,35 @@ Port all Jest test files from oakscriptJS to Python pytest equivalents for math,
 - Python `str.split('', '')` raises ValueError (tested as such instead of returning `[]`)
 - Python `substring` uses direct slicing (negative indices and begin>end behave differently from JS)
 - Python counts Unicode code points, not UTF-16 units (emoji = 1 char, not 2)
+
+## 2026-02-28 - PineScript DSL ergonomics (#10, #11, #12, #16)
+
+### Goal
+Make the Python API feel closer to PineScript's DSL by reducing boilerplate and adding familiar patterns.
+
+### Approach Taken
+Reviewed PineScript v5/v6 DSL characteristics against the current API. Identified achievable ergonomic wins vs inherent Python limitations. Implemented four features:
+
+1. `Series.__getitem__` — `close[1]` instead of `close.offset(1)`
+2. `BuiltIns` class — pre-built OHLCV Series from bar data
+3. `na` first-class concept — enhanced `na` constant, Series-aware `nz()` and `fixnan()`
+4. Decorator-style `@indicator()` — minimal working program pattern
+
+### What Worked
+- `__getitem__` was trivial (delegates to `offset()`, returns self for `[0]`)
+- `BuiltIns` as a simple class with pre-built Series avoids proxy/magic complexity
+- `na.__float__()` lets it participate in arithmetic as NaN
+- `indicator()` overload detects `str` vs `IndicatorMetadataConfig` for backward-compatible dual API
+
+### What Failed
+- Cannot override `and`/`or`/`not` or `==`/`!=` on Series — Python language limitation. Documented as known gaps (#13, #14)
+
+### Current State
+- **Done**: All 4 features shipped, 1224 tests passing
+- **Remaining open issues**: #13 (logical operators, wontfix), #14 (equality operators, wontfix), #15 (missing namespaces, future)
+
+### Key Decisions
+- `BuiltIns` is an explicit object (not module-level proxies) — no thread-local state, no import magic
+- `close[n]` only accepts non-negative integers, raises `ValueError` otherwise
+- `@indicator("title")` returns `Script` with `.calculate(bars)`, legacy API unchanged
+- `nz()`/`fixnan()` on Series create new lazy Series (no eager computation)

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oakscriptpy
-Version: 0.1.4
+Version: 0.2.0
 Summary: PineScript-like API for technical analysis in Python
 Project-URL: Homepage, https://github.com/deepentropy/oakscriptPy
 Project-URL: Repository, https://github.com/deepentropy/oakscriptPy
@@ -40,33 +40,66 @@ pip install oakscriptpy
 ## Quick Start
 
 ```python
-from oakscriptpy import ta, math, color, Series
+from oakscriptpy import indicator, ta, nz
+
+@indicator("My SMA", overlay=True)
+def my_sma(b):
+    sma14 = ta.sma(b.close, 14)
+    return nz(sma14)
+
+# Run on bar data
 from oakscriptpy._types import Bar
+bars = [Bar(time=1, open=10, high=12, low=9, close=11, volume=100), ...]
+result = my_sma.calculate(bars)
+```
+
+The `@indicator` decorator provides a `BuiltIns` object with pre-built Series for all standard fields:
+
+| Variable | Description |
+|----------|-------------|
+| `b.open`, `b.high`, `b.low`, `b.close`, `b.volume` | OHLCV price data |
+| `b.hl2`, `b.hlc3`, `b.ohlc4` | Derived composites |
+| `b.bar_index`, `b.time` | Bar identity |
+
+## PineScript-like Syntax
+
+```python
+from oakscriptpy import BuiltIns, ta, nz, fixnan, na
+
+b = BuiltIns(bars)
 
-# Create bars
-bars = [
-    Bar(time=1, open=10.0, high=12.0, low=9.0, close=11.0, volume=100.0),
-    Bar(time=2, open=11.0, high=13.0, low=10.0, close=12.0, volume=110.0),
-    Bar(time=3, open=12.0, high=14.0, low=11.0, close=13.0, volume=120.0),
-    # ...
-]
+# History access: close[1] instead of close.offset(1)
+change = b.close - b.close[1]
+
+# TA functions
+sma = ta.sma(b.close, 14)
+rsi = ta.rsi(b.close, 14)
+macd_line, signal, hist = ta.macd(b.close, 12, 26, 9)
+
+# na handling
+safe = nz(sma)            # replace NaN with 0
+filled = fixnan(sma)      # forward-fill NaN values
+if na(sma.last()):
+    pass
+
+# Comparisons and logic
+bullish = b.close > b.open
+above_sma = b.close > sma
+signal = bullish.and_(above_sma)
+result = signal.iff(1, -1)
+```
+
+## Array-based API
+
+For direct computation without Series overhead:
+
+```python
+from oakscriptpy import ta as ta_core
 
-# Array-based TA
 closes = [b.close for b in bars]
-sma_values = ta.sma(closes, 3)
-ema_values = ta.ema(closes, 3)
-rsi_values = ta.rsi(closes, 14)
-
-# Series-based TA (with operator overloading)
-from oakscriptpy import ta as ta_series
-close_series = Series.from_bars(bars, lambda b: b.close)
-sma_series = ta_series.sma(close_series, 3)
-ema_series = ta_series.ema(close_series, 3)
-
-# Series arithmetic
-spread = close_series - sma_series
-doubled = close_series * 2
-above_sma = close_series > sma_series
+sma_values = ta_core.sma(closes, 3)      # list[float]
+ema_values = ta_core.ema(closes, 3)
+rsi_values = ta_core.rsi(closes, 14)
 ```
 
 ## Namespaces
@@ -92,20 +125,22 @@ above_sma = close_series > sma_series
 The `Series` class provides lazy evaluation with Python operator overloading:
 
 ```python
-a = Series.from_bars(bars, lambda b: b.close)
-b = Series.from_bars(bars, lambda b: b.open)
+b = BuiltIns(bars)
 
 # Arithmetic: +, -, *, /, %
-spread = a - b
+spread = b.close - b.open
 
 # Comparison: >, >=, <, <=, eq(), neq()
-bullish = a > b
+bullish = b.close > b.open
 
 # Logical: and_(), or_(), not_()
-signal = bullish.and_(a > sma_series)
+signal = bullish.and_(b.close > sma)
 
 # History access
-prev_close = a.offset(1)
+prev_close = b.close[1]
+
+# Conditional (ternary)
+result = bullish.iff(1, -1)
 ```
 
 ## Tests

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/README.md

@@ -19,33 +19,66 @@ pip install oakscriptpy
 ## Quick Start
 
 ```python
-from oakscriptpy import ta, math, color, Series
+from oakscriptpy import indicator, ta, nz
+
+@indicator("My SMA", overlay=True)
+def my_sma(b):
+    sma14 = ta.sma(b.close, 14)
+    return nz(sma14)
+
+# Run on bar data
 from oakscriptpy._types import Bar
+bars = [Bar(time=1, open=10, high=12, low=9, close=11, volume=100), ...]
+result = my_sma.calculate(bars)
+```
+
+The `@indicator` decorator provides a `BuiltIns` object with pre-built Series for all standard fields:
+
+| Variable | Description |
+|----------|-------------|
+| `b.open`, `b.high`, `b.low`, `b.close`, `b.volume` | OHLCV price data |
+| `b.hl2`, `b.hlc3`, `b.ohlc4` | Derived composites |
+| `b.bar_index`, `b.time` | Bar identity |
+
+## PineScript-like Syntax
+
+```python
+from oakscriptpy import BuiltIns, ta, nz, fixnan, na
+
+b = BuiltIns(bars)
 
-# Create bars
-bars = [
-    Bar(time=1, open=10.0, high=12.0, low=9.0, close=11.0, volume=100.0),
-    Bar(time=2, open=11.0, high=13.0, low=10.0, close=12.0, volume=110.0),
-    Bar(time=3, open=12.0, high=14.0, low=11.0, close=13.0, volume=120.0),
-    # ...
-]
+# History access: close[1] instead of close.offset(1)
+change = b.close - b.close[1]
+
+# TA functions
+sma = ta.sma(b.close, 14)
+rsi = ta.rsi(b.close, 14)
+macd_line, signal, hist = ta.macd(b.close, 12, 26, 9)
+
+# na handling
+safe = nz(sma)            # replace NaN with 0
+filled = fixnan(sma)      # forward-fill NaN values
+if na(sma.last()):
+    pass
+
+# Comparisons and logic
+bullish = b.close > b.open
+above_sma = b.close > sma
+signal = bullish.and_(above_sma)
+result = signal.iff(1, -1)
+```
+
+## Array-based API
+
+For direct computation without Series overhead:
+
+```python
+from oakscriptpy import ta as ta_core
 
-# Array-based TA
 closes = [b.close for b in bars]
-sma_values = ta.sma(closes, 3)
-ema_values = ta.ema(closes, 3)
-rsi_values = ta.rsi(closes, 14)
-
-# Series-based TA (with operator overloading)
-from oakscriptpy import ta as ta_series
-close_series = Series.from_bars(bars, lambda b: b.close)
-sma_series = ta_series.sma(close_series, 3)
-ema_series = ta_series.ema(close_series, 3)
-
-# Series arithmetic
-spread = close_series - sma_series
-doubled = close_series * 2
-above_sma = close_series > sma_series
+sma_values = ta_core.sma(closes, 3)      # list[float]
+ema_values = ta_core.ema(closes, 3)
+rsi_values = ta_core.rsi(closes, 14)
 ```
 
 ## Namespaces
@@ -71,20 +104,22 @@ above_sma = close_series > sma_series
 The `Series` class provides lazy evaluation with Python operator overloading:
 
 ```python
-a = Series.from_bars(bars, lambda b: b.close)
-b = Series.from_bars(bars, lambda b: b.open)
+b = BuiltIns(bars)
 
 # Arithmetic: +, -, *, /, %
-spread = a - b
+spread = b.close - b.open
 
 # Comparison: >, >=, <, <=, eq(), neq()
-bullish = a > b
+bullish = b.close > b.open
 
 # Logical: and_(), or_(), not_()
-signal = bullish.and_(a > sma_series)
+signal = bullish.and_(b.close > sma)
 
 # History access
-prev_close = a.offset(1)
+prev_close = b.close[1]
+
+# Conditional (ternary)
+result = bullish.iff(1, -1)
 ```
 
 ## Tests

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oakscriptpy"
-version = "0.1.4"
+version = "0.2.0"
 description = "PineScript-like API for technical analysis in Python"
 requires-python = ">=3.11"
 dependencies = []

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/src/oakscriptpy/__init__.py

@@ -19,7 +19,7 @@ from . import chartpoint as chart_point
 from . import polyline
 
 # Series class (self-contained, no context)
-from .series import Series, BarData
+from .series import Series, BarData, BuiltIns
 
 # TA-Series namespace (Series-based wrappers)
 from . import ta_series as ta
@@ -41,7 +41,7 @@ from ._metadata import (
 )
 
 # Utilities
-from ._utils import is_na, nz, ohlc_from_bars, get_close, get_high, get_low, get_open, get_source
+from ._utils import is_na, nz, fixnan, ohlc_from_bars, get_close, get_high, get_low, get_open, get_source
 
 # Runtime
 from .runtime import (
@@ -58,7 +58,7 @@ from .inputs import (
 )
 
 # Indicator infrastructure
-from .indicator import indicator, IndicatorMetadataConfig, IndicatorContext, IndicatorInstance
+from .indicator import indicator, Script, IndicatorMetadataConfig, IndicatorContext, IndicatorInstance
 
 # Input helper
 from . import input_ as input
@@ -78,7 +78,7 @@ def alertcondition(_condition: object = None, _title: str | None = None, _messag
     pass
 
 
-VERSION = "0.1.4"
+VERSION = "0.2.0"
 
 info = {
     "name": "OakScriptPy",

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/src/oakscriptpy/_types.py

@@ -19,7 +19,14 @@ import math as _math
 
 
 class _Na:
-    """PineScript-compatible NA: falsy constant + callable checker."""
+    """PineScript-compatible NA: falsy constant, callable checker, numeric NaN.
+
+    Usage::
+
+        na          # falsy sentinel, acts as float('nan') in arithmetic
+        na(value)   # True if value is None or NaN
+        na + 1      # nan (propagates like NaN)
+    """
 
     def __call__(self, value: object) -> bool:
         if value is None:
@@ -31,9 +38,22 @@ class _Na:
     def __bool__(self) -> bool:
         return False
 
+    def __float__(self) -> float:
+        return float("nan")
+
     def __repr__(self) -> str:
         return "na"
 
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, _Na):
+            return True
+        if isinstance(other, float) and _math.isnan(other):
+            return True
+        return NotImplemented
+
+    def __hash__(self) -> int:
+        return hash(float("nan"))
+
 
 na = _Na()
 

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/src/oakscriptpy/_utils.py

@@ -32,9 +32,51 @@ def is_na(value: object) -> bool:
 
 
 def nz(value: object, default: object = 0) -> object:
+    """Replace na with default. Works on scalars and Series.
+
+    Scalar: nz(float('nan')) -> 0, nz(float('nan'), -1) -> -1
+    Series: nz(series) -> new Series with na values replaced by default
+    """
+    from .series import Series
+
+    if isinstance(value, Series):
+        replacement = float(default)
+        ext = value._extractor
+
+        def _nz(b: Bar, i: int, d: list[Bar]) -> float:
+            v = ext(b, i, d)
+            return replacement if (v is None or (isinstance(v, float) and math.isnan(v))) else v
+
+        return Series(value._data_source, _nz)
     return default if is_na(value) else value
 
 
+def fixnan(value: object) -> object:
+    """Replace na with last non-na value (forward fill). Works on scalars and Series.
+
+    Scalar: fixnan(float('nan')) -> float('nan') (no history to fill from)
+    Series: fixnan(series) -> new Series with na forward-filled
+    """
+    from .series import Series
+
+    if isinstance(value, Series):
+        ext = value._extractor
+
+        def _fixnan(_b: Bar, i: int, d: list[Bar]) -> float:
+            v = ext(d[i], i, d)
+            if not math.isnan(v):
+                return v
+            # Walk backwards to find last non-na value
+            for j in range(i - 1, -1, -1):
+                prev = ext(d[j], j, d)
+                if not math.isnan(prev):
+                    return prev
+            return float("nan")
+
+        return Series(value._data_source, _fixnan)
+    return value
+
+
 def clamp(value: float, min_val: float, max_val: float) -> float:
     return max(min_val, min(max_val, value))
 

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/src/oakscriptpy/indicator.py

@@ -6,6 +6,7 @@ from dataclasses import dataclass, field
 from typing import Any, Callable
 
 from ._types import Bar
+from .series import BuiltIns
 
 
 @dataclass
@@ -63,11 +64,70 @@ class IndicatorInstance:
         self._setup(ctx)
 
 
+class Script:
+    """Decorator-style indicator: receives BuiltIns, returns computed results.
+
+    Usage::
+
+        @indicator("My SMA", overlay=True)
+        def my_sma(b):
+            return ta.sma(b.close, 14)
+
+        result = my_sma.calculate(bars)
+    """
+
+    def __init__(self, metadata: IndicatorMetadataConfig, fn: Callable[[BuiltIns], Any]) -> None:
+        self.metadata = metadata
+        self._fn = fn
+
+    def calculate(self, data: list[Bar]) -> Any:
+        b = BuiltIns(data)
+        return self._fn(b)
+
+
 def indicator(
-    metadata: IndicatorMetadataConfig,
-    setup: Callable[[IndicatorContext], None],
-) -> Callable[[], IndicatorInstance]:
-    """Create an indicator factory function."""
+    title_or_metadata: str | IndicatorMetadataConfig,
+    setup: Callable[[IndicatorContext], None] | None = None,
+    /,
+    *,
+    overlay: bool = False,
+    short_title: str | None = None,
+    format: str = "price",
+    precision: int = 2,
+) -> Callable[[], IndicatorInstance] | Callable[..., Script]:
+    """Create an indicator — as a factory (legacy) or as a decorator (new).
+
+    Legacy API::
+
+        factory = indicator(IndicatorMetadataConfig(...), setup_fn)
+        instance = factory()
+        instance.calculate(bars)
+
+    Decorator API::
+
+        @indicator("My Script", overlay=True)
+        def my_script(b):
+            return ta.sma(b.close, 14)
+
+        result = my_script.calculate(bars)
+    """
+    if isinstance(title_or_metadata, str):
+        metadata = IndicatorMetadataConfig(
+            title=title_or_metadata,
+            short_title=short_title or title_or_metadata,
+            overlay=overlay,
+            format=format,
+            precision=precision,
+        )
+
+        def decorator(fn: Callable[[BuiltIns], Any]) -> Script:
+            return Script(metadata, fn)
+
+        return decorator
+
+    # Legacy path: indicator(IndicatorMetadataConfig, setup_fn)
+    metadata = title_or_metadata
+    assert setup is not None, "setup function required for legacy indicator() API"
     normalized = IndicatorMetadataConfig(
         title=metadata.title,
         short_title=metadata.short_title or metadata.title,

{oakscriptpy-0.1.4 → oakscriptpy-0.2.0}/src/oakscriptpy/series.py

@@ -10,6 +10,45 @@ from ._types import Bar
 SeriesExtractor = Callable[[Bar, int, list[Bar]], float]
 
 
+class BuiltIns:
+    """Pre-built Series for standard OHLCV fields and derived composites.
+
+    Mirrors PineScript's built-in variables: close, open, high, low, volume,
+    hl2, hlc3, ohlc4, bar_index, time.
+
+    Usage::
+
+        bd = BarData(bars)
+        b = BuiltIns(bd)
+        sma = ta.sma(b.close, 14)
+        change = b.close - b.close[1]
+    """
+
+    __slots__ = (
+        "open", "high", "low", "close", "volume",
+        "hl2", "hlc3", "ohlc4", "bar_index", "time",
+        "_bar_data",
+    )
+
+    def __init__(self, data: list[Bar] | BarData) -> None:
+        bd = data if isinstance(data, BarData) else BarData(data)
+        self._bar_data = bd
+        self.open: Series = Series.from_bars(bd, "open")
+        self.high: Series = Series.from_bars(bd, "high")
+        self.low: Series = Series.from_bars(bd, "low")
+        self.close: Series = Series.from_bars(bd, "close")
+        self.volume: Series = Series.from_bars(bd, "volume")
+        self.hl2: Series = (self.high + self.low) / 2
+        self.hlc3: Series = (self.high + self.low + self.close) / 3
+        self.ohlc4: Series = (self.open + self.high + self.low + self.close) / 4
+        self.time: Series = Series.from_bars(bd, "time")
+        self.bar_index: Series = Series(bd, lambda _b, i, _d: float(i))
+
+    @property
+    def bar_data(self) -> BarData:
+        return self._bar_data
+
+
 class BarData:
     """Versioned wrapper around list[Bar] for cache invalidation.
 
@@ -240,6 +279,14 @@ class Series:
 
     # --- Offset/History ---
 
+    def __getitem__(self, n: int) -> Series:
+        """Access previous bars: close[1] is equivalent to close.offset(1)."""
+        if not isinstance(n, int) or n < 0:
+            raise ValueError(f"Series index must be a non-negative integer, got {n!r}")
+        if n == 0:
+            return self
+        return self.offset(n)
+
     def offset(self, n: int) -> Series:
         """Access previous bars (like close[1] in PineScript)."""
         ext = self._extractor