Master

.cursor/rules/backtrader.mdc

@@ -3,142 +3,42 @@ description:
 globs:
 alwaysApply: true
 ---
-# 🚩 Backtrader Project-Specific Guidelines (Strictly Mandatory)
+## Backtrader addendum — extends/overrides GEN‑AI Universal rules
 
-These rules extend the universal guidelines, focusing on the unique needs, architecture, and workflow of the backtrader project. They are strictly enforced and must not be overridden except by explicit maintainer approval.
+* **A1 Copyright**
+  Add `# Copyright (c) 2025 backtrader contributors` to every file.
 
----
-
-## 1. Project Identity & Copyright
-
-**1.1. Project Scope**
-
-- backtrader is an open-source Python framework for backtesting, research, and live trading of financial strategies. It is modular, extensible, and supports multiple data sources, brokers, and custom analytics.
-
-**1.2. Copyright**
-
-- All copyright statements must use the year **2025** and the following format:
-  ```python
-  # Copyright (c) 2025 backtrader contributors
-  ```
-- Do not include author names, emails, or personal attribution in code, comments, or documentation, except where required by third-party licenses.
-
----
-
-## 2. Directory Structure & Documentation
-
-**2.1. Directory Structure**
-
-- The root `README.md` defines the canonical directory structure and project scope. Do not reorganize or add top-level directories without explicit approval.
-- Each major subdirectory (e.g., `backtrader/`, `arbitrage/`, `backtest/`, `samples/`, `tests/`) must contain a `README.md` describing its purpose, main components, usage, and any non-obvious dependencies or conventions.
-
-**2.2. Documentation Standards**
-
-- All new or modified modules, classes, and public functions must include docstrings that comply with the universal documentation requirements.
-- For complex logic (e.g., custom indicators, analyzers, or strategy orchestration), precede the code with a high-level comment explaining the rationale, algorithm, and any critical constraints.
-- All comments, docstrings, and markdown must be line-wrapped at 90 characters.
-
----
-
-## 3. Codebase Architecture & Extensibility
-
-**3.1. Modularity**
-
-- New features must be implemented as modular components (e.g., new indicators in `backtrader/indicators/`, new analyzers in `backtrader/analyzers/`, new strategies in `backtrader/strategies/`).
-- Avoid monolithic changes; prefer extension via subclassing, plugins, or new modules.
-
-**3.2. Backward Compatibility**
-
-- Do not break public APIs or remove existing features without explicit maintainer approval and a documented migration path.
-
-**3.3. Integration Points**
-
-- When integrating with external data sources, brokers, or analytics, follow the established adapter patterns in the relevant subdirectories.
-- Document any new integration points in the corresponding directory `README.md`.
-
----
-
-## 4. Testing & Quality Assurance
-
-**4.1. Test Coverage**
-
-- All new code must be accompanied by unit or integration tests under the appropriate `tests/` subdirectory.
-- Tests must be runnable via `pytest` and should not require external services unless explicitly documented as integration tests.
-
-**4.2. Sample Strategies**
-
-- If adding new sample strategies or notebooks, place them in the `samples/` directory and provide a brief description and usage instructions in a local `README.md`.
-
----
-
-## 5. Dependency Management
-
-**5.1. Version Pinning**
-
-- All Python dependencies must be explicitly version-pinned in `requirements.txt` or `pyproject.toml`.
-- Do not introduce or update dependencies without explicit approval.
-
-**5.2. Environment Isolation**
-
-- Use virtual environments for development and testing. Do not assume system-wide packages.
-
----
-
-## 6. Security & Secrets
-
-**6.1. Secrets Handling**
-
-- Never commit real credentials, API keys, or secrets. Use only template files (e.g., `.sample`) to illustrate secret structure.
-
-**6.2. Security Scanning**
-
-- Enable automated secret and vulnerability scanning in CI.
-
----
+* **A2 Docs**
+  Each top‑level dir needs a short README (purpose / usage / deps).
 
-## 7. Logging, Debugging, and Error Handling
+* **A3 Dependencies** (replaces Universal Q‑2)
+  Pin every Python version; upgrades need maintainer approval.
 
-**7.1. Logging**
+* **A4 Modularity / API**
+  New code goes in subpackages; no public‑API breaks without a migration note.
 
-- Use the standard logging facilities provided by backtrader or Python’s `logging` module.
-- Do not introduce new logging frameworks.
+* **A5 Tests**
+  Add `pytest` tests under `tests/`; keep coverage ≥ current.
 
-**7.2. Error Reporting**
+* **A6 Samples**
+  Put demos in `samples/` with a brief README.
 
-- When raising exceptions or logging errors, include sufficient context (e.g., data feed, broker, strategy name) to aid debugging.
-- For critical errors, ensure that stack traces are preserved and actionable.
+* **A7 CI security**
+  Run secret‑scan and vuln‑scan.
 
----
-
-## 8. Contribution Workflow
-
-**8.1. Pull Requests**
-
-- All changes must be submitted via pull request and reviewed by a maintainer.
-- PRs must pass all CI checks (lint, tests, coverage) before merging.
-
-**8.2. Codeowners**
-
-- Follow the `.github/CODEOWNERS` file for reviewer assignment.
-
----
+* **A8 Logging / errors**
+  Use `logging` or built‑in helpers; include feed / broker / strategy context.
 
-## 9. Project-Specific Conventions
+* **A9 Workflow**
+  All changes via PR; follow CODEOWNERS; CI (lint + tests) must pass.
 
-**9.1. Naming**
-
-- Use descriptive, consistent names for new modules, classes, and functions, following the established naming conventions in each subpackage.
-
-**9.2. Imports**
-
-- Use explicit relative imports within the `backtrader/` package to avoid ambiguity.
-
-**9.3. Platform Compatibility**
-
-- Ensure all code runs on Linux and macOS. Windows support is best-effort unless otherwise specified.
-
----
+* **A10 Naming / imports**
+  Use descriptive names; explicit relative imports inside `backtrader/`.
 
-## 10. Compatibility with Universal Guidelines
+* **A11 Platform**
+  Must run on Linux + macOS. Windows best effort.
 
-- These rules extend, but do not duplicate, the universal guidelines. In case of conflict, the stricter or lower-numbered rule prevails.
+* **A12 Baseline diff**
+  Before commit run
+  `git diff origin/main -- <path>`
+  Revert pure‑noise edits, restore lost features, note recoveries in the PR.

.github/workflows/pylint.yml

@@ -0,0 +1,23 @@
+name: Pylint
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10"]
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v3
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pylint
+    - name: Analysing the code with pylint
+      run: |
+        pylint $(git ls-files '*.py')

README.md

@@ -1,25 +1,22 @@
-# Slim Backtrader
+# backtrader
 
-This is a fork of the original [backtrader](https://github.com/mementum/backtrader) - slimmed down.
-Unnecessary features and updating the package to ensure compatibility with newer Python versions and dependencies.
+This is a fork of the original [backtrader](https://github.com/mementum/backtrader) —
+slimmed down. The project aims to remove unnecessary features and update the package
+to ensure compatibility with newer Python versions and dependencies.
 
-Aims of this project:
+## Project Aims
 
 - Slim down unnecessary features
 - Improve performance
 - Update aged implementations
-
-For now the focus is:
-
-- Code clean-up: remove unncessary imports
+- Code clean-up: remove unnecessary imports
 - Syntax update: make it more modern
-- Remove deprecated integrations (i.e. pyfolio, IbPy, comtypes)
+- Remove deprecated integrations (e.g., pyfolio, IbPy, comtypes)
 - Remove interactive plotting: the backend is heavy and slow
 - Improved support for parallel processing
 
-This is an ongoing process that has just started and will hopefully bring life to an excellent project.
-
-Feel free to contribute!
+This is an ongoing process that has just started and will hopefully bring life to an
+excellent project. Feel free to contribute!
 
 ---
 
@@ -28,76 +25,123 @@ Feel free to contribute!
 A Python-based platform for live trading and backtesting, featuring:
 
 - **Live Data Feed and Trading**:
-  - Interactive Brokers (requires `IbPy`, significantly benefits from installed `pytz`)
-  - *Visual Chart* (requires fork of `comtypes` until pull request integration, benefits from `pytz`)
-  - *Oanda* (requires `oandapy`, REST API only – v20 streaming not supported)
-
+  - Interactive Brokers (requires `IbPy`, benefits from installed `pytz`)
+  - Visual Chart (requires fork of `comtypes` until pull request integration, benefits from `pytz`)
+  - Oanda (requires `oandapy`, REST API only — v20 streaming not supported)
 - **Data Sources**:
   - CSV/files, online sources, or via *pandas* and *blaze*
-
 - **Data Management**:
   - Filters (e.g., daily bars into intraday chunks, Renko bricks)
   - Multiple data feeds and strategies supported
   - Multiple simultaneous timeframes
   - Integrated resampling and replaying capabilities
-
 - **Backtesting Modes**:
   - Step-by-step execution or all-at-once (strategy evaluation exception)
-
 - **Indicators**:
-  - Extensive built-in indicators (full list available [here](http://www.backtrader.com/docu/indautoref.html))
-  - *TA-Lib* integration (requires Python *ta-lib*)
+  - Extensive built-in indicators ([full list](http://www.backtrader.com/docu/indautoref.html))
+  - TA-Lib integration (requires Python *ta-lib*)
   - Easy creation of custom indicators
-
 - **Analyzers and Utilities**:
   - Built-in analyzers (e.g., TimeReturn, Sharpe Ratio, SQN)
   - `pyfolio` integration (**deprecated**)
-
 - **Broker Simulation**:
-  - Supports multiple order types: *Market*, *Close*, *Limit*, *Stop*, *StopLimit*, *StopTrail*, *StopTrailLimit*, *OCO*, bracket orders, slippage, volume filling strategies, continuous cash adjustments for futures-like instruments
-
+  - Supports multiple order types: Market, Close, Limit, Stop, StopLimit, StopTrail,
+    StopTrailLimit, OCO, bracket orders, slippage, volume filling strategies, continuous cash
+    adjustments for futures-like instruments
 - **Automated Staking**:
   - Sizers for position sizing
-
 - **Cheating Modes**:
   - Cheat-on-Close
   - Cheat-on-Open
-
 - **Schedulers and Calendars**
-- **Plotting** *(requires matplotlib)*
+- **Plotting** (requires matplotlib)
 
 ---
 
 ## Installation
 
-Backtrader is self-contained with minimal external dependencies (plotting requires `matplotlib`).
+Backtrader is self-contained with minimal external dependencies (plotting requires
+`matplotlib`).
 
-Currently, the installation takes place by navigating to the clone of this repository and running:
+Install by navigating to the clone of this repository and running:
 
-```shell script
-pip install -e
+```shell
+pip install -e .
 ```
 
+---
+
 ## Python Compatibility
 
 Works with:
 
 - Python version `>= 3.10`
 
+---
+
 ## Documentation
 
 - **Original backtrader repository**: <https://github.com/mementum/backtrader>
 - **Blog**: [Backtrader Blog](http://www.backtrader.com/blog)
 - **Docs**: [Full Documentation](http://www.backtrader.com/docu)
 - **Indicators Reference**: [List of Built-in Indicators (122)](http://www.backtrader.com/docu/indautoref.html)
 
+---
+
 ## Version Numbering
 
 Follows format `X.Y.Z.I` where:
 
-- `X`: Major version (stable, unless significant overhauls, e.g., numpy integration).
-- `Y`: Minor version (new features or incompatible API changes).
-- `Z`: Revision updates (documentation tweaks, minor changes, bug fixes).
-- `I`: Number of built-in indicators.
+- `X`: Major version (stable, unless significant overhauls, e.g., numpy integration)
+- `Y`: Minor version (new features or incompatible API changes)
+- `Z`: Revision updates (documentation tweaks, minor changes, bug fixes)
+- `I`: Number of built-in indicators
+
+---
+
+## Navigation
+
+- [🏠 Root Directory](./README.md)
+- [⬆️ Parent Directory (workspace)](../README.md)
+
+### Subdirectories
+
+- [Tutorials](Tutorials/README.md) — Contains tutorial code and examples
+- [arbitrage](arbitrage/README.md) — Contains arbitrage strategy implementations
+- [backtest](backtest/README.md) — Contains backtesting functionality
+- [backtrader](backtrader/README.md) — Directory containing backtrader related files
+- [contrib](contrib/README.md) — Contains contributed code
+- [datas](datas/README.md) — Contains data files
+- [logs](logs/README.md) — Contains log files
+- [outcome](outcome/README.md) — Directory containing outcome related files
+- [prompts](prompts/README.md) — Directory containing prompts related files
+- [qmtbt](qmtbt/README.md) — Directory containing qmtbt related files
+- [reference](reference/README.md) — Directory containing reference related files
+- [samples](samples/README.md) — Contains sample code and examples
+- [sandbox](sandbox/README.md) — Contains experimental or sandbox code
+- [scripts](scripts/README.md) — This directory contains files related to scripts
+- [src](src/README.md) — Contains source code
+- [strategies](strategies/README.md) — Contains trading strategy implementations
+- [tests](tests/README.md) — Contains test files and test utilities
+- [tools](tools/README.md) — Contains tools and utilities
+- [turtle](turtle/README.md) — Directory containing turtle related files
+- [xtquant](xtquant/README.md) — Directory containing xtquant related files
 
 ---
+
+## Directory Summary
+
+This directory contains 31 files and 20 subdirectories.
+
+### File Types
+
+- .py: 6 files
+- .png: 6 files
+- .ipynb: 4 files
+- .txt: 4 files
+- .md: 3 files
+- .sh: 2 files
+- .rst: 1 file
+- .code-workspace: 1 file
+- .toml: 1 file
+- .ini: 1 file