Qubx 0.6.66__tar.gz → 0.6.68__tar.gz

{qubx-0.6.66 → qubx-0.6.68}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Qubx
-Version: 0.6.66
+Version: 0.6.68
 Summary: Qubx - Quantitative Trading Framework
 Author: Dmitry Marienko
 Author-email: dmitry.marienko@xlydian.com
@@ -19,6 +19,7 @@ Requires-Dist: dash-bootstrap-components (>=1.6.0,<2.0.0)
 Requires-Dist: gitpython (>=3.1.44,<4.0.0)
 Requires-Dist: importlib-metadata
 Requires-Dist: ipywidgets (>=8.1.5,<9.0.0)
+Requires-Dist: jinja2 (>=3.1.0,<4.0.0)
 Requires-Dist: jupyter (>=1.1.1,<2.0.0)
 Requires-Dist: jupyter-console (>=6.6.3,<7.0.0)
 Requires-Dist: loguru (>=0.7.2,<0.8.0)
@@ -69,6 +70,49 @@ Description-Content-Type: text/markdown
 
 Qubx is a next-generation quantitative trading framework designed for efficient backtesting and live trading. Built with Python, it offers a robust environment for developing, testing, and deploying trading strategies.
 
+## Quick Start
+
+### 1. Install Dependencies
+```bash
+poetry install
+```
+
+### 2. Create a Strategy
+```bash
+# Create a simple strategy template (default)
+poetry run qubx init
+
+# Or specify a name and symbols
+poetry run qubx init --name my_strategy --symbols BTCUSDT,ETHUSDT
+```
+
+### 3. Run Your Strategy
+```bash
+cd my_strategy
+
+# Run in paper trading mode
+poetry run qubx run config.yml --paper
+
+# Or run in Jupyter mode for interactive development
+./jpaper.sh
+```
+
+### Available Templates
+```bash
+# List available strategy templates
+poetry run qubx init --list-templates
+
+# Create strategy with full project structure and MACD example
+poetry run qubx init --template project --name my_project
+```
+
+### Strategy Development Workflow
+1. **Initialize**: `poetry run qubx init` - Create strategy from template
+2. **Develop**: Edit `strategy.py` to implement your trading logic
+3. **Test**: `poetry run qubx run config.yml --paper` - Run in paper mode
+4. **Debug**: `./jpaper.sh` - Use Jupyter for interactive development
+5. **Deploy**: Configure for live trading when ready
+
 ## Features
 
 - 🚀 High-performance backtesting engine
@@ -119,11 +163,13 @@ qubx --help  # Show all available commands
 
 Available commands:
 
-- `qubx deploy` - Deploy a strategy from a zip file
-- `qubx ls` - List all strategies in a directory
-- `qubx release` - Package a strategy into a zip file
+- `qubx init` - Create a new strategy from template
 - `qubx run` - Start a strategy with given configuration
 - `qubx simulate` - Run strategy simulation
+- `qubx ls` - List all strategies in a directory
+- `qubx release` - Package a strategy into a zip file
+- `qubx deploy` - Deploy a strategy from a zip file
+- `qubx browse` - Browse backtest results using interactive TUI
 
 ## Development
 

{qubx-0.6.66 → qubx-0.6.68}/README.md

@@ -11,6 +11,49 @@
 
 Qubx is a next-generation quantitative trading framework designed for efficient backtesting and live trading. Built with Python, it offers a robust environment for developing, testing, and deploying trading strategies.
 
+## Quick Start
+
+### 1. Install Dependencies
+```bash
+poetry install
+```
+
+### 2. Create a Strategy
+```bash
+# Create a simple strategy template (default)
+poetry run qubx init
+
+# Or specify a name and symbols
+poetry run qubx init --name my_strategy --symbols BTCUSDT,ETHUSDT
+```
+
+### 3. Run Your Strategy
+```bash
+cd my_strategy
+
+# Run in paper trading mode
+poetry run qubx run config.yml --paper
+
+# Or run in Jupyter mode for interactive development
+./jpaper.sh
+```
+
+### Available Templates
+```bash
+# List available strategy templates
+poetry run qubx init --list-templates
+
+# Create strategy with full project structure and MACD example
+poetry run qubx init --template project --name my_project
+```
+
+### Strategy Development Workflow
+1. **Initialize**: `poetry run qubx init` - Create strategy from template
+2. **Develop**: Edit `strategy.py` to implement your trading logic
+3. **Test**: `poetry run qubx run config.yml --paper` - Run in paper mode
+4. **Debug**: `./jpaper.sh` - Use Jupyter for interactive development
+5. **Deploy**: Configure for live trading when ready
+
 ## Features
 
 - 🚀 High-performance backtesting engine
@@ -61,11 +104,13 @@ qubx --help  # Show all available commands
 
 Available commands:
 
-- `qubx deploy` - Deploy a strategy from a zip file
-- `qubx ls` - List all strategies in a directory
-- `qubx release` - Package a strategy into a zip file
+- `qubx init` - Create a new strategy from template
 - `qubx run` - Start a strategy with given configuration
 - `qubx simulate` - Run strategy simulation
+- `qubx ls` - List all strategies in a directory
+- `qubx release` - Package a strategy into a zip file
+- `qubx deploy` - Deploy a strategy from a zip file
+- `qubx browse` - Browse backtest results using interactive TUI
 
 ## Development
 

{qubx-0.6.66 → qubx-0.6.68}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "Qubx"
-version = "0.6.66"
+version = "0.6.68"
 description = "Qubx - Quantitative Trading Framework"
 authors = [ "Dmitry Marienko <dmitry.marienko@xlydian.com>", "Yuriy Arabskyy <yuriy.arabskyy@xlydian.com>",]
 readme = "README.md"
@@ -76,6 +76,7 @@ websockets = "15.0.1"
 qubx-bitfinex-api = "^3.0.7"
 textual = "^0.88.0"
 rich = "^13.9.4"
+jinja2 = "^3.1.0"
 
 [tool.ruff.lint]
 extend-select = [ "I",]

{qubx-0.6.66 → qubx-0.6.68}/src/qubx/backtester/data.py

@@ -1,4 +1,5 @@
 from collections import defaultdict
+from typing import Any, TypeVar
 
 import pandas as pd
 
@@ -19,6 +20,17 @@ from qubx.utils.time import infer_series_frequency
 from .account import SimulatedAccountProcessor
 from .utils import SimulatedTimeProvider
 
+T = TypeVar("T")
+
+
+def _get_first_existing(data: dict, keys: list, default: T = None) -> T:
+    data_get = data.get  # Cache method lookup
+    sentinel = object()
+    for key in keys:
+        if (value := data_get(key, sentinel)) is not sentinel:
+            return value
+    return default
+
 
 class SimulatedDataProvider(IDataProvider):
     time_provider: SimulatedTimeProvider
@@ -164,8 +176,13 @@ class SimulatedDataProvider(IDataProvider):
                     r.data["high"],
                     r.data["low"],
                     r.data["close"],
-                    r.data.get("volume", 0),
-                    r.data.get("bought_volume", 0),
+                    volume=r.data.get("volume", 0),
+                    bought_volume=_get_first_existing(r.data, ["taker_buy_volume", "bought_volume"], 0),
+                    volume_quote=_get_first_existing(r.data, ["quote_volume", "volume_quote"], 0),
+                    bought_volume_quote=_get_first_existing(
+                        r.data, ["taker_buy_quote_volume", "bought_volume_quote"], 0
+                    ),
+                    trade_count=_get_first_existing(r.data, ["count", "trade_count"], 0),
                 )
             )
 

{qubx-0.6.66 → qubx-0.6.68}/src/qubx/cli/commands.py

@@ -275,5 +275,130 @@ def browse(results_path: str):
     run_backtest_browser(results_path)
 
 
+@main.command()
+@click.option(
+    "--template",
+    "-t",
+    type=str,
+    default="simple",
+    help="Built-in template to use (default: simple)",
+    show_default=True,
+)
+@click.option(
+    "--template-path",
+    type=click.Path(exists=True, resolve_path=True),
+    help="Path to custom template directory",
+)
+@click.option(
+    "--name",
+    "-n",
+    type=str,
+    default="my_strategy",
+    help="Name of the strategy to create",
+    show_default=True,
+)
+@click.option(
+    "--exchange",
+    "-e",
+    type=str,
+    default="BINANCE.UM",
+    help="Exchange to configure for the strategy",
+    show_default=True,
+)
+@click.option(
+    "--symbols",
+    "-s",
+    type=str,
+    default="BTCUSDT",
+    help="Comma-separated list of symbols to trade",
+    show_default=True,
+)
+@click.option(
+    "--timeframe",
+    type=str,
+    default="1h",
+    help="Timeframe for market data",
+    show_default=True,
+)
+@click.option(
+    "--output-dir",
+    "-o",
+    type=click.Path(resolve_path=True),
+    default=".",
+    help="Directory to create the strategy in",
+    show_default=True,
+)
+@click.option(
+    "--list-templates",
+    is_flag=True,
+    help="List all available built-in templates",
+)
+def init(
+    template: str,
+    template_path: str | None,
+    name: str,
+    exchange: str,
+    symbols: str,
+    timeframe: str,
+    output_dir: str,
+    list_templates: bool,
+):
+    """
+    Create a new strategy from a template.
+    
+    This command generates a complete strategy project structure with:
+    - Strategy class implementing IStrategy interface
+    - Configuration file for qubx run command
+    - Package structure for proper imports
+    
+    The generated strategy can be run immediately with:
+    poetry run qubx run --config config.yml --paper
+    """
+    from qubx.templates import TemplateManager, TemplateError
+    
+    try:
+        manager = TemplateManager()
+        
+        if list_templates:
+            templates = manager.list_templates()
+            if not templates:
+                click.echo("No templates available.")
+                return
+            
+            click.echo("Available templates:")
+            for template_name, metadata in templates.items():
+                description = metadata.get("description", "No description")
+                click.echo(f"  {template_name:<15} - {description}")
+            return
+        
+        # Generate strategy
+        strategy_path = manager.generate_strategy(
+            template_name=template if not template_path else None,
+            template_path=template_path,
+            output_dir=output_dir,
+            name=name,
+            exchange=exchange,
+            symbols=symbols,
+            timeframe=timeframe,
+        )
+        
+        click.echo(f"✅ Strategy '{name}' created successfully!")
+        click.echo(f"📁 Location: {strategy_path}")
+        click.echo()
+        click.echo("To run your strategy:")
+        click.echo(f"  cd {strategy_path}")
+        click.echo("  poetry run qubx run config.yml --paper")
+        click.echo()
+        click.echo("To run in Jupyter mode:")
+        click.echo("  ./jpaper.sh")
+        
+    except TemplateError as e:
+        click.echo(f"❌ Template error: {e}", err=True)
+        raise click.Abort()
+    except Exception as e:
+        click.echo(f"❌ Unexpected error: {e}", err=True)
+        raise click.Abort()
+
+
 if __name__ == "__main__":
     main()

qubx-0.6.68/src/qubx/connectors/ccxt/connection_manager.py

@@ -0,0 +1,310 @@
+"""
+Connection management for CCXT data provider.
+
+This module handles WebSocket connections, retry logic, and stream lifecycle management,
+separating connection concerns from subscription state and data handling.
+"""
+
+import asyncio
+import concurrent.futures
+from asyncio.exceptions import CancelledError
+from collections import defaultdict
+from typing import Awaitable, Callable, Dict
+
+from ccxt import ExchangeClosedByUser, ExchangeError, ExchangeNotAvailable, NetworkError
+from ccxt.pro import Exchange
+from qubx import logger
+from qubx.core.basics import CtrlChannel
+
+from .exceptions import CcxtSymbolNotRecognized
+from .subscription_manager import SubscriptionManager
+
+
+class ConnectionManager:
+    """
+    Manages WebSocket connections and stream lifecycle for CCXT data provider.
+    
+    Responsibilities:
+    - Handle WebSocket connection establishment and management
+    - Implement retry logic and error handling
+    - Manage stream lifecycle (start, stop, cleanup)
+    - Coordinate with SubscriptionManager for state updates
+    """
+    
+    def __init__(
+        self, 
+        exchange_id: str, 
+        max_ws_retries: int = 10,
+        subscription_manager: SubscriptionManager | None = None
+    ):
+        self._exchange_id = exchange_id
+        self.max_ws_retries = max_ws_retries
+        self._subscription_manager = subscription_manager
+        
+        # Stream state management
+        self._is_stream_enabled: Dict[str, bool] = defaultdict(lambda: False)
+        self._stream_to_unsubscriber: Dict[str, Callable[[], Awaitable[None]]] = {}
+        
+        # Connection tracking
+        self._stream_to_coro: Dict[str, concurrent.futures.Future] = {}
+    
+    def set_subscription_manager(self, subscription_manager: SubscriptionManager) -> None:
+        """Set the subscription manager for state coordination."""
+        self._subscription_manager = subscription_manager
+    
+    async def listen_to_stream(
+        self,
+        subscriber: Callable[[], Awaitable[None]],
+        exchange: Exchange,
+        channel: CtrlChannel,
+        stream_name: str,
+        unsubscriber: Callable[[], Awaitable[None]] | None = None,
+    ) -> None:
+        """
+        Listen to a WebSocket stream with error handling and retry logic.
+        
+        Args:
+            subscriber: Async function that handles the stream data
+            exchange: CCXT exchange instance
+            channel: Control channel for data flow
+            stream_name: Unique name for this stream
+            unsubscriber: Optional cleanup function for graceful unsubscription
+        """
+        logger.info(f"<yellow>{self._exchange_id}</yellow> Listening to {stream_name}")
+        
+        # Register unsubscriber for cleanup
+        if unsubscriber is not None:
+            self._stream_to_unsubscriber[stream_name] = unsubscriber
+        
+        # Enable the stream
+        self._is_stream_enabled[stream_name] = True
+        n_retry = 0
+        connection_established = False
+        
+        while channel.control.is_set() and self._is_stream_enabled[stream_name]:
+            try:
+                await subscriber()
+                n_retry = 0  # Reset retry counter on success
+                
+                # Mark subscription as active on first successful data reception
+                if not connection_established and self._subscription_manager:
+                    subscription_type = self._subscription_manager.find_subscription_type_by_name(stream_name)
+                    if subscription_type:
+                        self._subscription_manager.mark_subscription_active(subscription_type)
+                        connection_established = True
+                
+                # Check if stream was disabled during subscriber execution
+                if not self._is_stream_enabled[stream_name]:
+                    break
+                    
+            except CcxtSymbolNotRecognized:
+                # Skip unrecognized symbols but continue listening
+                continue
+            except CancelledError:
+                # Graceful cancellation
+                break
+            except ExchangeClosedByUser:
+                # Connection closed by us, stop gracefully
+                logger.info(f"<yellow>{self._exchange_id}</yellow> {stream_name} listening has been stopped")
+                break
+            except (NetworkError, ExchangeError, ExchangeNotAvailable) as e:
+                # Network/exchange errors - retry after short delay
+                logger.error(f"<yellow>{self._exchange_id}</yellow> {e.__class__.__name__} :: Error in {stream_name} : {e}")
+                await asyncio.sleep(1)
+                continue
+            except Exception as e:
+                # Unexpected errors
+                if not channel.control.is_set() or not self._is_stream_enabled[stream_name]:
+                    # Channel closed or stream disabled, exit gracefully
+                    break
+                
+                logger.error(f"<yellow>{self._exchange_id}</yellow> Exception in {stream_name}: {e}")
+                logger.exception(e)
+                
+                n_retry += 1
+                if n_retry >= self.max_ws_retries:
+                    logger.error(
+                        f"<yellow>{self._exchange_id}</yellow> Max retries reached for {stream_name}. Closing connection."
+                    )
+                    # Clean up exchange reference to force reconnection
+                    del exchange
+                    break
+                
+                # Exponential backoff with cap at 60 seconds
+                await asyncio.sleep(min(2**n_retry, 60))
+        
+        # Stream ended, cleanup
+        logger.debug(f"<yellow>{self._exchange_id}</yellow> Stream {stream_name} ended")
+    
+    async def stop_stream(
+        self, 
+        stream_name: str, 
+        future: concurrent.futures.Future | None = None,
+        is_resubscription: bool = False
+    ) -> None:
+        """
+        Stop a stream gracefully with proper cleanup.
+        
+        Args:
+            stream_name: Name of the stream to stop
+            future: Optional future representing the stream task
+            is_resubscription: True if this is stopping an old stream during resubscription
+        """
+        try:
+            context = "old stream" if is_resubscription else "stream"
+            logger.debug(f"<yellow>{self._exchange_id}</yellow> Stopping {context} {stream_name}")
+            
+            # Disable the stream to signal it should stop
+            self._is_stream_enabled[stream_name] = False
+            
+            # Wait for the stream to stop naturally
+            if future:
+                total_sleep_time = 0.0
+                while future.running() and total_sleep_time < 20.0:
+                    await asyncio.sleep(1.0)
+                    total_sleep_time += 1.0
+                
+                if future.running():
+                    logger.warning(
+                        f"<yellow>{self._exchange_id}</yellow> {context.title()} {stream_name} is still running. Cancelling it."
+                    )
+                    future.cancel()
+                else:
+                    logger.debug(f"<yellow>{self._exchange_id}</yellow> {context.title()} {stream_name} has been stopped")
+            
+            # Run unsubscriber if available
+            if stream_name in self._stream_to_unsubscriber:
+                logger.debug(f"<yellow>{self._exchange_id}</yellow> Unsubscribing from {stream_name}")
+                await self._stream_to_unsubscriber[stream_name]()
+                del self._stream_to_unsubscriber[stream_name]
+            
+            # Clean up stream state
+            if is_resubscription:
+                # For resubscription, only clean up if the stream is actually disabled
+                # (avoid interfering with new streams using the same name)
+                if stream_name in self._is_stream_enabled and not self._is_stream_enabled[stream_name]:
+                    del self._is_stream_enabled[stream_name]
+            else:
+                # For regular stops, always clean up completely
+                self._is_stream_enabled.pop(stream_name, None)
+                self._stream_to_coro.pop(stream_name, None)
+            
+            logger.debug(f"<yellow>{self._exchange_id}</yellow> {context.title()} {stream_name} stopped")
+            
+        except Exception as e:
+            logger.error(f"<yellow>{self._exchange_id}</yellow> Error stopping {stream_name}")
+            logger.exception(e)
+    
+    def register_stream_future(
+        self, 
+        stream_name: str, 
+        future: concurrent.futures.Future
+    ) -> None:
+        """
+        Register a future for a stream for tracking and cleanup.
+        
+        Args:
+            stream_name: Name of the stream
+            future: Future representing the stream task
+        """
+        self._stream_to_coro[stream_name] = future
+    
+    def is_stream_enabled(self, stream_name: str) -> bool:
+        """
+        Check if a stream is enabled.
+        
+        Args:
+            stream_name: Name of the stream to check
+            
+        Returns:
+            True if stream is enabled, False otherwise
+        """
+        return self._is_stream_enabled.get(stream_name, False)
+    
+    def get_stream_future(self, stream_name: str) -> concurrent.futures.Future | None:
+        """
+        Get the future for a stream.
+        
+        Args:
+            stream_name: Name of the stream
+            
+        Returns:
+            Future if exists, None otherwise
+        """
+        return self._stream_to_coro.get(stream_name)
+    
+    def disable_stream(self, stream_name: str) -> None:
+        """
+        Disable a stream (signal it to stop).
+        
+        Args:
+            stream_name: Name of the stream to disable
+        """
+        self._is_stream_enabled[stream_name] = False
+    
+    def enable_stream(self, stream_name: str) -> None:
+        """
+        Enable a stream.
+        
+        Args:
+            stream_name: Name of the stream to enable
+        """
+        self._is_stream_enabled[stream_name] = True
+    
+    def set_stream_unsubscriber(
+        self, 
+        stream_name: str, 
+        unsubscriber: Callable[[], Awaitable[None]]
+    ) -> None:
+        """
+        Set unsubscriber function for a stream.
+        
+        Args:
+            stream_name: Name of the stream
+            unsubscriber: Async function to call for unsubscription
+        """
+        self._stream_to_unsubscriber[stream_name] = unsubscriber
+    
+    def get_stream_unsubscriber(self, stream_name: str) -> Callable[[], Awaitable[None]] | None:
+        """
+        Get unsubscriber function for a stream.
+        
+        Args:
+            stream_name: Name of the stream
+            
+        Returns:
+            Unsubscriber function if exists, None otherwise
+        """
+        return self._stream_to_unsubscriber.get(stream_name)
+    
+    def set_stream_coro(
+        self, 
+        stream_name: str, 
+        coro: concurrent.futures.Future
+    ) -> None:
+        """
+        Set coroutine/future for a stream.
+        
+        Args:
+            stream_name: Name of the stream
+            coro: Future representing the stream task
+        """
+        self._stream_to_coro[stream_name] = coro
+    
+    def get_stream_coro(self, stream_name: str) -> concurrent.futures.Future | None:
+        """
+        Get coroutine/future for a stream.
+        
+        Args:
+            stream_name: Name of the stream
+            
+        Returns:
+            Future if exists, None otherwise
+        """
+        return self._stream_to_coro.get(stream_name)
+
+    def cleanup_all_streams(self) -> None:
+        """Clean up all stream state (for shutdown)."""
+        self._is_stream_enabled.clear()
+        self._stream_to_unsubscriber.clear()
+        self._stream_to_coro.clear()