back-trader-python 1.4.0__py3-none-any.whl

backtrader/channels/bridge.py

@@ -0,0 +1,186 @@
+"""Channel-to-LineSeries bridge for indicator compatibility.
+
+ChannelBridge optionally bridges data from Channel events to LineSeries,
+enabling the use of traditional backtrader indicators (SMA, RSI, etc.)
+on tick-level data. This comes with a performance overhead warning.
+
+Example::
+
+    bridge = ChannelBridge(tick_channel, fields=['price', 'volume'])
+    bridge.update(tick_event)
+    # Now bridge.lines.price[0] contains the latest tick price
+"""
+
+from collections import deque
+
+from ..utils.log_message import get_logger
+
+logger = get_logger(__name__)
+
+__all__ = ["ChannelBridge"]
+
+
+class ChannelBridge:
+    """Bridge between DataChannel events and a simple line-like interface.
+
+    Buffers specified fields from channel events into deque-based lines
+    that can be accessed with [0], [-1] indexing. This is a lightweight
+    bridge - it does NOT create full LineSeries objects but provides
+    a compatible enough interface for simple indicator usage.
+
+    Note:
+        Using ChannelBridge adds overhead. Only use it when you need
+        indicators on channel data. For pure tick processing, use
+        channel events directly.
+
+    Args:
+        channel: The DataChannel to bridge from.
+        fields: List of field names to bridge (e.g., ['price', 'volume']).
+        maxlen: Maximum number of values to retain per line.
+
+    Example::
+
+        bridge = ChannelBridge(tick_ch, fields=['price', 'volume'])
+        bridge.update(tick_event)
+        print(bridge['price'][0])   # latest price
+        print(bridge['price'][-1])  # previous price
+    """
+
+    def __init__(self, channel, fields=None, maxlen=10000):
+        """Initialize the channel bridge.
+
+        Args:
+            channel: The DataChannel instance to bridge.
+            fields: Optional list of field names to extract.
+            maxlen: Maximum deque length for each field.
+        """
+        self.channel = channel
+        self._maxlen = maxlen
+        self._fields = fields or self._default_fields(channel)
+        self._lines: dict = {f: deque(maxlen=maxlen) for f in self._fields}
+        self._count = 0
+
+    def _default_fields(self, channel):
+        """Determine default fields based on channel type.
+
+        Args:
+            channel: The DataChannel instance to introspect.
+
+        Returns:
+            List of default field names for the channel type.
+        """
+        type_fields = {
+            "tick": ["price", "volume", "timestamp"],
+            "orderbook": ["timestamp"],
+            "funding": ["rate", "mark_price", "timestamp"],
+            "bar": ["open", "high", "low", "close", "volume", "timestamp"],
+        }
+        return type_fields.get(channel.channel_type, ["timestamp"])
+
+    def update(self, event):
+        """Update bridge lines with data from a new event.
+
+        Args:
+            event: An EventData instance whose fields are extracted.
+        """
+        for field in self._fields:
+            value = getattr(event, field, None)
+            if value is not None:
+                self._lines[field].append(value)
+            else:
+                self._lines[field].append(float("nan"))
+        self._count += 1
+
+    @property
+    def fields(self):
+        """List of bridged field names."""
+        return list(self._fields)
+
+    @property
+    def count(self):
+        """Number of events bridged."""
+        return self._count
+
+    def __getitem__(self, field):
+        """Get a line by field name.
+
+        Args:
+            field: Field name string.
+
+        Returns:
+            _BridgeLine accessor for the field.
+        """
+        if field not in self._lines:
+            raise KeyError(f"Field '{field}' not bridged. Available: {list(self._lines.keys())}")
+        return _BridgeLine(self._lines[field])
+
+    def __len__(self):
+        """Number of data points in the bridge."""
+        if self._lines:
+            return len(next(iter(self._lines.values())))
+        return 0
+
+    def __repr__(self):
+        """Return a string representation of the bridge.
+
+        Returns:
+            str: Representation showing channel, fields, and event count.
+        """
+        return (
+            f"ChannelBridge(channel={self.channel!r}, fields={self._fields}, count={self._count})"
+        )
+
+
+class _BridgeLine:
+    """Accessor for a single bridged line with [-n] indexing.
+
+    Supports [0] for latest, [-1] for previous, etc. Mimics
+    backtrader's line indexing convention.
+    """
+
+    def __init__(self, data):
+        """Initialize the bridge line accessor.
+
+        Args:
+            data: Deque containing the historical values for this line.
+        """
+        self._data = data
+
+    def __getitem__(self, index):
+        """Access line values with backtrader-style indexing.
+
+        Supports backtrader's line indexing convention where:
+            [0] = latest value (last element)
+            [-1] = previous value (second to last)
+            [-2] = two values back
+            [n] = future offset from current (only 0 supported)
+
+        Args:
+            index: Integer index (0 for latest, negative for historical).
+
+        Returns:
+            float: The value at the specified index, or NaN if out of bounds.
+        """
+        if not self._data:
+            return float("nan")
+        if index == 0:
+            return self._data[-1]
+        if index < 0:
+            # -1 = previous, -2 = two back, etc.
+            pos = len(self._data) + index - 1
+            if 0 <= pos < len(self._data):
+                return self._data[pos]
+            return float("nan")
+        return float("nan")
+
+    def __len__(self):
+        """Return the number of data points in the line."""
+        return len(self._data)
+
+    def __repr__(self):
+        """Return a string representation of the bridge line.
+
+        Returns:
+            str: Representation showing data length.
+        """
+        return f"_BridgeLine(length={len(self._data)})"

backtrader/channels/funding.py

@@ -0,0 +1,248 @@
+"""Funding rate data channel for perpetual contract funding rates.
+
+Provides FundingRateChannel for loading, validating, and buffering
+funding rate data from CSV/JSONL files or other sources.
+
+Example:
+    Loading funding rate data from CSV::
+
+        channel = FundingRateChannel(
+            symbol='BTC/USDT',
+            dataname='data/btc_funding_20210101.csv'
+        )
+        for event in channel.load():
+            print(event.rate, event.mark_price)
+"""
+
+import csv
+import gzip
+import json
+import math
+from typing import Iterator, Optional
+
+from ..channel import DataChannel, DataValidationResult
+from ..events import FundingEvent
+from ..utils.log_message import get_logger
+
+logger = get_logger(__name__)
+
+
+class FundingRateChannel(DataChannel):
+    """Funding rate data channel for perpetual contracts.
+
+    Loads funding rate data from CSV or JSONL files. Validates funding
+    rate ranges and mark price consistency.
+
+    CSV format expects columns: timestamp, rate, mark_price
+    Optional columns: next_funding_time, predicted_rate, symbol, exchange
+
+    Args:
+        symbol: Trading pair symbol (e.g., 'BTC/USDT').
+        dataname: Path to the data file (CSV or JSONL).
+        maxlen: Maximum buffer size.
+        validate: Whether to validate incoming events.
+        auto_fix: Whether to auto-fix invalid data.
+        rate_threshold: Max absolute funding rate for anomaly warning.
+        **kwargs: Additional parameters passed to DataChannel.
+    """
+
+    channel_type = "funding"
+
+    def __init__(
+        self,
+        symbol,
+        dataname=None,
+        maxlen=10000,
+        validate=True,
+        auto_fix=True,
+        rate_threshold=0.01,
+        **kwargs,
+    ):
+        """Initialize the funding rate channel.
+
+        Args:
+            symbol: Trading pair symbol (e.g., 'BTC/USDT:USDT').
+            dataname: Optional data name for the feed.
+            maxlen: Maximum number of events to buffer.
+            validate: Whether to validate incoming events.
+            auto_fix: Whether to attempt auto-fixing invalid data.
+            rate_threshold: Maximum allowed rate difference threshold.
+            **kwargs: Additional arguments passed to parent.
+        """
+        super().__init__(
+            symbol=symbol,
+            maxlen=maxlen,
+            validate=validate,
+            auto_fix=auto_fix,
+            dataname=dataname,
+            **kwargs,
+        )
+        self._dataname = dataname
+        self._rate_threshold = rate_threshold
+        self._last_rate = None
+
+    def _validate_event(self, event) -> DataValidationResult:
+        """Validate funding rate specific fields beyond base validation.
+
+        Additional checks:
+            - Rate change anomaly detection
+        """
+        result = super()._validate_event(event)
+        if not result.valid:
+            return result
+
+        # Rate anomaly detection
+        if self._last_rate is not None and abs(event.rate) > self._rate_threshold:
+            result.warnings.append(
+                f"High funding rate: {event.rate} (threshold: {self._rate_threshold})"
+            )
+
+        self._last_rate = event.rate
+        return result
+
+    def load(self) -> Iterator[FundingEvent]:
+        """Load funding rate events from file.
+
+        Supports CSV and JSONL formats.
+
+        Yields:
+            FundingEvent instances.
+        """
+        if self._dataname is None:
+            raise ValueError("dataname (file path) is required for loading")
+
+        if self._dataname.endswith(".jsonl") or self._dataname.endswith(".jsonl.gz"):
+            yield from self._load_jsonl()
+        else:
+            yield from self._load_csv()
+
+    def _load_csv(self) -> Iterator[FundingEvent]:
+        """Load funding rate events from CSV format.
+
+        Supports both plain CSV and gzip-compressed CSV (.csv.gz).
+        Expects columns: timestamp, rate, mark_price. Optional columns:
+        next_funding_time, predicted_rate, symbol, exchange.
+
+        Yields:
+            FundingEvent instances.
+        """
+        if self._dataname is None:
+            raise ValueError("FundingChannel requires a 'dataname' (CSV path) to load from")
+        open_func = gzip.open if self._dataname.endswith(".gz") else open
+        open_kwargs = (
+            {"mode": "rt", "encoding": "utf-8"}
+            if self._dataname.endswith(".gz")
+            else {"mode": "r", "encoding": "utf-8", "newline": ""}
+        )
+
+        # open_func is gzip.open or builtin open; the conditionally-built
+        # open_kwargs dict can't be matched to a specific overload by mypy.
+        with open_func(self._dataname, **open_kwargs) as f:  # type: ignore[call-overload]
+            reader = csv.DictReader(f)
+
+            required = {"timestamp", "rate", "mark_price"}
+            if reader.fieldnames:
+                missing = required - set(reader.fieldnames)
+                if missing:
+                    raise ValueError(
+                        f"Missing required columns: {missing}. Found: {reader.fieldnames}"
+                    )
+
+            for row in reader:
+                try:
+                    fe = FundingEvent(
+                        timestamp=_parse_required_float(row["timestamp"]),
+                        symbol=row.get("symbol", self.symbol),
+                        exchange=row.get("exchange", ""),
+                        asset_type=row.get("asset_type", "swap"),
+                        rate=_parse_required_float(row["rate"]),
+                        mark_price=_parse_required_float(row["mark_price"]),
+                        next_funding_time=_parse_optional_float(row.get("next_funding_time"))
+                        or 0.0,
+                        predicted_rate=_parse_optional_float(row.get("predicted_rate")) or 0.0,
+                    )
+                    yield fe
+                except (ValueError, KeyError) as e:
+                    logger.warning("Skipping invalid funding row: %s (error: %s)", row, e)
+                    continue
+
+    def _load_jsonl(self) -> Iterator[FundingEvent]:
+        """Load funding rate events from JSONL format.
+
+        Supports both plain JSONL and gzip-compressed JSONL (.jsonl.gz).
+        Each line should contain a JSON object with timestamp, rate,
+        mark_price, and optional fields.
+
+        Yields:
+            FundingEvent instances.
+        """
+        if self._dataname is None:
+            raise ValueError("FundingChannel requires a 'dataname' (JSONL path) to load from")
+        open_func = gzip.open if self._dataname.endswith(".gz") else open
+        open_kwargs = {"mode": "rt", "encoding": "utf-8"}
+
+        # open_func is gzip.open or builtin open; the kwargs dict can't be
+        # matched to a specific overload by mypy.
+        with open_func(self._dataname, **open_kwargs) as f:  # type: ignore[call-overload]
+            for line_num, line in enumerate(f, 1):
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    data = json.loads(line)
+                    fe = FundingEvent(
+                        timestamp=_parse_required_float(data["timestamp"]),
+                        symbol=data.get("symbol", self.symbol),
+                        exchange=data.get("exchange", ""),
+                        asset_type=data.get("asset_type", "swap"),
+                        rate=_parse_required_float(data["rate"]),
+                        mark_price=_parse_required_float(data["mark_price"]),
+                        next_funding_time=_parse_optional_float(data.get("next_funding_time"))
+                        or 0.0,
+                        predicted_rate=_parse_optional_float(data.get("predicted_rate")) or 0.0,
+                    )
+                    yield fe
+                except (ValueError, KeyError, json.JSONDecodeError) as e:
+                    logger.warning("Skipping invalid funding JSONL line %d: %s", line_num, e)
+                    continue
+
+    def __repr__(self):
+        """Return a string representation of the channel.
+
+        Returns:
+            str: Representation showing symbol, dataname, and buffer stats.
+        """
+        return (
+            f"FundingRateChannel(symbol={self.symbol!r}, "
+            f"dataname={self._dataname!r}, "
+            f"events={self._event_count}, "
+            f"buffered={len(self._buffer)})"
+        )
+
+
+def _parse_optional_float(value) -> Optional[float]:
+    """Parse an optional float value, returning None for empty/missing.
+
+    Args:
+        value: The value to parse as a float. Can be None, empty string,
+            or any value that can be converted to float.
+
+    Returns:
+        The float value if parsing succeeds, None otherwise.
+    """
+    if value is None or value == "":
+        return None
+    try:
+        number = float(value)
+    except (ValueError, TypeError):
+        return None
+    if not math.isfinite(number):
+        return None
+    return number
+
+
+def _parse_required_float(value) -> float:
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValueError(f"Non-finite float value: {value}")
+    return number

backtrader/channels/live_queue.py

@@ -0,0 +1,216 @@
+"""Thread-safe live event queue for real-time trading.
+
+LiveEventQueue provides a thread-safe priority queue for handling events
+from multiple WebSocket connections or data sources in real-time. It uses
+threading locks and supports timeout-based blocking reads.
+
+Example::
+
+    queue = LiveEventQueue(maxsize=100000)
+
+    # Producer thread (WebSocket callback)
+    queue.put(tick_event, priority=EventPriority.TICK)
+
+    # Consumer thread (strategy processing)
+    event = queue.get(timeout=1.0)
+    if event:
+        process(event)
+"""
+
+import heapq
+import threading
+import time
+from typing import Optional, cast
+
+from ..channel import Event, EventPriority
+from ..utils.log_message import get_logger
+
+logger = get_logger(__name__)
+
+__all__ = ["LiveEventQueue"]
+
+
+class LiveEventQueue:
+    """Thread-safe priority event queue for live trading.
+
+    Events are ordered by (timestamp, priority, sequence) just like
+    StreamingEventQueue, but with thread-safety for concurrent producers
+    and consumers.
+
+    Args:
+        maxsize: Maximum queue capacity. 0 = unlimited.
+        drop_policy: What to do when full: 'drop_oldest' or 'drop_newest'.
+    """
+
+    def __init__(self, maxsize=0, drop_policy="drop_oldest"):
+        """Initialize the priority queue for live events.
+
+        Args:
+            maxsize: Maximum queue size (0 for unlimited).
+            drop_policy: Policy for dropping events when full ('drop_oldest' or 'drop_newest').
+        """
+        self._heap = []
+        self._lock = threading.Lock()
+        self._not_empty = threading.Condition(self._lock)
+        self._sequence = 0
+        self._maxsize = maxsize
+        self._drop_policy = drop_policy
+        self._total_put = 0
+        self._total_get = 0
+        self._total_dropped = 0
+        self._closed = False
+
+    def put(
+        self,
+        event_data,
+        priority=EventPriority.TICK,
+        channel_type="",
+        channel_name="",
+        timestamp=None,
+    ):
+        """Add an event to the queue (thread-safe).
+
+        Args:
+            event_data: The event data (EventData subclass).
+            priority: Event priority.
+            channel_type: Source channel type.
+            channel_name: Source channel/symbol name.
+            timestamp: Event timestamp. If None, uses event_data.timestamp
+                       or current time.
+
+        Returns:
+            True if the event was added, False if dropped.
+        """
+        if self._closed:
+            return False
+
+        if timestamp is None:
+            timestamp = getattr(event_data, "timestamp", time.time())
+
+        with self._lock:
+            event = Event(
+                timestamp=timestamp,
+                priority=priority,
+                sequence=self._sequence,
+                channel_type=channel_type,
+                channel_name=channel_name,
+                data=event_data,
+            )
+            self._sequence += 1
+
+            if self._maxsize > 0 and len(self._heap) >= self._maxsize:
+                if self._drop_policy == "drop_oldest":
+                    heapq.heapreplace(self._heap, event)
+                    self._total_dropped += 1
+                else:
+                    self._total_dropped += 1
+                    return False
+            else:
+                heapq.heappush(self._heap, event)
+
+            self._total_put += 1
+            self._not_empty.notify()
+            return True
+
+    def get(self, timeout=None) -> Optional[Event]:
+        """Get the next event from the queue (thread-safe, blocking).
+
+        Args:
+            timeout: Maximum seconds to wait. None = block forever.
+                     0 = non-blocking.
+
+        Returns:
+            The next Event, or None if timeout expired or queue is closed.
+        """
+        with self._not_empty:
+            if timeout == 0:
+                if not self._heap:
+                    return None
+            elif timeout is None:
+                while not self._heap and not self._closed:
+                    self._not_empty.wait()
+            else:
+                end_time = time.monotonic() + timeout
+                while not self._heap and not self._closed:
+                    remaining = end_time - time.monotonic()
+                    if remaining <= 0:
+                        return None
+                    self._not_empty.wait(timeout=remaining)
+
+            if not self._heap:
+                return None
+
+            event = heapq.heappop(self._heap)
+            self._total_get += 1
+            return cast(Event, event)
+
+    def peek(self) -> Optional[Event]:
+        """Peek at the next event without removing it (thread-safe)."""
+        with self._lock:
+            return self._heap[0] if self._heap else None
+
+    def close(self):
+        """Close the queue, unblocking any waiting consumers."""
+        with self._not_empty:
+            self._closed = True
+            self._not_empty.notify_all()
+
+    @property
+    def closed(self):
+        """Whether the queue has been closed."""
+        return self._closed
+
+    @property
+    def size(self):
+        """Current number of events in the queue."""
+        with self._lock:
+            return len(self._heap)
+
+    @property
+    def empty(self):
+        """Whether the queue is empty."""
+        with self._lock:
+            return len(self._heap) == 0
+
+    @property
+    def stats(self):
+        """Queue statistics."""
+        with self._lock:
+            return {
+                "total_put": self._total_put,
+                "total_get": self._total_get,
+                "total_dropped": self._total_dropped,
+                "current_size": len(self._heap),
+                "closed": self._closed,
+            }
+
+    def __len__(self):
+        """Return the current number of events in the queue.
+
+        Returns:
+            int: Number of events currently in the queue.
+        """
+        with self._lock:
+            return len(self._heap)
+
+    def __bool__(self):
+        """Return whether the queue has any events.
+
+        Returns:
+            bool: True if the queue has at least one event, False otherwise.
+        """
+        with self._lock:
+            return len(self._heap) > 0
+
+    def __repr__(self):
+        """Return a string representation of the queue.
+
+        Returns:
+            str: Representation showing size and statistics.
+        """
+        with self._lock:
+            return (
+                f"LiveEventQueue(size={len(self._heap)}, "
+                f"put={self._total_put}, get={self._total_get}, "
+                f"dropped={self._total_dropped})"
+            )