rangebar 11.6.1__cp313-cp313-macosx_11_0_arm64.whl

rangebar-11.6.1.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: rangebar
+Version: 11.6.1
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: polars>=1.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: clickhouse-connect>=0.8
+Requires-Dist: arro3-core>=0.6.5
+Requires-Dist: click>=8.0
+Requires-Dist: requests>=2.28
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: backtesting>=0.3 ; extra == 'backtesting'
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0 ; extra == 'dev'
+Requires-Dist: black>=23.0 ; extra == 'dev'
+Requires-Dist: ruff>=0.1 ; extra == 'dev'
+Provides-Extra: backtesting
+Provides-Extra: dev
+Provides-Extra: exness
+License-File: LICENSE
+Summary: Python bindings for rangebar: Non-lookahead range bar construction for cryptocurrency trading
+Keywords: trading,cryptocurrency,range-bars,backtesting,technical-analysis
+Author: Terry Li
+License: MIT
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Documentation, https://github.com/terrylica/rangebar-py#readme
+Project-URL: Repository, https://github.com/terrylica/rangebar-py
+Project-URL: Upstream (Rust), https://github.com/terrylica/rangebar
+
+# rangebar-py
+
+Python bindings for the [rangebar](https://github.com/terrylica/rangebar-py/tree/main/crates) Rust crates via PyO3/maturin.
+
+[![PyPI](https://img.shields.io/pypi/v/rangebar.svg)](https://pypi.org/project/rangebar/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/terrylica/rangebar-py/blob/main/LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/rangebar.svg)](https://pypi.org/project/rangebar/)
+
+## Links
+
+| Resource              | URL                                                         |
+| --------------------- | ----------------------------------------------------------- |
+| PyPI                  | <https://pypi.org/project/rangebar/>                        |
+| Repository            | <https://github.com/terrylica/rangebar-py>                  |
+| Performance Dashboard | <https://terrylica.github.io/rangebar-py/>                  |
+| Rust Crates           | <https://github.com/terrylica/rangebar-py/tree/main/crates> |
+| Issues                | <https://github.com/terrylica/rangebar-py/issues>           |
+
+## Installation
+
+```bash
+pip install rangebar
+```
+
+Pre-built wheels: Linux (x86_64), macOS (ARM64), Python 3.13
+
+Source build requires Rust toolchain and maturin.
+
+## Overview
+
+Converts trade tick data into range bars for backtesting. Range bars close when price moves a fixed percentage from the opening price, adapting to market volatility rather than fixed time intervals.
+
+**Output format**: pandas DataFrame with DatetimeIndex and OHLCV columns, compatible with [backtesting.py](https://github.com/kernc/backtesting.py).
+
+## Quick Start
+
+```python
+from rangebar import get_range_bars
+
+# Fetch data and generate range bars in one call
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-06-30")
+
+# Use with backtesting.py
+from backtesting import Backtest, Strategy
+bt = Backtest(df, MyStrategy, cash=10000, commission=0.0002)
+stats = bt.run()
+```
+
+## API Reference
+
+### get_range_bars (Date-Bounded)
+
+The entry point for date-bounded range bar generation with automatic data fetching and caching.
+
+```python
+from rangebar import get_range_bars
+
+# Basic usage - Binance spot
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-06-30")
+
+# Using threshold presets
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-03-31", threshold_decimal_bps="tight")
+
+# Binance USD-M Futures
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-03-31", market="futures-um")
+
+# With microstructure data (vwap, buy_volume, sell_volume)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", include_microstructure=True)
+```
+
+**Parameters**:
+
+- `symbol`: Trading symbol (e.g., "BTCUSDT", "ETHUSDT")
+- `start_date`: Start date in YYYY-MM-DD format
+- `end_date`: End date in YYYY-MM-DD format
+- `threshold_decimal_bps`: Threshold in decimal basis points or preset name (default: 250 = 25bps = 0.25%)
+- `source`: Data source - "binance" or "exness" (default: "binance")
+- `market`: Market type - "spot", "futures-um"/"um", "futures-cm"/"cm" (default: "spot")
+- `include_microstructure`: Include vwap, buy_volume, sell_volume columns (default: False)
+- `use_cache`: Cache tick data locally (default: True)
+
+**Returns**: pandas DataFrame with DatetimeIndex and columns `Open`, `High`, `Low`, `Close`, `Volume`
+
+### get_n_range_bars (Count-Bounded)
+
+Get exactly N range bars - useful for ML training, walk-forward optimization, and consistent backtest comparisons.
+
+```python
+from rangebar import get_n_range_bars
+
+# Get last 10,000 bars for ML training
+df = get_n_range_bars("BTCUSDT", n_bars=10000)
+assert len(df) == 10000
+
+# Get 5,000 bars ending at specific date
+df = get_n_range_bars("BTCUSDT", n_bars=5000, end_date="2024-06-01")
+
+# With safety limit (won't fetch more than 30 days of data)
+df = get_n_range_bars("BTCUSDT", n_bars=1000, max_lookback_days=30)
+```
+
+**Parameters**:
+
+- `symbol`: Trading symbol (e.g., "BTCUSDT")
+- `n_bars`: Number of bars to retrieve (must be > 0)
+- `threshold_decimal_bps`: Threshold in decimal basis points or preset name (default: 250)
+- `end_date`: End date (YYYY-MM-DD) or None for most recent data
+- `source`: Data source - "binance" or "exness" (default: "binance")
+- `market`: Market type (default: "spot")
+- `use_cache`: Use ClickHouse cache (default: True)
+- `fetch_if_missing`: Fetch data if cache doesn't have enough bars (default: True)
+- `max_lookback_days`: Safety limit for data fetching (default: 90)
+- `warn_if_fewer`: Emit warning if returning fewer bars than requested (default: True)
+
+**Returns**: pandas DataFrame with exactly `n_bars` rows (or fewer if insufficient data), sorted chronologically
+
+**Cache behavior**:
+
+- **Fast path**: If ClickHouse cache has >= n_bars, returns immediately (~50ms)
+- **Slow path**: Fetches additional data, computes bars, stores in cache
+
+### Threshold Presets
+
+Use string presets for common threshold values:
+
+| Preset       | Value | Percentage    | Use Case         |
+| ------------ | ----- | ------------- | ---------------- |
+| `"micro"`    | 10    | 0.01% (1bps)  | Scalping         |
+| `"tight"`    | 50    | 0.05% (5bps)  | Day trading      |
+| `"standard"` | 100   | 0.1% (10bps)  | Swing trading    |
+| `"medium"`   | 250   | 0.25% (25bps) | Default          |
+| `"wide"`     | 500   | 0.5% (50bps)  | Position trading |
+| `"macro"`    | 1000  | 1% (100bps)   | Long-term        |
+
+```python
+from rangebar import get_range_bars, THRESHOLD_PRESETS
+
+# Using preset string
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps="tight")
+
+# Or numeric value
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps=50)
+
+# View all presets
+print(THRESHOLD_PRESETS)
+# {'micro': 10, 'tight': 50, 'standard': 100, 'medium': 250, 'wide': 500, 'macro': 1000}
+```
+
+### Configuration Constants
+
+```python
+from rangebar import TIER1_SYMBOLS, THRESHOLD_PRESETS, THRESHOLD_DECIMAL_MIN, THRESHOLD_DECIMAL_MAX
+
+# 18 high-liquidity symbols available on all Binance markets
+print(TIER1_SYMBOLS)
+# ('AAVE', 'ADA', 'AVAX', 'BCH', 'BNB', 'BTC', 'DOGE', 'ETH', 'FIL',
+#  'LINK', 'LTC', 'NEAR', 'SOL', 'SUI', 'UNI', 'WIF', 'WLD', 'XRP')
+
+# Valid threshold range
+print(f"Min: {THRESHOLD_DECIMAL_MIN}, Max: {THRESHOLD_DECIMAL_MAX}")
+# Min: 1, Max: 100000
+```
+
+### Advanced APIs
+
+For users with existing tick data (not fetching from Binance):
+
+#### process_trades_to_dataframe
+
+```python
+import pandas as pd
+from rangebar import process_trades_to_dataframe
+
+# Load your own trade data
+trades = pd.read_csv("BTCUSDT-aggTrades.csv")
+
+# Convert to range bars
+df = process_trades_to_dataframe(trades, threshold_decimal_bps=250)
+```
+
+#### process_trades_polars (Recommended for Polars Users)
+
+**2-3x faster** than `process_trades_to_dataframe()` with lazy evaluation and predicate pushdown:
+
+```python
+import polars as pl
+from rangebar import process_trades_polars
+
+# LazyFrame - predicates pushed to I/O layer (10-100x memory reduction)
+lazy_df = pl.scan_parquet("trades/*.parquet").filter(pl.col("timestamp") >= start_ts)
+bars = process_trades_polars(lazy_df, threshold_decimal_bps=250)
+
+# Or with eager DataFrame
+df = pl.read_parquet("trades.parquet")
+bars = process_trades_polars(df)
+```
+
+**Performance benefits**:
+
+- Predicate pushdown: filters applied at Parquet read, not after
+- Minimal conversion: only required columns extracted
+- Chunked processing: 100K records per batch
+- Memory efficient: avoids materializing full dataset
+
+#### process_trades_chunked
+
+Memory-safe processing for large datasets:
+
+```python
+from rangebar import process_trades_chunked
+
+# Process 10M+ trades without OOM
+for bars_df in process_trades_chunked(iter(trades), chunk_size=50_000):
+    process_batch(bars_df)
+```
+
+## Requirements
+
+**Runtime**: Python >= 3.13, pandas >= 2.0, numpy >= 1.24, polars >= 1.0
+
+**Optional**: backtesting >= 0.3 (for backtesting integration)
+
+**Build**: Rust toolchain, maturin >= 1.7
+
+## Architecture
+
+```
+rangebar (Rust crate)
+    ↓ Cargo dependency
+rangebar-py (this package)
+    ├── src/lib.rs (PyO3 bindings)
+    └── python/rangebar/ (Python API)
+    ↓ pip install
+Python applications
+```
+
+## Development
+
+```bash
+git clone https://github.com/terrylica/rangebar-py.git
+cd rangebar-py
+pip install maturin
+maturin develop --features data-providers
+pytest tests/
+```
+
+## Documentation
+
+| Document                                                                                                | Description           |
+| ------------------------------------------------------------------------------------------------------- | --------------------- |
+| [Examples](https://github.com/terrylica/rangebar-py/tree/main/examples)                                 | Usage examples        |
+| [CLAUDE.md](https://github.com/terrylica/rangebar-py/blob/main/CLAUDE.md)                               | Project context       |
+| [Architecture](https://github.com/terrylica/rangebar-py/blob/main/docs/ARCHITECTURE.md)                 | System design         |
+| [Performance Guide](https://github.com/terrylica/rangebar-py/blob/main/docs/development/PERFORMANCE.md) | Benchmark methodology |
+
+## License
+
+MIT License. See [LICENSE](https://github.com/terrylica/rangebar-py/blob/main/LICENSE).
+
+## Citation
+
+```bibtex
+@software{rangebar-py,
+  title = {rangebar-py: Python bindings for range bar construction},
+  author = {Terry Li},
+  url = {https://github.com/terrylica/rangebar-py}
+}
+```
+

rangebar-11.6.1.dist-info/RECORD

@@ -0,0 +1,54 @@
+rangebar/CLAUDE.md,sha256=a93bvlk4hGcPydRDBbfzMUro5hX01j4jQV8WmDWy6DQ,9680
+rangebar/__init__.py,sha256=tYLjvpehB-BcnOcLSGqtppqMuzposfZegp_KVR8_ZR0,7407
+rangebar/__init__.pyi,sha256=cbSe-uoWZFviCu1owiZUCH0G5picol3bcNFo4FeRZI8,39531
+rangebar/_core.cpython-313-darwin.so,sha256=n0F_Vx7jvRW9K6i9DXrq6nV3cqOu51Lxom0aMNb8U9k,7440176
+rangebar/checkpoint.py,sha256=dbtjV6R09q2vXovwHKXYZLUueTXBbV1Jg0RXaA19wy0,13055
+rangebar/cli.py,sha256=kJdZvPIOTudQCrlyP6GBJqJNXyW_jPkuau5HUx463sc,8948
+rangebar/clickhouse/CLAUDE.md,sha256=b8YtpHrAZBhYEC5EYJNEIcks2_M-VNttfOd-_T0l4ek,4390
+rangebar/clickhouse/__init__.py,sha256=6enwJRjxxRBTg_GigRd7xTaRAuKQaM-Y7NZL-iDB4Q0,3021
+rangebar/clickhouse/bulk_operations.py,sha256=IDgJiG49axaDgiMIMs8Te8YeMpFXxjygfb0UFjBSK4A,10725
+rangebar/clickhouse/cache.py,sha256=mnwboxwyhX_yrTzOCvRAsWMX_ZUnezzK-x8A1T7ca4A,23381
+rangebar/clickhouse/client.py,sha256=Aij6k2-odeoLe75KpP11rk5AwhWsybsqZ1cLEtA_QAM,2841
+rangebar/clickhouse/config.py,sha256=RzWruoY6lRMxgnisE8iI30RPwaJkXm5gxiG6ZdJfMlo,4050
+rangebar/clickhouse/mixin.py,sha256=7py8EMt4tx5gwIcKnpTaFCRa0fVMs1SzZGJ108ZuG9U,3473
+rangebar/clickhouse/preflight.py,sha256=1BcHN-xDy0XPFlT0022-zAoV2i6uBVJObvPaIokq0GQ,17070
+rangebar/clickhouse/query_operations.py,sha256=qnOR-YYUQdGuX_liIigE6VPesAHd0lAhPw4_ZJeC5RM,12000
+rangebar/clickhouse/schema.sql,sha256=Pq8BDvytm5XhQDq-W1hMEzWoDbG3n7mELFIw0n5J0bA,8549
+rangebar/clickhouse/tunnel.py,sha256=sb4mNh5sLk7P36HO1lzx1E9u42a_fakwa1OSnqcFLy8,6609
+rangebar/constants.py,sha256=bFmaX6o5NdiCUE3ouzo3Kf_1wXGKuKrhMPFL0uc7kw8,9674
+rangebar/conversion.py,sha256=3XPZuHLheZ-9XgVc0a8Kj4ElDcutQVmJ1ESvYvA_Jw8,5065
+rangebar/exceptions.py,sha256=07WO9ZYNJsowkEe6sqVrPpaGqr0dpJkmoyUq7N82vGE,5819
+rangebar/exness.py,sha256=IluUL_PZkOXIBg4jsBl2t5Nii8rrG6KXpchgwCYrJBM,12370
+rangebar/hooks.py,sha256=Zc8hv9jGMbvYqcrWy_uuTh3B-2YDdH7jF2DV8aXwk_4,8555
+rangebar/logging.py,sha256=HOkFj7JmsXW-AJJnxuSR75xpMRiWecffgRLgoysY9ZE,4516
+rangebar/notify/__init__.py,sha256=J6HMJQ4ejryHntnJH6QsiuQ4E7AAzooD3NRDa6DtKR8,380
+rangebar/notify/pushover.py,sha256=ZOZCYlsPPf8EfMp4ZomAl44svVxfCb94hxteUHiFLng,4715
+rangebar/notify/telegram.py,sha256=-LeaZ7lsBdSAuFKXKUU7u4pq-cOfOxhWzi813lXemIM,7641
+rangebar/orchestration/__init__.py,sha256=fk3-pYAUADGpBxk6S7gmsu9ccLFwYEUqaEPWK4GBifE,645
+rangebar/orchestration/count_bounded.py,sha256=VXZc-Gm3YDwAltz6YBXQnQ4jYPThAx6uwgk4qXcc5jE,29224
+rangebar/orchestration/helpers.py,sha256=b7S_t1e4Rvv84UBrF78dmYMGgpoYPMRsV2iJESdwZzg,13544
+rangebar/orchestration/models.py,sha256=_gw5RH0iojCymanDgGvwPG1nJHy05cS5SEYf91mKElw,2059
+rangebar/orchestration/precompute.py,sha256=LT1_LDuoUkyrhYcaCnicDdyxmBLFeB6PMASVFuNxcZI,20210
+rangebar/orchestration/range_bars.py,sha256=w3SnkfUQwsk2fJQYJIdXvU0cwEROuuLCrfRMW9kR_5Q,30016
+rangebar/orchestration/tick_fetcher.py,sha256=iMYtwT9EWmiylBTK1Q4UOF2DAakw186p0tGribDtzqA,7463
+rangebar/ouroboros.py,sha256=hfCxtaoEPNip25NsPEpWWNf6vy08KoW-G4PVup-jrX8,14231
+rangebar/processors/__init__.py,sha256=IpPdEIpLzA-dIytR1rGv4img8GxQa65RnEv2g0R6VRk,635
+rangebar/processors/api.py,sha256=2i0txl5-VVk76i4CuErOPIaW3TKExpvF1W3FaWX3rjk,12540
+rangebar/processors/core.py,sha256=svA2tZTVj0tapesmCDVsDBdsV-_6r4NDmpM5gE3YExg,18782
+rangebar/resource_guard.py,sha256=FZS91LBYEvijldpOnAzuwOLWFLa2M8ZqEJOYRXPlkgc,18768
+rangebar/storage/__init__.py,sha256=HLfTiyih939NN3GtoVon8wUNAN32VyqhAi18r6pAkvw,719
+rangebar/storage/checksum_registry.py,sha256=V9Zc8Iy8K5K5ceg5C93USEIbla5ta2JToJWNz_vfRRY,6965
+rangebar/storage/parquet.py,sha256=RjYC8w57zlmOJbo6kvhgHtF3MQ6LHrudfTOZIUwOy_I,23346
+rangebar/streaming.py,sha256=k_5_AABRPymAVWx8Pa1O55RycfCUaLKsD-mwqE2l850,9726
+rangebar/validation/__init__.py,sha256=HFzJJPgOFwA213KkKhRJuOGyNWJvoBIo7cgeYpmJ8XY,1939
+rangebar/validation/cache_staleness.py,sha256=Dj2tftNzqU4Jb6jR1aCC85mvrHvJBzkztg4vWW5uVYI,8869
+rangebar/validation/continuity.py,sha256=e3M5-0fRECi-EdjEwhZQ1rEg9vbOg0D3GP5BA9lkV6g,21332
+rangebar/validation/gap_classification.py,sha256=9WLKwsQUi8JJT1nAjkphwWLn13MCQRsHiD4TstgbOZE,9894
+rangebar/validation/post_storage.py,sha256=kWgraWeKhDwAFlWxlzEGb0de3RzKk7-nlrJ7t5FyKSo,9696
+rangebar/validation/tier1.py,sha256=3KkXiIQjz7U6HJmgFiuwPSOdIF6JoJTWlj6AuTIoZ70,5591
+rangebar/validation/tier2.py,sha256=PUtT9q8Pe_VbBm25EdHDR6bxFJkq7tUQQJE7iXfUy4A,8970
+rangebar-11.6.1.dist-info/METADATA,sha256=HvZJI_UVNsq5EjM8Axu42H_Hd_MAgrP_gPhXTxQRHpE,10955
+rangebar-11.6.1.dist-info/WHEEL,sha256=V0PyzvBcSARU334gfbMpVsvFu6xR7hFdhQVohqdzf7E,105
+rangebar-11.6.1.dist-info/entry_points.txt,sha256=NRIcb9BtRf3_wr5MBmOJSykOGa6BDcnapRmEQ3QPQyI,45
+rangebar-11.6.1.dist-info/licenses/LICENSE,sha256=QStVwwVTxSvPQ6LIaG7LwxymOexwcbrbgxIJQasda-4,1081
+rangebar-11.6.1.dist-info/RECORD,,

rangebar-11.6.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp313-cp313-macosx_11_0_arm64

rangebar-11.6.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rangebar=rangebar.cli:main

rangebar-11.6.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rangebar-py contributors
+
+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.