sandtable 0.1.0__tar.gz

sandtable-0.1.0/.env.example

@@ -0,0 +1,20 @@
+# .env.example
+
+# Backtester config
+# copy this file to .env and edit as needed
+#unset variables fall back to the defaults shown below
+
+# Python logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+BACKTESTER_LOG_LEVEL=INFO
+
+# Annual risk-free rate for Sharpe / Sortino ratios (decimal, e.g. 0.05 = 5%)
+BACKTESTER_RISK_FREE_RATE=0.0
+
+# Trading days per year for annualisation (252 = US equity, 365 = crypto)
+BACKTESTER_TRADING_DAYS=252
+
+# Default cache directory for downloaded data (leave empty to disable caching)
+BACKTESTER_CACHE_DIR=
+
+# Directory for script outputs (tearsheets, charts, etc.)
+BACKTESTER_OUTPUT_DIR=outputs

sandtable-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,185 @@
+# .github/workflows/publish.yml
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+  pull_request:
+    paths:
+      - 'pyproject.toml'
+      - 'src/sandtable/**'
+      - '.github/workflows/publish.yml'
+
+  push:
+    branches: [main]
+    paths:
+      - 'pyproject.toml'
+      - 'src/sandtable/**'
+      - '.github/workflows/publish.yml'
+
+  workflow_dispatch:
+
+jobs:
+  # PR + Release: build & test
+  build:
+    name: Build & test wheel
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get-version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install build hatchling
+
+      - name: Build package
+        run: python -m build
+
+      - name: Extract version
+        id: get-version
+        run: |
+          VERSION=$(ls dist/*.whl | sed 's/.*sandtable-\(.*\)-py3.*/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - name: Verify wheel installs
+        run: |
+          pip install dist/*.whl
+          python -c "import sandtable"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # -------------------------
+  # Release only: TestPyPI
+  # -------------------------
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: sandtable
+    permissions:
+      id-token: write
+    outputs:
+      test_version: ${{ steps.get-version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build deps
+        run: |
+          python -m pip install --upgrade pip
+          pip install build hatchling
+
+      - name: Add dev suffix for TestPyPI
+        run: |
+          TIMESTAMP=$(date +%Y%m%d%H%M%S)
+          VERSION=$(python - <<'PY'
+          import tomllib
+          print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])
+          PY
+          )
+          DEV_VERSION="${VERSION}.dev${TIMESTAMP}"
+          sed -i "s/version = \"$VERSION\"/version = \"$DEV_VERSION\"/" pyproject.toml
+          echo "DEV_VERSION=$DEV_VERSION" >> $GITHUB_ENV
+
+      - name: Clean dist
+        run: rm -rf dist
+
+      - name: Build TestPyPI artifacts
+        run: python -m build
+
+      - name: Extract TestPyPI version
+        id: get-version
+        run: |
+          VERSION=$(ls dist/*.whl | sed 's/.*sandtable-\(.*\)-py3.*/\1/')
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  test-install-testpypi:
+    name: Verify install from TestPyPI
+    if: github.event_name == 'release'
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install from TestPyPI
+        run: |
+          VERSION="${{ needs.publish-testpypi.outputs.test_version }}"
+          for i in {1..10}; do
+            # Package from TestPyPI, deps from PyPI
+            if uv pip install --system --pre \
+              --index-url https://test.pypi.org/simple/ \
+              --extra-index-url https://pypi.org/simple/ \
+              --index-strategy unsafe-best-match \
+              "sandtable==$VERSION"; then
+              python -c "import sandtable"
+              exit 0
+            fi
+            sleep 30
+          done
+          exit 1
+
+  # Release only: PyPI
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: test-install-testpypi
+    runs-on: ubuntu-latest
+    environment: sandtable
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  test-install-pypi:
+    name: Verify install from PyPI
+    if: github.event_name == 'release'
+    needs: [build, publish-pypi]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install from PyPI
+        run: |
+          VERSION="${{ needs.build.outputs.version }}"
+          for i in {1..10}; do
+            if uv pip install --system "sandtable==$VERSION"; then
+              python -c "import sandtable"
+              exit 0
+            fi
+            sleep 30
+          done
+          exit 1

sandtable-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,103 @@
+# .github/workflows/tests.yml
+
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('pyproject.toml') }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run pytest tests/ -v
+
+  test-install:
+    name: Test package install mechanism
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build uv
+
+      - name: Build package
+        run: python -m build
+
+      - name: Test --no-deps installs only the package
+        run: |
+          # Create fresh venv
+          python -m venv test-venv
+          source test-venv/bin/activate
+
+          # Count packages before install (pip is pre-installed)
+          BEFORE_COUNT=$(pip list --format=freeze | wc -l)
+
+          # Install with --no-deps
+          uv pip install dist/*.whl --no-deps
+
+          # Count packages after install (should be exactly 1 more: sandtable)
+          AFTER_COUNT=$(pip list --format=freeze | wc -l)
+          INSTALLED=$((AFTER_COUNT - BEFORE_COUNT))
+
+          if [[ "$INSTALLED" -ne 1 ]]; then
+            echo "ERROR: Expected 1 new package, got $INSTALLED"
+            pip list
+            exit 1
+          fi
+          echo "✓ --no-deps installed exactly 1 package (no dependencies)"
+
+      - name: Test full install from PyPI deps
+        run: |
+          source test-venv/bin/activate
+
+          # Now install normally - deps should come from PyPI
+          uv pip install dist/*.whl
+
+          # Verify import works
+          python -c "import sandtable; print('✓ sandtable imported successfully')"
+
+          # Verify deps were installed
+          PACKAGE_COUNT=$(pip list --format=freeze | wc -l)
+          if [[ "$PACKAGE_COUNT" -lt 10 ]]; then
+            echo "ERROR: Expected many packages, got $PACKAGE_COUNT"
+            exit 1
+          fi
+          echo "✓ Full install succeeded with $PACKAGE_COUNT packages"

sandtable-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Environment
+.env
+.venv/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Cache
+.cache/
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# Generated outputs
+outputs/

sandtable-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Wilcox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sandtable-0.1.0/PKG-INFO

@@ -0,0 +1,307 @@
+Metadata-Version: 2.4
+Name: sandtable
+Version: 0.1.0
+Summary: Event-driven backtesting framework with realistic execution modeling
+Project-URL: Repository, https://github.com/westimator/sandtable
+Author: Westimator
+License: MIT License
+        
+        Copyright (c) 2026 Alex Wilcox
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: <3.13,>=3.12.1
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: tabulate>=0.9
+Requires-Dist: yfinance>=0.2
+Provides-Extra: dev
+Requires-Dist: ipykernel>=6.29; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sandtable
+
+A Python backtesting framework where all components communicate exclusively through a central event queue. This design enforces temporal causality and prevents look-ahead bias by construction.
+
+## Why event-driven?
+
+Traditional backtesting frameworks often allow direct access to future data, making it easy to accidentally introduce look-ahead bias. This framework prevents that by design:
+
+1. <ins>Temporal causality:</ins> Events are processed in strict timestamp order via a priority queue
+2. <ins>No future data access:</ins> The `DataHandler` only exposes historical data up to the current bar
+3. <ins>Realistic execution:</ins> Orders are filled with configurable slippage, market impact, and commissions
+4. <ins>Clear data flow:</ins> Events flow in one direction: `MARKET_DATA → SIGNAL → ORDER → FILL`
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│ DataHandler │────▶│  Strategy   │────▶│  Portfolio  │────▶│  Executor   │
+│ (bars)      │     │  (signals)  │     │  (orders)   │     │  (fills)    │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+       │                   │                   │                   │
+       └───────────────────┴───────────────────┴───────────────────┘
+                                    │
+                           ┌────────▼────────┐
+                           │   Event Queue   │
+                           │  (priority by   │
+                           │   timestamp)    │
+                           └─────────────────┘
+```
+
+## Setup
+
+Requires Python 3.12 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+# install uv (if you don't have it)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# create venv and install dependencies
+uv sync
+
+# install with all extras (yfinance, matplotlib, plotly)
+uv pip install -e ".[all]"
+
+# or with dev dependencies (pytest, ruff, viz, reports)
+uv pip install -e ".[dev]"
+```
+
+## Quick start
+
+### One-liner API
+
+```python
+from sandtable import run_backtest, AbstractStrategy, SignalEvent, MarketDataEvent, Direction, FixedSlippage
+
+class MeanReversion(AbstractStrategy):
+    lookback: int = 20
+    threshold: float = 2.0
+
+    def generate_signal(self, bar: MarketDataEvent) -> SignalEvent | None:
+        closes = self.get_historical_closes(self.lookback)
+        if len(closes) < self.lookback:
+            return None
+        mean = sum(closes) / len(closes)
+        std = (sum((c - mean) ** 2 for c in closes) / len(closes)) ** 0.5
+        if std == 0:
+            return None
+        z_score = (bar.close - mean) / std
+        if z_score < -self.threshold:
+            return SignalEvent(
+                timestamp=bar.timestamp, symbol=bar.symbol,
+                direction=Direction.LONG, strength=1.0,
+            )
+        return None
+
+result = run_backtest(
+    strategy=MeanReversion(),
+    symbols="SPY",
+    start="2022-01-01", end="2023-12-31",
+    slippage=FixedSlippage(bps=5),
+    commission=0.005,
+)
+print(result.metrics)
+result.tearsheet("tearsheet.html")
+```
+
+### Parameter sweep
+
+```python
+from sandtable import Metric, run_parameter_sweep
+
+sweep = run_parameter_sweep(
+    strategy_class=MeanReversion,
+    param_grid={"lookback": [10, 20, 30], "threshold": [1.5, 2.0, 2.5]},
+    symbols="SPY",
+    start="2022-01-01", end="2023-12-31",
+    metric=Metric.SHARPE_RATIO,
+)
+print(sweep.best_params)
+print(sweep.to_dataframe())
+```
+
+### Run the example
+
+```bash
+uv run python examples/quick_start.py
+```
+
+## Usage
+
+### Basic backtest (manual wiring)
+
+```python
+from sandtable import CSVDataHandler, MACrossoverStrategy
+from sandtable.core import Backtest
+from sandtable.execution import ExecutionConfig, ExecutionSimulator, FixedSlippage
+from sandtable.portfolio import Portfolio
+
+# set up components
+data = CSVDataHandler("data/sample_ohlcv.csv", "SPY")
+strategy = MACrossoverStrategy(fast_period=10, slow_period=30)
+portfolio = Portfolio(initial_capital=100_000)
+executor = ExecutionSimulator(
+    config=ExecutionConfig(commission_per_share=0.005),
+    slippage_model=FixedSlippage(bps=5),
+)
+
+# run backtest
+backtest = Backtest(data, strategy, portfolio, executor)
+metrics = backtest.run()
+print(metrics)
+```
+
+### Custom strategy
+
+```python
+from sandtable import AbstractStrategy, MarketDataEvent, SignalEvent, Direction
+
+class MyStrategy(AbstractStrategy):
+    def generate_signal(self, bar: MarketDataEvent) -> SignalEvent | None:
+        closes = self.get_historical_closes(20)
+        if len(closes) < 20:
+            return None  # warmup period
+
+        # [your logic here]
+        if closes[-1] > sum(closes) / len(closes):
+            return SignalEvent(
+                timestamp=bar.timestamp,
+                symbol=bar.symbol,
+                direction=Direction.LONG,
+                strength=1.0,
+            )
+        return None
+```
+
+### Multi-symbol backtest
+
+```python
+from sandtable import run_backtest
+
+result = run_backtest(
+    strategy=MyStrategy(),
+    symbols=["SPY", "QQQ", "IWM"],
+    start="2022-01-01", end="2023-12-31",
+)
+```
+
+### Tearsheet and comparison
+
+```python
+# Single strategy tearsheet
+result.tearsheet("tearsheet.html")
+
+# Compare multiple strategies
+from sandtable import compare_strategies
+
+compare_strategies(
+    {"Strategy A": result_a, "Strategy B": result_b},
+    output_path="comparison.html",
+)
+```
+
+### Execution models
+
+```python
+from sandtable.execution import (
+    ExecutionConfig, ExecutionSimulator,
+    ZeroSlippage, FixedSlippage, SpreadSlippage,
+    NoMarketImpact, SquareRootImpactModel,
+)
+
+# no transaction costs (unrealistic baseline)
+executor = ExecutionSimulator(
+    slippage_model=ZeroSlippage(),
+    impact_model=NoMarketImpact(),
+)
+
+# realistic costs
+executor = ExecutionSimulator(
+    config=ExecutionConfig(
+        commission_per_share=0.005,
+        commission_minimum=1.0,
+    ),
+    slippage_model=FixedSlippage(bps=5),
+    impact_model=SquareRootImpactModel(eta=0.1),
+)
+```
+
+## Project structure
+
+```
+sandtable/
+├── src/sandtable/
+│   ├── __init__.py        # Public API exports
+│   ├── api.py             # run_backtest(), run_parameter_sweep()
+│   ├── core/              # Events, queue, backtest engine, result
+│   ├── data_handlers/     # DataHandler protocol, CSV, yfinance, multi-symbol
+│   ├── strategy/          # Strategy base class and implementations
+│   ├── execution/         # Slippage, impact, and fill simulation
+│   ├── portfolio/         # Position and cash management
+│   ├── metrics/           # Performance calculation
+│   ├── report/            # HTML tearsheet and strategy comparison
+│   └── viz/               # matplotlib charts and animation
+├── tests/                 # Unit tests
+├── data/                  # Sample OHLCV data
+├── examples/              # Example scripts
+└── pyproject.toml
+```
+
+## Running tests
+
+```bash
+# run all tests
+uv run python -m pytest
+
+# run with verbose output
+uv run python -m pytest -v
+
+# run specific test file
+uv run python -m pytest tests/core/test_event_queue.py
+
+# run with coverage
+uv run python -m coverage run --include="src/sandtable/*" -m pytest tests/
+uv run python -m coverage report --show-missing
+```
+
+## Design decisions
+
+1. <ins>Lookahead Prevention:</ins> `DataHandler.get_historical_bars(n)` only returns data before the current index
+2. <ins>Event Ordering:</ins> Priority queue with `(timestamp, counter)` ensures correct ordering and FIFO for same-timestamp events
+3. <ins>Fill Price Bounds:</ins> Fill prices are clamped to the bar's `[low, high]` range
+4. <ins>Short Positions:</ins> Cash increases on short sale, decreases on cover, with correct P&L tracking
+5. <ins>Warmup Period:</ins> Strategies return `None` until they have enough data for their indicators
+6. <ins>Multi-symbol:</ins> `MultiDataHandler` merges bars from multiple sources via min-heap for correct temporal ordering
+
+## Performance metrics
+
+The `PerformanceMetrics` dataclass includes:
+
+| Category | Metrics |
+|----------|---------|
+| Returns | `total_return`, `cagr` |
+| Risk | `sharpe_ratio`, `sortino_ratio`, `max_drawdown` |
+| Trades | `num_trades`, `win_rate`, `profit_factor`, `avg_trade_pnl` |
+
+## License
+
+See [LICENSE](LICENSE) file.