polars-bt 0.1.2__tar.gz

polars_bt-0.1.2/.cargo/config.toml

@@ -0,0 +1,5 @@
+[build]
+jobs = 128
+
+[test]
+jobs = 128

polars_bt-0.1.2/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Set up Rust
+      uses: dtolnay/rust-toolchain@nightly
+      with:
+        components: rustfmt, clippy
+
+    - name: Cache cargo
+      uses: actions/cache@v4
+      with:
+        path: |
+          ~/.cargo/registry
+          ~/.cargo/git
+          target
+        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+    - name: Cache uv
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/uv
+        key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml') }}
+
+    - name: Install uv
+      run: pip install uv
+
+    - name: Install dependencies with uv
+      run: uv pip install --system maturin polars pytest
+
+    - name: Run rustfmt
+      run: cargo +nightly fmt --all -- --check
+
+    - name: Run clippy
+      run: cargo +nightly clippy --package polars_bt_extension --all-features -- -D warnings
+
+    - name: Build wheels with maturin
+      run: maturin build --release
+
+    - name: Install wheels with uv
+      run: uv pip install --system target/wheels/*.whl --force-reinstall
+
+    - name: Run tests with uv
+      run: uv run pytest test_backtest.py -v

polars_bt-0.1.2/.gitignore

@@ -0,0 +1,78 @@
+# Rust
+/target/
+**/*.rs.bk
+*.pdb
+Cargo.lock
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.pyd
+*.dll
+*.pyc
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.pyi
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv/
+.ENV/
+env.bak/
+venv.bak/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+*.parquet
+
+# Logs
+logs/
+*.log
+
+# Maturin
+*.whl
+*.tar.gz
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+# OS
+Thumbs.db
+.DS_Store

polars_bt-0.1.2/ARCHITECTURE.md

@@ -0,0 +1,198 @@
+# Project Structure
+
+This document provides an overview of the polars_bt_extension project structure and organization.
+
+## Directory Layout
+
+```
+polars_bt_extension/
+├── .github/
+│   └── workflows/
+│       ├── ci.yml          # Continuous Integration workflow
+│       └── release.yml    # Release and PyPI publishing workflow
+├── polars_bt_extension/                # Python package
+│   ├── __init__.py       # Package initialization
+│   └── backtest.py       # Python API for backtest function
+├── src/                  # Rust source code
+│   ├── exchange/
+│   │   ├── mod.rs        # Exchange simulator and main backtest logic
+│   │   └── matcher.rs    # Order matching algorithms
+│   ├── order.rs          # Order management structures
+│   ├── position.rs       # Position tracking and P&L calculation
+│   └── lib.rs           # Library entry point
+├── .gitignore           # Git ignore patterns
+├── .cargo/              # Cargo configuration
+├── Cargo.toml           # Rust dependencies and metadata
+├── CHANGELOG.md         # Version changelog
+├── CONTRIBUTING.md       # Contribution guidelines
+├── LICENSE              # MIT License
+├── Makefile            # Development tasks
+├── pyproject.toml       # Python package configuration
+├── README.md            # Project documentation
+├── requirements.txt      # Python development dependencies
+├── rust-toolchain.toml  # Rust toolchain configuration
+├── rustfmt.toml        # Rust formatting configuration
+└── test_backtest.py     # Python tests
+```
+
+## Core Modules
+
+### `src/exchange/`
+
+**Purpose**: Low-frequency exchange simulator with order matching capabilities
+
+**Key Components**:
+- `LofiEx`: Main exchange simulator
+- `Strategy`: Trading strategy implementation
+- `backtest()`: Main Polars plugin function
+
+**Dependencies**: `order`, `position`, `matcher`
+
+### `src/order.rs`
+
+**Purpose**: Order management and direction handling
+
+**Key Components**:
+- `Order`: Order structure with price, quantity, direction, and timestamp
+- `OrderDirection`: Long/Short direction enumeration
+
+**Dependencies**: `chrono` (for timestamp formatting)
+
+### `src/position.rs`
+
+**Purpose**: Position tracking and profit/loss calculation
+
+**Key Components**:
+- `Position`: Position management with P&L tracking
+- `PositionDirection`: Long/Short/Flat position direction
+- `Summary`: Backtest result summary
+
+**Dependencies**: `order`
+
+### `src/exchange/matcher.rs`
+
+**Purpose**: Pluggable order matching algorithms
+
+**Key Components**:
+- `Matcher`: Trait for order matching algorithms
+- `DefaultMatcher`: Strict cross matching with limit restrictions
+- `EasyMatcher`: Lenient matching without limit restrictions
+- `MarketData`: Current market price information
+- `DealResp`: Order matching result
+
+**Dependencies**: `order`, `position`
+
+### `polars_bt_extension/` (Python Package)
+
+**Purpose**: Python API interface
+
+**Key Components**:
+- `backtest()`: Python wrapper for Rust backtest function
+
+**Dependencies**: `polars`, `pyo3-polars`
+
+## Build System
+
+### Rust (Cargo)
+
+- **Cargo.toml**: Defines Rust dependencies and package metadata
+- **rust-toolchain.toml**: Specifies Rust toolchain version
+- **rustfmt.toml**: Rust code formatting rules
+
+### Python (Maturin)
+
+- **pyproject.toml**: Python package configuration
+- **requirements.txt**: Development dependencies
+
+### CI/CD
+
+- **.github/workflows/ci.yml**: Runs tests on push/PR
+- **.github/workflows/release.yml**: Builds and publishes on tag
+
+## Development Workflow
+
+1. **Code Changes**: Modify Rust or Python code
+2. **Testing**: Run `cargo test` and `python test_backtest.py`
+3. **Quality Checks**: Run `cargo clippy` and `cargo fmt`
+4. **Build**: Run `maturin develop` or `maturin develop --release`
+5. **Commit**: Follow conventional commit format
+6. **Push**: CI will automatically run tests
+
+## Key Design Decisions
+
+### Flat Directory Structure
+
+- Removed `bt_lite/` intermediate directory for simpler structure
+- Direct module organization under `src/`
+- Easier navigation and maintenance
+
+### Separation of Concerns
+
+- **Exchange**: Order matching and execution
+- **Order**: Order data structures
+- **Position**: Position tracking and P&L
+- **Matcher**: Pluggable matching algorithms
+
+### Performance Optimization
+
+- Zero-copy data transfer with Polars
+- Native Rust implementation
+- Efficient memory management with PolarsAllocator
+- Array literals instead of `vec!` where possible
+
+### Code Quality
+
+- All public APIs documented with English comments
+- Clippy strict mode (`-D warnings`)
+- Rustfmt for consistent formatting
+- Comprehensive test coverage
+
+## Dependencies
+
+### Rust
+
+- `polars`: DataFrame library
+- `pyo3`: Python bindings
+- `pyo3-polars`: Polars integration
+- `serde`: Serialization
+- `chrono`: Date/time handling
+
+### Python
+
+- `polars`: DataFrame library
+- `pytest`: Testing framework
+- `maturin`: Build tool
+
+## Testing
+
+### Unit Tests
+
+- Rust tests in `src/` modules
+- Python tests in `test_backtest.py`
+
+### Integration Tests
+
+- CI runs tests on multiple Python versions (3.9-3.12)
+- CI runs tests on multiple OS (Linux, macOS, Windows)
+
+### Quality Checks
+
+- `cargo clippy`: Linting
+- `cargo fmt`: Formatting
+- `cargo doc`: Documentation
+
+## Release Process
+
+1. Update version in `Cargo.toml`
+2. Update `CHANGELOG.md`
+3. Create git tag: `git tag -a v1.0.0 -m "Release v1.0.0"`
+4. Push tag: `git push origin v1.0.0`
+5. GitHub Actions builds wheels and publishes to PyPI
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.

polars_bt-0.1.2/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial release of polars_bt_extension backtesting engine plugin
+- High-performance order matching with DefaultMatcher and EasyMatcher
+- Comprehensive position management with P&L tracking
+- Support for trading limits (limit up/down)
+- Python API integration with Polars
+- Complete documentation and examples
+
+### Changed
+- Refactored project structure for better maintainability
+- Optimized code for performance with zero-copy data transfer
+- Improved code quality with clippy and rustfmt
+
+### Fixed
+- All clippy warnings resolved
+- Documentation formatting issues fixed
+
+## [0.1.2] - 2025-03-04
+
+### Added
+- Initial version
+- Core backtesting functionality
+- Order matching algorithms
+- Position management
+- Python API
+
+[Unreleased]: https://github.com/yourusername/polars_bt_extension/compare/v0.1.2...HEAD
+[0.1.2]: https://github.com/yourusername/polars_bt_extension/releases/tag/v0.1.2

polars_bt-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,185 @@
+# Contributing to polars_bt_extension
+
+Thank you for your interest in contributing to polars_bt_extension! This document provides guidelines and instructions for contributing to the project.
+
+## Code of Conduct
+
+Be respectful, inclusive, and constructive in all interactions. We aim to maintain a welcoming environment for all contributors.
+
+## Getting Started
+
+### Prerequisites
+
+- Rust 1.70 or later
+- Python 3.9 or later
+- maturin
+- Git
+
+### Setting Up Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/polars_bt_extension.git
+cd polars_bt_extension
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install development dependencies
+pip install maturin polars pytest
+
+# Install the package in development mode
+maturin develop
+```
+
+## Development Workflow
+
+### 1. Create a Branch
+
+```bash
+git checkout -b feature/your-feature-name
+# or
+git checkout -b fix/your-bug-fix
+```
+
+### 2. Make Changes
+
+- Write clean, readable code
+- Follow existing code style and conventions
+- Add tests for new functionality
+- Update documentation as needed
+
+### 3. Code Quality Checks
+
+Before submitting, ensure your code passes all quality checks:
+
+```bash
+# Format code
+cargo fmt
+
+# Run clippy (linting)
+cargo clippy --all-targets --all-features -- -D warnings
+
+# Run tests
+cargo test
+python test_backtest.py
+
+# Check documentation
+cargo doc --no-deps --all-features
+```
+
+### 4. Commit Changes
+
+```bash
+git add .
+git commit -m "Add your commit message here"
+```
+
+**Commit Message Guidelines:**
+
+- Use the present tense ("Add feature" not "Added feature")
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
+- Limit the first line to 72 characters or less
+- Reference issues and pull requests liberally
+
+Examples:
+- `Add support for custom matchers`
+- `Fix memory leak in position tracking`
+- `Update documentation for API changes`
+
+### 5. Push and Create Pull Request
+
+```bash
+git push origin feature/your-feature-name
+```
+
+Then create a Pull Request on GitHub with:
+- Clear title and description
+- Reference any related issues
+- Explain the changes and their purpose
+- Include screenshots if applicable
+
+## Coding Standards
+
+### Rust Code
+
+- Follow [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/)
+- Use meaningful variable and function names
+- Add doc comments for all public APIs
+- Prefer `unwrap_or_default()` over manual `match` for Option handling
+- Use array literals instead of `vec!` when possible
+
+### Python Code
+
+- Follow [PEP 8](https://pep8.org/)
+- Use type hints where appropriate
+- Add docstrings for all public functions
+- Keep functions focused and small
+
+### Documentation
+
+- All public APIs must have documentation
+- Use clear, concise language
+- Include examples for complex functionality
+- Keep documentation up to date with code changes
+
+## Testing
+
+### Writing Tests
+
+- Write tests for all new functionality
+- Test both success and failure cases
+- Use descriptive test names
+- Keep tests independent and fast
+
+### Running Tests
+
+```bash
+# Rust tests
+cargo test
+
+# Python tests
+pytest test_backtest.py -v
+
+# Run specific test
+cargo test test_name
+pytest test_backtest.py::test_function -v
+```
+
+## Project Structure
+
+```
+polars_bt_extension/
+├── src/
+│   ├── exchange/       # Exchange simulator and matching logic
+│   ├── order.rs        # Order management
+│   ├── position.rs     # Position tracking
+│   └── lib.rs         # Library entry point
+├── polars_bt_extension/             # Python package
+│   ├── __init__.py
+│   └── backtest.py    # Python API
+├── tests/             # Test files
+├── .github/           # GitHub workflows
+├── Cargo.toml         # Rust dependencies
+├── pyproject.toml     # Python configuration
+└── README.md          # Project documentation
+```
+
+## Release Process
+
+Releases are handled by maintainers through GitHub Actions:
+
+1. Update version in `Cargo.toml`
+2. Create a git tag: `git tag -a v1.0.0 -m "Release version 1.0.0"`
+3. Push the tag: `git push origin v1.0.0`
+4. GitHub Actions will automatically build and publish to PyPI
+
+## Questions?
+
+Feel free to:
+- Open an issue for bugs or feature requests
+- Start a discussion for questions or ideas
+- Contact maintainers directly for urgent matters
+
+Thank you for contributing to polars_bt_extension! 🚀