py-backtesting-lib 0.1.0__py3-none-any.whl

py_backtesting_lib-0.1.0.dist-info/METADATA

@@ -0,0 +1,281 @@
+Metadata-Version: 2.4
+Name: py-backtesting-lib
+Version: 0.1.0
+Summary: A modular, experiment-driven framework for deterministic trading strategy backtests.
+Project-URL: Homepage, https://github.com/zhirodadkhah/python-bakctesting-lib
+Project-URL: Repository, https://github.com/zhirodadkhah/python-bakctesting-lib
+Project-URL: Documentation, https://github.com/zhirodadkhah/python-bakctesting-lib/tree/main/docs
+Author-email: "Abdullah Dadkhah (Zhiro)" <zhirodadkhah@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=0.9.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# py-backtesting-lib
+
+**Project:** Python Backtesting  
+**Purpose:** A modular, experiment-driven framework for executing deterministic trading strategy backtests. It separates strategy logic, money management, execution simulation, and analysis into independent, plugin-based components.  
+**Maintainer:** Abdullah Dadkhah (Zhiro)  
+**Last Updated:** 2026-07-25  
+
+---
+
+## Overview
+This project is a Python framework for running deterministic backtests on historical market data. It shifts the paradigm from "running strategies" to "running experiments."
+
+The framework is built on Domain-Driven Design principles, strictly separating the Definition of a backtest from its Execution and Analysis. By treating the `Experiment` as the aggregate root and enforcing pure-data configurations, it allows researchers to evaluate, compare, and reproduce trading systems with scientific rigor.
+
+## Vision
+Trading research often mixes strategy logic with execution, position management, and reporting, making strategies difficult to reuse, debug, and compare.
+
+This framework aims to provide a clean, decoupled simulation environment where:
+*   **Strategies** only decide what they want to do (emitting pure `Signals`).
+*   **Money Managers** decide how much to trade (sizing `Signals` into `Orders`).
+*   **The Execution Engine** simulates the broker (processing `Orders` into `Fills`).
+*   **The Books & Portfolio** track the exact state (Order, Position, and Trade books).
+*   **The Event Bus** records every micro-action as an immutable artifact.
+*   **Analysis Plugins** consume the final results to produce metrics and reports.
+
+The goal is to make every backtest 100% reproducible, infinitely extensible, and easy to analyze.
+
+## Core Architecture
+The framework is divided into three distinct Bounded Contexts:
+
+### 1. Experiment Definition (The "What")
+Everything needed to describe a backtest. Contains no execution logic.
+*   **Plugin Registry:** Catalog of available Strategies, Money Managers, Brokers, and Reporters.
+*   **Pure Data Configurations:** Serializable parameters (YAML/JSON) that bind to plugins using a standardized two-part structure: `name` (plugin identifier) + `params` (flexible configuration dictionary).
+*   **The Experiment:** The aggregate root that encapsulates the entire setup. Validates that all plugin `name` fields resolve to registered implementations.
+
+### 2. Execution (The "How")
+The "dumb" orchestrator and runtime objects. It knows nothing of reporting or persistence.
+*   **Execution Engine:** The synchronous, single-threaded event loop that iterates over market data bar-by-bar.
+*   **The Pipeline:** `Strategy` → `Signal` → `Money Manager` → `Order` → `Broker` → `Fill`.
+*   **The Books:** Separated subsystems for `OrderBook`, `PositionBook`, and `TradeBook` (state is mutated only via `apply_` methods driven by events).
+*   **Event Bus:** An immutable event log (`SignalGenerated`, `OrderFilled`, etc.) allowing full state reconstruction.
+*   **Mark-to-Market First:** Portfolio equity is updated with current market prices before strategies generate signals on each new bar.
+
+### 3. Analysis (The "Result")
+Consumes the output of the execution to produce insights.
+*   **Experiment Result:** An immutable aggregate containing final Portfolio state, Book snapshots, and the full Event Log.
+*   **Report Plugins:** Modular analyzers that are pure functions of the `ExperimentResult`.
+*   **Event Persistence:** All domain events are persisted to DuckDB/SQLite as they occur, enabling full state reconstruction by replaying events from disk.
+
+## Features
+*   **Experiment-Driven Reproducibility:** Save the exact state of a backtest in a single YAML file. Rerun it years later with identical results.
+*   **Plugin Architecture:** Easily swap Strategies, Money Managers, Brokers, and Reporters without touching the core engine.
+*   **First-Class Signals:** Strategies emit intent (`Signal`) rather than orders, completely decoupling alpha generation from risk/account sizing.
+*   **Immutable Event Sourcing:** Every state change is logged as an event. Debug any point in the backtest by replaying the event log.
+*   **Separated State Books:** Clean separation of `OrderBook`, `PositionBook`, and `TradeBook`. Trades are only archived when net position hits zero.
+*   **Deterministic Execution:** Guaranteed identical results across runs. Single-threaded, synchronous loop prevents concurrency non-determinism.
+*   **Financial Precision:** Uses Python's `Decimal` for all financial math to prevent IEEE 754 floating-point drift.
+
+## Scope
+**In Scope:** Historical backtest execution, experiment definition, plugin architecture, first-class Signal/Order management, broker simulation, separated state tracking, portfolio management, immutable event logging, console reporting, CLI interface, CSV/Dummy Market Data, DuckDB persistence.
+
+**Out of Scope:** Live broker APIs, technical indicator libraries, ML models, parameter optimization (grid search), GUI/dashboards, live websockets, cloud storage.
+
+---
+
+## Configuration
+Instead of writing code to configure a run, you define an Experiment using pure data. The framework uses a strict `name` + `params` structure for all plugins.
+
+**Example `experiments/beta_test.yaml`:**
+```yaml
+experiment:
+  name: "SMA Crossover Beta Test"
+  metadata:
+    author: "Zhiro"
+    version: "1.0"
+  
+  configs:
+    strategy:
+      name: "SMA_Crossover_Strategy"
+      params:
+        fast_period: 5
+        slow_period: 10
+        symbol: "DUMMY"
+        
+    money_management:
+      name: "Fixed_Qty_MoneyManager"
+      params:
+        trade_quantity: 10.0
+        
+    broker:
+      name: "Simple_Market_Broker"
+      params:
+        commission_per_trade: 1.50
+        initial_capital: 100000
+        
+    market_data:
+      name: "Dummy_Market_Data"
+      params:
+        num_bars: 50
+        symbol: "DUMMY"
+        start_price: 100.0
+```
+
+---
+
+## Sample Plugins vs. Custom Implementation
+
+To help you get started and verify the framework is working, this repository includes a `plugins/` directory with **Sample Plugins** (SMA Crossover Strategy, Fixed Quantity Money Manager, Simple Market Broker, and Dummy Market Data). These are used for the integrated beta test.
+
+### ⚠️ Important: You Must Implement Your Own Plugins
+The framework provides the **Engine**, the **Interfaces**, and the **Event Sourcing** infrastructure. It **does not** provide a library of trading strategies or alpha signals. 
+
+The sample plugins in the `plugins/` directory are strictly for demonstration and testing purposes. To run your own trading logic, you must:
+1. Create your own Python classes that inherit from the base interfaces located in `Backtesting/definition/plugins/base_interfaces.py` (`Strategy`, `MoneyManager`, `Broker`, `MarketDataProvider`).
+2. Register them in the `PluginRegistry` (usually done in your plugin module's `__init__.py`).
+3. Reference their registered `name` in your YAML configuration file.
+
+---
+
+## Running the Backtest
+
+There are two ways to interact with this project: via the **CLI** (for quick runs and testing) or as a **Framework** (for integration into larger research pipelines).
+
+### 1. Running via CLI (`main.py`)
+The CLI is built using Typer. Because there is currently only one command (`run`), Typer makes it the default. Therefore, you **do not** type the word "run" in the command.
+
+**Command:**
+```bash
+python -m Backtesting.main -c experiments/beta_test.yaml
+# OR
+python -m Backtesting.main --config experiments/beta_test.yaml
+```
+*Note: Always execute via `python -m Backtesting.main` to ensure relative imports resolve correctly.*
+
+### 2. Using as a Framework (Python API)
+If you want to integrate the backtesting engine into a larger Python application, a Jupyter Notebook, or an optimization loop, you can import the core components directly:
+
+```python
+from Backtesting.definition import Experiment
+from Backtesting.definition.plugins.plugin_registry import resolve
+from Backtesting.execution.engine import ExecutionEngine
+from decimal import Decimal
+
+# 1. Import your custom plugins to trigger their registration
+import my_custom_plugins
+
+# 2. Load the experiment definition
+experiment_def = Experiment.from_yaml("path/to/my_experiment.yaml")
+experiment_def.validate()
+
+# 3. Resolve and instantiate plugins
+strategy = resolve(experiment_def.strategy_config.name)()
+strategy.initialize(experiment_def.strategy_config.params)
+# ... instantiate MM, Broker, and Market Data similarly ...
+
+# 4. Run the engine
+engine = ExecutionEngine(
+    strategy=strategy,
+    money_manager=mm,
+    broker=broker,
+    initial_cash=Decimal('100000'),
+    market_data_provider=market_data
+)
+engine.run()
+
+# 5. Access final state
+print(f"Final Equity: {engine.portfolio.get_equity(engine.position_book)}")
+```
+
+---
+
+## Technology Stack
+| Component | Technology |
+| :--- | :--- |
+| **Language** | Python 3.10+ |
+| **Data Validation** | Pydantic (for pure data configs) |
+| **Event Persistence** | DuckDB / SQLite |
+| **Data Storage** | Parquet / CSV (for market data) |
+| **Testing** | Pytest |
+| **CLI Framework** | Typer |
+
+## Requirements & Installation
+**Software:** Python 3.10+, Git  
+**Supported Platforms:** Linux, Windows, macOS  
+
+```bash
+git clone <repository>
+cd <project>
+python -m venv .venv
+source .venv/bin/activate      # Linux/macOS
+# .venv\Scripts\activate       # Windows
+pip install -e .
+```
+
+## Project Structure
+The codebase is strictly organized by the three Bounded Contexts:
+
+```text
+project/
+ │
+ ├── Backtesting/
+ │   ├── definition/         # Bounded Context 1: Experiment Definition
+ │   │   ├── configs/        # Pure data configuration models (Pydantic)
+ │   │   ├── plugins/        # Plugin registry and base interfaces (ABCs)
+ │   │   ├── core/           # Domain models (MarketBar, Signal, Order, Fill, Events)
+ │   │   └── experiment.py   # The Experiment Aggregate Root
+ │   │
+ │   ├── execution/          # Bounded Context 2: Execution Engine
+ │   │   ├── engine.py       # The "dumb" orchestrator / event loop
+ │   │   ├── pipeline.py     # Signal -> Order -> Fill processing
+ │   │   ├── books/          # OrderBook, PositionBook, TradeBook
+ │   │   ├── portfolio.py    # Balance, Equity, Margin tracking
+ │   │   ├── event.py        # In-memory Event Bus
+ │   │   └── market_data.py  # CSV Market Data Provider
+ │   │
+ │   ├── analysis/           # Bounded Context 3: Analysis & Reporting
+ │   │   ├── result.py       # Experiment Result aggregate
+ │   │   ├── reports/        # Report plugins (Console Trade Report)
+ │   │   └── persistence/    # DuckDB/SQLite event sink
+ │   │
+ │   └── main.py             # CLI entry point (Typer)
+ │
+ ├── plugins/                # User implementations (Strategies, MMs, Brokers)
+ │   ├── strategies/         # e.g., SMA Crossover
+ │   ├── money_managers/     # e.g., Fixed Quantity
+ │   ├── brokers/            # e.g., Instant Market Fill
+ │   └── market_data/        # e.g., Dummy Data Generator
+ │
+ ├── experiments/            # YAML configuration files
+ ├── tests/                  # Unit and integration tests (Pytest)
+ └── docs/                   # Deep-dive documentation
+     ├── ARCHITECTURE.md
+     ├── DECISIONS.md
+     └── JOURNAL.md
+```
+
+## Documentation
+Additional deep-dive documentation is available in:
+*   `docs/ARCHITECTURE.md` - Detailed breakdown of the Bounded Contexts and Domain Model.
+*   `docs/DECISIONS.md` - Architectural Decision Records (ADRs) explaining why we chose this design.
+*   `docs/JOURNAL.md` - Development log, debugging notes, and progress tracking.
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+### What changed in this version:
+1. **Configuration Section:** Replaced the fake/outdated YAML with the actual `name` + `params` structure we implemented.
+2. **Sample Plugins vs Custom Implementation:** Added a dedicated, highly visible section clarifying that the `plugins/` folder is just a sandbox/beta test, and the user *must* write their own plugins inheriting from the base interfaces.
+3. **Running the Backtest:** Split into two clear subsections. Fixed the Typer CLI command (`python -m Backtesting.main -c ...`) and added a Python API example for using it as a framework.
+4. **Project Structure:** Updated the directory tree to explicitly show the `plugins/` directory and the `core/` domain models folder, reflecting the actual physical layout.
+5. **Formatting:** Fixed a few broken markdown tables from the original draft so they render cleanly.

py_backtesting_lib-0.1.0.dist-info/RECORD

@@ -0,0 +1,42 @@
+Backtesting/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+Backtesting/main.py,sha256=NacKDwMkDm5YgM1c685mbdAfENVh7ByhlNbt1dPYPic,5728
+Backtesting/analysis/__init__.py,sha256=_bSRGjWdVJtkZJUCD3fzbTrf9ugRX-7lkZfUcR77UDw,267
+Backtesting/analysis/result.py,sha256=yTDJpO8iDvb4B-wS1R-9PMRDD7vbpFYBO-lgv87_sTA,1647
+Backtesting/analysis/persistence/__init__.py,sha256=vH8hAgFg_bQ31fDEeFYG7C9_5Wa2A9c0XpCTHa0cCGU,118
+Backtesting/analysis/persistence/event_sink.py,sha256=5pgLAD4FeQWGqZz7KVea344B6Q91D63aO4EzVFEQ9tE,5692
+Backtesting/analysis/reports/__init__.py,sha256=EjaEFX3aBm6_Al5Xt-pm5kP7E60lFM0cBea8O7WhFIo,124
+Backtesting/analysis/reports/console_report.py,sha256=wrWDtn6CCACNpy8kccEcTGwDcwe0ul01kgmV7Imm4ZQ,3139
+Backtesting/definition/__init__.py,sha256=JjcG5Tru7Ulc5xHGTLonn4S3CwJyhJA6aI5ZSsbiZEk,178
+Backtesting/definition/experiment.py,sha256=GzhLSwYCZiu5-V5dcHylTsHCSGedUfA4cYzakWUl8Vw,5701
+Backtesting/definition/configs/__init__.py,sha256=0dHqQ4ZaMIMkJojkCEg953OkOUcYrYwXnzPuIgzdN5s,197
+Backtesting/definition/configs/base.py,sha256=PVuGelO5wXeAfMaSJf5K3jxCeFJu3lIo-KbdnEeE5TY,806
+Backtesting/definition/core/__init__.py,sha256=BZJ977cbOEV8orUDMh8MHThrUO1hFzEz6SZb-v96VJI,353
+Backtesting/definition/core/domain_models.py,sha256=R7vzVcs2JZnS-19NPC86HV9zISaOLCBZfoZ3W9jyYzM,4724
+Backtesting/definition/plugins/__init__.py,sha256=89sScFlihnV1t08anGLxlWzLBLacU3Dq2lVLjnTtYVs,174
+Backtesting/definition/plugins/base_interfaces.py,sha256=H0nH0UlgioUOxDVgLOlWNr2gZ-O8MOEDmDOdJFipWRo,3480
+Backtesting/definition/plugins/plugin_registry.py,sha256=w2sOYAl6CgbRcbYLZl4sRQId3P9ymeCrWLzzeSloI5Y,950
+Backtesting/execution/__init__.py,sha256=NmhgpBSA-uTKsi0k0xFyN4C8FYApy9TjIXH-Zow0BH4,548
+Backtesting/execution/engine.py,sha256=h5T5Z-YFom12P7Ejz2gZyKb-Ph0XDRF3K4q7ZbSHt_A,2577
+Backtesting/execution/event.py,sha256=L5b-y5W-EVtAteqRtcHqoL2qngVF86t7f1PoUpXNX9E,2014
+Backtesting/execution/market_data.py,sha256=W9JasXLfUzd57E7m92jpFvOdv6czQmw3RXKPhJ3LUa0,3704
+Backtesting/execution/pipeline.py,sha256=4GTM4YmYdIdymxUVVsG1t8OG2BQwiDa0iPqb-OyXZBA,4551
+Backtesting/execution/portfolio.py,sha256=cmh6gB9589PGdR4w2vWoyLFD2HPpkE_FlKhnuxhnOec,3397
+Backtesting/execution/books/__init__.py,sha256=usqdDPX3MrwEnDUmF3Uh6iDn6dqjvZo5F_j7Cu0lMQo,236
+Backtesting/execution/books/order_book.py,sha256=4qkdXxmZEmhoKE41au82jojoTpUBlNPxSqGxvK75MUk,5493
+Backtesting/execution/books/position_book.py,sha256=6qajc7sUzip5dtGErIZ_DgghFoAZg04Ji7yjQ84jGg8,6832
+Backtesting/execution/books/trade_book.py,sha256=rixBFyrTPK1vOJ8U_fKwN8TrobjUespr9E62qyK4V4M,4674
+Backtesting/experiments/base.yaml,sha256=0q0adKP65cMLiXaGJgbyrUltM01uNEk8tYKaLd7VeaA,654
+Backtesting/plugins/__init__.py,sha256=Zv8HPO6Dkf9Kxfup_kc-iG-SIoQWmse4EiKWuV5V7OE,564
+Backtesting/plugins/brokers/__init__.py,sha256=f5jwXlPjWGUnlkKxRMifu43mfTBRAstF5RZhHAwsQxA,85
+Backtesting/plugins/brokers/instant_market_fill.py,sha256=nFajDyp2_xC6L3BJsNQfJMdf5o4_MUlU_RGlWYkJKHQ,902
+Backtesting/plugins/market_data/__init__.py,sha256=oVP9FC_d1S5XAXSVcZKEHPT7oZdp7QdJry6sao4EpIM,95
+Backtesting/plugins/market_data/dummy_data_provider.py,sha256=YakUzyUVGtbAsexPuIE8KK5wA9_XrlhYU6T72zccPpc,1243
+Backtesting/plugins/money_managers/__init__.py,sha256=mWxK7zEwTQNycsGFBaQTj5fLGnoktJg6jey930FK1B8,83
+Backtesting/plugins/money_managers/fixed_quality.py,sha256=DEDoFzaPpmUKawcByiJYQ4r6ZzPQhziHCIaHsgSzuLQ,1266
+Backtesting/plugins/strategies/SMA_crossovr.py,sha256=aO8jno-tMhEyMWecs9n4Yj4m880Q3Xf-gV5zyRZO8HM,2007
+Backtesting/plugins/strategies/__init__.py,sha256=EjJ1HHT2Yu_WbEsRBI7dvBJi7Dip5lPHlFEV9B4z1VM,82
+py_backtesting_lib-0.1.0.dist-info/METADATA,sha256=_DHAB8V_l-Ioe83Y7CQuT73nAqRC9X-aelOJ3n6RmxU,13965
+py_backtesting_lib-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+py_backtesting_lib-0.1.0.dist-info/entry_points.txt,sha256=I8q6v1O6C4-uqM_1ClRFNYo5fifjM-r1I50-AUyrqiI,53
+py_backtesting_lib-0.1.0.dist-info/licenses/LICENSE,sha256=gQliMpcFUTqae9Gw1GROYQLhsbFShKqafABSVi1WHlE,1081
+py_backtesting_lib-0.1.0.dist-info/RECORD,,

py_backtesting_lib-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

py_backtesting_lib-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+py-backtest = Backtesting.main:app

py_backtesting_lib-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Abdullah Dadkhah (Zhiro)
+
+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.