backtestingfx 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. backtestingfx-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md +39 -0
  2. backtestingfx-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md +31 -0
  3. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/.github/workflows/ci.yml +1 -1
  4. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/.github/workflows/release.yml +11 -0
  5. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/.gitignore +1 -0
  6. backtestingfx-0.3.0/CHANGELOG.md +182 -0
  7. backtestingfx-0.3.0/COMPATIBILITY.md +79 -0
  8. backtestingfx-0.3.0/CONTRIBUTING.md +97 -0
  9. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/Cargo.lock +70 -36
  10. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/Cargo.toml +2 -1
  11. backtestingfx-0.3.0/MARGINS.md +253 -0
  12. backtestingfx-0.3.0/MARKET_DATA.md +215 -0
  13. backtestingfx-0.3.0/PKG-INFO +541 -0
  14. backtestingfx-0.3.0/README.md +524 -0
  15. backtestingfx-0.3.0/REFERENCE_INPUT.md +146 -0
  16. backtestingfx-0.3.0/ROADMAP.md +63 -0
  17. backtestingfx-0.3.0/SWAPS.md +172 -0
  18. backtestingfx-0.3.0/backtestingfx/__init__.py +3 -0
  19. backtestingfx-0.3.0/backtestingfx/_input.py +157 -0
  20. backtestingfx-0.3.0/backtestingfx/_timestamps.py +43 -0
  21. backtestingfx-0.3.0/backtestingfx/backtest.py +519 -0
  22. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/backtestingfx/plotting.py +134 -27
  23. backtestingfx-0.3.0/examples/benchmark.md +147 -0
  24. backtestingfx-0.3.0/examples/benchmark.py +81 -0
  25. backtestingfx-0.3.0/examples/benchmark_callbacks.md +176 -0
  26. backtestingfx-0.3.0/examples/benchmark_callbacks.py +264 -0
  27. backtestingfx-0.3.0/examples/benchmark_ingestion.md +158 -0
  28. backtestingfx-0.3.0/examples/benchmark_ingestion.py +175 -0
  29. backtestingfx-0.3.0/examples/benchmark_ingestion_results.json +723 -0
  30. backtestingfx-0.3.0/examples/benchmark_sl_tp.md +29 -0
  31. backtestingfx-0.3.0/examples/benchmark_sl_tp.rs +37 -0
  32. backtestingfx-0.3.0/examples/compare_bt.py +171 -0
  33. backtestingfx-0.3.0/examples/margin.py +27 -0
  34. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/examples/simple_strategy.rs +6 -4
  35. backtestingfx-0.3.0/examples/swaps.py +30 -0
  36. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/pyproject.toml +2 -1
  37. backtestingfx-0.3.0/src/broker.rs +1543 -0
  38. backtestingfx-0.3.0/src/data.rs +596 -0
  39. backtestingfx-0.3.0/src/engine.rs +711 -0
  40. backtestingfx-0.3.0/src/execution.rs +54 -0
  41. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/src/lib.rs +12 -0
  42. backtestingfx-0.3.0/src/margin.rs +243 -0
  43. backtestingfx-0.3.0/src/optimise.rs +301 -0
  44. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/src/stats.rs +57 -4
  45. backtestingfx-0.3.0/src/strategy.rs +17 -0
  46. backtestingfx-0.3.0/src/swap.rs +544 -0
  47. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/src/types.rs +39 -2
  48. backtestingfx-0.3.0/src/validation.rs +59 -0
  49. backtestingfx-0.3.0/tests/data/timestamps.csv +7 -0
  50. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/tests/test_backtest.py +57 -0
  51. backtestingfx-0.3.0/tests/test_bulk_ingestion.py +296 -0
  52. backtestingfx-0.3.0/tests/test_callback_contract.py +161 -0
  53. backtestingfx-0.3.0/tests/test_column_conversion.py +63 -0
  54. backtestingfx-0.3.0/tests/test_execution_timing.py +155 -0
  55. backtestingfx-0.3.0/tests/test_intrabar_execution.py +109 -0
  56. backtestingfx-0.3.0/tests/test_margin.py +234 -0
  57. backtestingfx-0.3.0/tests/test_market_data_validation.py +131 -0
  58. backtestingfx-0.3.0/tests/test_native_engine_reuse.py +34 -0
  59. backtestingfx-0.3.0/tests/test_numeric_validation.py +150 -0
  60. backtestingfx-0.3.0/tests/test_reference_comparison.py +69 -0
  61. backtestingfx-0.3.0/tests/test_reference_input.py +338 -0
  62. backtestingfx-0.3.0/tests/test_strategy_data.py +125 -0
  63. backtestingfx-0.3.0/tests/test_swaps.py +294 -0
  64. backtestingfx-0.3.0/tests/test_timestamps.py +123 -0
  65. backtestingfx-0.2.0/CHANGELOG.md +0 -64
  66. backtestingfx-0.2.0/PKG-INFO +0 -265
  67. backtestingfx-0.2.0/README.md +0 -250
  68. backtestingfx-0.2.0/backtestingfx/__init__.py +0 -2
  69. backtestingfx-0.2.0/backtestingfx/backtest.py +0 -240
  70. backtestingfx-0.2.0/examples/benchmark.py +0 -146
  71. backtestingfx-0.2.0/examples/compare_bt.py +0 -90
  72. backtestingfx-0.2.0/src/broker.rs +0 -454
  73. backtestingfx-0.2.0/src/data.rs +0 -28
  74. backtestingfx-0.2.0/src/engine.rs +0 -163
  75. backtestingfx-0.2.0/src/optimise.rs +0 -166
  76. backtestingfx-0.2.0/src/strategy.rs +0 -7
  77. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/LICENSE +0 -0
  78. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/data/EURUSD_1H.csv +0 -0
  79. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/examples/html_report.py +0 -0
  80. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/examples/optimize.py +0 -0
  81. {backtestingfx-0.2.0 → backtestingfx-0.3.0}/examples/sma_cross.py +0 -0
@@ -0,0 +1,39 @@
1
+ ---
2
+ name: Bug report
3
+ about: Report a reproducible FX simulation, installation, or reporting bug
4
+ title: ""
5
+ labels: ""
6
+ assignees: ""
7
+ ---
8
+
9
+ ## Problem
10
+ Describe the bug and the expected versus actual behavior. Include exact errors
11
+ or a traceback and hand-calculated expected results when relevant.
12
+
13
+ ## Environment
14
+ - backtestingfx version (or commit):
15
+ - Python version and interpreter:
16
+ - OS and architecture:
17
+ - pandas / numpy versions:
18
+ - Plotly version (if reporting):
19
+ - Installation method (wheel, source, development); Rust version if source-built:
20
+
21
+ ## Data and simulation settings
22
+ - Instrument, account currency, and quote-to-account conversion:
23
+ - Row count, column names/dtypes, and index type:
24
+ - Timeframe, timestamp format/unit, and timezone:
25
+ - OHLC price convention (midpoint, bid, or ask):
26
+ - Cash, lot sizes, contract size, spread, commission, and SL/TP settings:
27
+
28
+ ## Minimal reproduction
29
+ Provide a runnable code block that constructs a small synthetic DataFrame,
30
+ defines the strategy or signal function, and runs the failing call. Include
31
+ sample rows and output; avoid private data and external file dependencies.
32
+
33
+ ```python
34
+ # Imports, synthetic input, strategy/signals, settings, and failing call
35
+ ```
36
+
37
+ ## Additional context
38
+ Does this happen on the latest release or main? If it is a regression, include
39
+ the last working version and relevant logs.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: Feature request
3
+ about: Propose an FX research capability or API improvement
4
+ title: ""
5
+ labels: ""
6
+ assignees: ""
7
+ ---
8
+
9
+ ## FX use case and problem
10
+ Describe the research workflow and what currently prevents it.
11
+
12
+ ## Proposed behavior
13
+ Give an API/code example and explain expected execution or result semantics.
14
+
15
+ ## Environment and representative data
16
+ - backtestingfx and Python versions; OS/architecture:
17
+ - Instrument, timeframe, row count, column/index types, and timestamp timezone/unit:
18
+ - Relevant sizing, costs, conversion, or order assumptions:
19
+
20
+ ## Current workaround
21
+ Include a small example of the current workflow if possible, and alternatives
22
+ you considered.
23
+
24
+ ## Acceptance criteria
25
+ List observable outcomes and edge cases that would make the feature complete.
26
+ Explain how the behavior could be tested with synthetic data.
27
+
28
+ ## Compatibility and scope
29
+ Could existing strategies or results change? Note any related
30
+ [roadmap](https://github.com/KhizarImran/backtestingfx/blob/main/ROADMAP.md)
31
+ items or issues.
@@ -19,6 +19,6 @@ jobs:
19
19
  # clippy does everything cargo check does, so it replaces it rather than adding to it
20
20
  - run: cargo clippy --all-targets -- -D warnings
21
21
  - run: cargo test
22
- - run: python -m pip install ".[report]"
22
+ - run: python -m pip install ".[report,test]"
23
23
  - run: python -m unittest discover -s "$GITHUB_WORKSPACE/tests"
24
24
  working-directory: /tmp
@@ -78,6 +78,17 @@ jobs:
78
78
  target: x64
79
79
  args: --release --out dist --find-interpreter
80
80
  sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
81
+ # Preserve the 3.10 wheel when the runner image no longer includes it.
82
+ - uses: actions/setup-python@v6
83
+ with:
84
+ python-version: "3.10"
85
+ architecture: x64
86
+ - name: Build Python 3.10 wheel
87
+ uses: PyO3/maturin-action@v1
88
+ with:
89
+ target: x64
90
+ args: --release --out dist --interpreter python
91
+ sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
81
92
  - uses: actions/upload-artifact@v6
82
93
  with:
83
94
  name: wheels-windows-x64
@@ -4,6 +4,7 @@ Cargo.lock
4
4
  __pycache__/
5
5
  ### My claude md file
6
6
  CLAUDE.md
7
+ .claude/settings.local.json
7
8
  data/*
8
9
  !data/EURUSD_1H.csv
9
10
  .env
@@ -0,0 +1,182 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ ## [0.3.0] - 2026-11-19
6
+
7
+ ### Added
8
+ - Reference strategy data exposes case-sensitive OHLCV NumPy views, pandas
9
+ accessors, and pip size. Each callback sees only its visible prefix.
10
+ - Opt-in queued market execution through `trade_on_close` and `finalize_trades`.
11
+ Python strategies, native strategies, and signal runs share next-open or
12
+ previous-close fills and final-bar processing. Results expose open positions
13
+ and marked final equity. The queued timeline follows backtesting.py 0.6.6
14
+ with FX sizing and costs. See [queued market execution](README.md#queued-market-execution).
15
+ - Optional `data_mode="reference"` for backtesting.py 0.6.6 DataFrame input:
16
+ periods, duplicate labels, exact timestamps, aligned features, indexed equity
17
+ and event views, and reports that retain source labels. The default FX input
18
+ policy and order API remain unchanged. Reference mode rejects calendar swaps.
19
+ See [REFERENCE_INPUT.md](REFERENCE_INPUT.md) for scope and remaining API work.
20
+ - Required CI input-conformance fixtures against `backtesting==0.6.6` through
21
+ the `test` extra.
22
+ - Optional immutable `MarginConfig`, current-price gross used/free margin,
23
+ cost-aware entry checks, returned `OrderResult` values, durable rejection
24
+ records, and full-book liquidation with terminal account status. Python,
25
+ native, and signal execution share the policy; margin defaults to disabled.
26
+ - Margin configuration and stopout evidence in HTML reports, plus a
27
+ [margin guide](MARGINS.md) and hand-calculated examples.
28
+ - Explicit Python `timestamp_unit` and native CSV `TimestampUnit` options for
29
+ numeric epoch input. Naive datetimes mean UTC; offsets normalize to UTC.
30
+ - Optional `SwapConfig` for signed long/short overnight financing in account
31
+ currency per lot. Configure local rollover time, IANA timezone, weekday weights,
32
+ and holiday date overrides. Swaps are disabled by default.
33
+ - Separate position/trade financing, total swap cash flow, dated posting records,
34
+ and HTML report financing details. Native, Python, and signal runs share the
35
+ rollover policy and reconcile partial-close financing without charging twice.
36
+ - Constant-time Python `Strategy` and `Broker` properties `has_positions` and
37
+ `position_count`, avoiding position-list copies for presence and count checks.
38
+ - A callback benchmark with separate conversion, engine construction,
39
+ initialization, and simulation timings, native and Python no-op baselines,
40
+ indicator and position-access workloads, correctness checks, and peak RSS.
41
+ - Documented and regression-tested the stop-first intrabar SL/TP policy,
42
+ inclusive touches and next-bar checks for new entries.
43
+ - Contributor setup and validation guidance, bug/feature issue templates, an
44
+ API/platform compatibility policy, and a prioritized FX roadmap.
45
+
46
+ ### Fixed
47
+ - Nonpositive-equity histories return zero Sharpe instead of dividing by zero
48
+ or computing percentage returns on debt.
49
+ - Timestamp conversion floors to exact whole seconds, including before 1970,
50
+ without floating-point rounding or row promotion of integer timestamps.
51
+ Reports use the same saved seconds as the engine and financing ledger.
52
+ - Default FX market-data boundaries reject nonfinite/nonpositive OHLC values, inconsistent
53
+ candle ranges, negative/nonfinite volume, and duplicate or backwards timestamps
54
+ after conversion to whole seconds. Python errors identify the bar and field;
55
+ empty inputs remain valid. Optimization checks data before calling signals.
56
+ - Native CSV loading resolves columns by case-insensitive name, defaults missing
57
+ volume to zero, and returns typed errors instead of panicking. Checked native
58
+ `Bar::try_new`, `Engine::try_new`, and `data::validate_bars` are also available.
59
+ - Pandas input uses bulk typed buffers to construct native bars, removing
60
+ per-row Series and temporary Python Bar allocation from numeric DatetimeIndex
61
+ ingestion. Initialization history avoids an intermediate native copy. Preserve
62
+ independent runs, report snapshots, and Bar identity. Timestamp policy is
63
+ explicit as described above.
64
+ See the ingestion benchmark for measured setup and total-runtime improvements.
65
+ - Python strategy dispatch reuses the Python method-name string for `next`,
66
+ while preserving per-bar method lookup, distinct Bar objects, and exceptions.
67
+ - The existing cross-library comparison and benchmark now use matched fixed-unit
68
+ next-open strategies, verify trades and full equity curves, and report setup,
69
+ simulation, and total timings separately. Spread is zero; commission is matched.
70
+ - Python constructors reject nonfinite or out-of-range broker settings. Order,
71
+ partial-close, stop-update, closing-price, and equity-price inputs are checked
72
+ before account mutation. Finite nonpositive partial sizes remain no-ops.
73
+ - Optimization rejects malformed or nonfinite signals, including direct
74
+ `run_grid()` calls. Native SMA calls reject invalid sizes and windows before
75
+ simulation rather than risking a Rust panic.
76
+ - SL/TP processing checks the midpoint open first: crossed stops fill at the
77
+ adverse open, while crossed targets receive the favorable open, before any
78
+ later range touches. Exit spread, commission, and conversion still apply.
79
+ Bars that open inside both levels retain stop-first intrabar behavior.
80
+ - Batch stop-loss/take-profit processing uses a single linear pass, preserving
81
+ survivor and trade order, fills, and accounting when many positions exit together.
82
+ - Native engine runs reset cash, positions, trade history, and position IDs before
83
+ each independent simulation, including repeated `run_native_sma()` calls.
84
+ - `spread` now means the full bid–ask width around midpoint OHLC prices. Each
85
+ fill applies half the width, so a one-pip EURUSD spread costs $10 per standard
86
+ lot on a flat round trip, before commission, instead of $20.
87
+ - Open equity uses the bid/ask price available to close each position and includes
88
+ the exit-side spread (future exit commission is still charged only at closing).
89
+
90
+ ### Migration
91
+ - Strategy and Broker `buy`/`sell` return `OrderResult` instead of `None`.
92
+ Native `Engine::run` and `run_with_swap` return
93
+ `Result<Stats, SimulationError>`, and native broker close methods and
94
+ `check_sl_tp` return `Result<(), MarginError>`. Handle results with `?` or a
95
+ match. Margin checks
96
+ require an explicit `MarginConfig`. A stopout halts further callbacks, retains
97
+ real negative cash, and preserves the full equity timeline. See [MARGINS.md](MARGINS.md).
98
+ - Numeric timestamp columns now require `timestamp_unit="s"`, `"ms"`, `"us"`, or
99
+ `"ns"`. Use `"ns"` for the previous implicit pandas units. Fractional dates
100
+ floor instead of rounding and truncating; rerun affected backtests and resolve
101
+ collisions at whole-second precision. Native numeric CSV uses signed integers
102
+ with `load_csv_with_timestamp_unit`. See [timestamp rules](MARKET_DATA.md#timestamp-sources-and-ordering).
103
+ - Malformed candles and duplicate/reversed whole-second timestamps now raise
104
+ errors, including repeated timestamps previously accepted with swaps enabled.
105
+ Resolve subsecond collisions explicitly before simulation. Native `load_csv`
106
+ now returns `Result<Vec<Bar>, DataError>`; handle it with `?` or an explicit
107
+ match. See [MARKET_DATA.md](MARKET_DATA.md) for the complete input policy.
108
+ - Python cash, contract size, conversion rate, opening sizes, prices, and supplied
109
+ SL/TP levels must be positive and finite; spread and commission must be finite
110
+ and nonnegative. Invalid numeric inputs now raise `ValueError`. Signal arrays
111
+ must be one-dimensional, finite, and contain one target per bar. See README
112
+ numeric input validation for partial-close and native SMA rules.
113
+ - Gap-bar SL/TP fills now use the opening price instead of the configured level.
114
+ An opening target also takes precedence over a later stop touch. Rerun affected
115
+ backtests: PnL, equity, and strategy decisions can change; there is no legacy
116
+ gap-fill option. See README execution policy for long/short examples.
117
+ - Double the previous `spread` input to preserve pre-change fills and completed
118
+ trade PnL. Equity curves can still differ because marking now includes exit
119
+ spread. SL/TP levels remain midpoint levels. See README price conventions.
120
+
121
+ ## [0.2.0] - 2026-08-30
122
+
123
+ First release to reach PyPI since 0.1.1 — the `v0.1.2` tag predated the release
124
+ workflow, so 0.1.2 was tagged but never published. Everything listed under 0.1.2
125
+ below ships here too.
126
+
127
+ ### Added
128
+ - `Strategy.update_sl(id, stop_loss)` — move the stop on an open position in place,
129
+ so a trailing stop doesn't pay spread and commission to close and reopen
130
+ - `Strategy.close_partial(id, lot_size)` — scale out of a position, leaving the
131
+ remainder open under the same id
132
+
133
+ ### Changed
134
+ - `Broker` closes positions through one internal `settle` helper instead of four
135
+ copies of the same PnL and commission arithmetic
136
+
137
+ ## [0.1.2] - 2026-08-13
138
+
139
+ ### Added
140
+ - `Backtest.optimize()` — parallel grid search over a vectorised signal function.
141
+ Simulations run on native threads with the GIL released (`src/optimise.rs`);
142
+ 157x faster than looping `run()` over the same grid.
143
+ - `strategy_class` is now optional, so `Backtest(df, cash=...)` works for optimization
144
+ - Standalone HTML reports (`Backtest.plot()`) and `examples/html_report.py`
145
+ - Three-way speed benchmark against backtesting.py (`examples/benchmark.py`)
146
+ - Sample EURUSD hourly data is now in the repo, so the examples run on a fresh clone
147
+
148
+ ### Fixed
149
+ - Data access inside `next()` is O(1) per bar instead of O(n) — ~2.6x faster
150
+
151
+ ### Changed
152
+ - `numpy` is now a direct dependency (it was already pulled in by pandas)
153
+ - CI runs `cargo clippy -- -D warnings` in place of `cargo check`
154
+
155
+ ## [0.1.1] - 2026-07-05
156
+
157
+ ### Added
158
+ - `self.data`, `self.index`, `self.cash`, `self.equity` properties on Strategy
159
+ - Sharpe ratio in Stats output (unannualized)
160
+ - `__repr__` on Position — readable output when printing positions
161
+ - DataFrame column validation with clear error message
162
+
163
+ ### Fixed
164
+ - Trade PnL in history now stores net PnL (after exit commission) — per-trade stats were slightly optimistic
165
+ - `Position` pyclass uses `from_py_object` to fix PyO3 deprecation warning
166
+ - Removed dead `AttributeError` swallow in engine.rs
167
+
168
+ ### Examples
169
+ - Added `examples/sma_cross.py` — SMA 10/50 crossover on EURUSD hourly data
170
+ - Added `examples/compare_bt.py` — side-by-side comparison against backtesting.py
171
+
172
+ ## [0.1.0] - 2026-06-21
173
+
174
+ ### Added
175
+ - Event-driven backtesting engine on OHLCV bar data
176
+ - Simulated broker with buy, sell, close_all, close_position
177
+ - Per-position stop loss and take profit
178
+ - Realistic FX lot sizing (0.01 / 0.10 / 1.00) with contract_size and quote_to_account conversion
179
+ - Full trade history with PnL per trade
180
+ - Stats: return, win rate, avg PnL, best/worst trade, profit factor, max drawdown
181
+ - Python API — inherit Strategy, run Backtest
182
+ - PyO3 Rust extension with Python wrapper
@@ -0,0 +1,79 @@
1
+ # Compatibility policy
2
+
3
+ ## Python and platforms
4
+
5
+ Package metadata declares Python >=3.9. CPython is the intended interpreter;
6
+ PyPy support is not currently verified. pandas and numpy are required.
7
+ HTML reporting additionally requires Plotly >=5 through the `report` extra.
8
+
9
+ | Area | Current coverage |
10
+ | --- | --- |
11
+ | Functional CI | Ubuntu, CPython 3.12; Rust checks and installed-package Python tests |
12
+ | Linux release wheel targets | x86_64 and aarch64, with manylinux selected by maturin |
13
+ | macOS release wheel targets | Intel x86_64 and Apple Silicon aarch64 |
14
+ | Windows release wheel target | x64 |
15
+ | Source distributions | Built by the release workflow; require Rust and a native compiler to install |
16
+
17
+ These wheel targets describe the configured release workflow, not a guarantee
18
+ that every Python version has a published wheel or has passed functional tests.
19
+ The extension does not currently use abi3, so wheel compatibility depends on
20
+ the interpreter and platform tags. The wheel jobs discover available
21
+ interpreters. Windows also builds Python 3.10 explicitly. Check the artifacts
22
+ for your interpreter before relying on wheel availability.
23
+
24
+ If pip falls back to a source build, install a current stable Rust toolchain
25
+ and your platform's compiler/linker, then retry installation. Contributor
26
+ setup is in [CONTRIBUTING.md](CONTRIBUTING.md). Broader wheel verification and
27
+ functional coverage are tracked in issues
28
+ [#35](https://github.com/KhizarImran/backtestingfx/issues/35) and
29
+ [#36](https://github.com/KhizarImran/backtestingfx/issues/36).
30
+
31
+ ## Public API and stability
32
+
33
+ Input compatibility targets backtesting.py **0.6.6**, commit
34
+ `9c2b8e1c99f3a860883222ba8d6d5b5cac3a932d`, through the explicit
35
+ `data_mode="reference"` option. See [reference input](REFERENCE_INPUT.md) for
36
+ index, validation, strategy, and result behavior. CI requires the pinned
37
+ reference package through the `test` extra. Full strategy, order, sizing, cost,
38
+ and results compatibility remains tracked in
39
+ [#61](https://github.com/KhizarImran/backtestingfx/issues/61).
40
+
41
+ The project is pre-1.0. Public Python imports from `backtestingfx`, documented
42
+ strategy methods/properties, result fields, and documented execution assumptions
43
+ are the compatibility surface. Underscore-prefixed members and internal Rust
44
+ implementation details may change; existing examples using private strategy
45
+ members do not make those members stable.
46
+
47
+ Before 1.0, intentional incompatible API changes belong in a minor release
48
+ with a changelog entry and migration instructions. Patch releases should
49
+ preserve API signatures, but correctness fixes can change simulated fills,
50
+ PnL, equity, and statistics. Such changes must identify the previous and new
51
+ behavior and any migration required. After 1.0, intentional incompatible public
52
+ API changes require a major release.
53
+
54
+ Where practical, deprecated Python APIs emit `DeprecationWarning` and remain
55
+ available for at least one minor release before removal. Document the
56
+ replacement and planned removal version. A correctness fix that cannot retain
57
+ the old behavior safely may be made without a deprecation period, with an
58
+ explicit explanation and migration notes.
59
+
60
+ Changes to the minimum Python version or supported platform targets must be
61
+ announced in the changelog and this policy. Before 1.0 they belong in a minor
62
+ release; after 1.0 they require a major release.
63
+
64
+ ## Reproducibility
65
+
66
+ Pin the library and dependency versions for reproducible research. Record data
67
+ source, instrument, timeframe, timezone, sizing, spread, commission, and
68
+ conversion assumptions. Read [CHANGELOG.md](CHANGELOG.md) before upgrading:
69
+ unchanged strategy code can produce different results after a modeling fix.
70
+ The full bid–ask spread correction in Unreleased is one such example.
71
+
72
+ With optional swaps enabled, also record signed long/short rates, the rollover
73
+ timezone and time, weekday weights, and date overrides. Timezone rules come
74
+ from the `chrono-tz` database embedded in the build. Pin the package and native
75
+ dependency versions when reproducing historical rollover results. See
76
+ [SWAPS.md](SWAPS.md) for calendar behavior.
77
+
78
+ This policy describes project expectations; the current tests and published
79
+ artifacts establish the coverage actually verified for each release.
@@ -0,0 +1,97 @@
1
+ # Contributing
2
+
3
+ backtestingfx focuses on FX research with OHLCV bars, lot sizing, spread,
4
+ commission, optional overnight financing, and quote-to-account conversion. See the [roadmap](ROADMAP.md)
5
+ for priorities and the [compatibility policy](COMPATIBILITY.md) before changing
6
+ public behavior. Search existing issues before opening a bug or feature request.
7
+
8
+ ## Local setup
9
+
10
+ Install Git, CPython 3.9 or newer, and a current stable Rust toolchain with
11
+ Cargo and Clippy. The crate uses Rust edition 2024 (Rust 1.85 or newer);
12
+ dependency requirements may require a newer compiler. Python 3.12 on Linux
13
+ matches the current CI configuration. Building the extension also requires
14
+ your platform's native compiler/linker (for example, Xcode Command Line Tools
15
+ on macOS or MSVC Build Tools on Windows).
16
+
17
+ From your clone's root:
18
+
19
+ ```bash
20
+ git clone https://github.com/KhizarImran/backtestingfx.git
21
+ cd backtestingfx
22
+ python -m venv .venv
23
+ source .venv/bin/activate
24
+ python -m pip install --upgrade pip
25
+ python -m pip install "maturin>=1.0,<2.0" pandas numpy "plotly>=5" "backtesting==0.6.6"
26
+ maturin develop
27
+ ```
28
+
29
+ On Windows, activate with `.venv\Scripts\Activate.ps1` in PowerShell instead.
30
+ Use your virtual environment's Python for all commands. Run `maturin develop`
31
+ again after Rust changes. Python source changes are visible through the
32
+ development installation.
33
+
34
+ ## Checks
35
+
36
+ Run the Rust checks from the repository root:
37
+
38
+ ```bash
39
+ cargo clippy --all-targets -- -D warnings
40
+ cargo test
41
+ ```
42
+
43
+ Check the installed Python package outside the source directory, as CI does.
44
+ This avoids accidentally importing the source package without its built extension.
45
+
46
+ ```bash
47
+ python -m pip install ".[report,test]"
48
+ repo_dir="$PWD"
49
+ cd /tmp
50
+ python -m unittest discover -s "$repo_dir/tests"
51
+ cd "$repo_dir"
52
+ ```
53
+
54
+ On Windows, save the repository path, change to a temporary directory, and pass
55
+ the absolute path to `tests` to `python -m unittest discover -s`. Reinstall
56
+ with `python -m pip install --force-reinstall ".[report,test]"` after changes when
57
+ using this regular installation rather than `maturin develop`.
58
+
59
+ ## Examples
60
+
61
+ Run these from the repository root after building/installing the package:
62
+
63
+ ```bash
64
+ python examples/sma_cross.py
65
+ python examples/optimize.py
66
+ python examples/swaps.py
67
+ python examples/margin.py
68
+ python examples/html_report.py
69
+ cargo run --example simple_strategy
70
+ ```
71
+
72
+ SMA and optimization examples use the included `data/EURUSD_1H.csv`.
73
+ The HTML example generates synthetic data, writes
74
+ `backtestingfx-report.html`, and attempts to open a browser. It requires the
75
+ `report` extra. Comparison and benchmark scripts additionally require
76
+ `python -m pip install backtesting==0.6.6`; report their versions and execution
77
+ assumptions when sharing results. See [the matched comparison](examples/benchmark.md)
78
+ for correctness checks and separate setup/run timings. The `test` extra pins the
79
+ reference package. Input conformance tests require it, and CI installs it.
80
+
81
+ The swap example uses a small flat-price fixture and checks financing and
82
+ partial-close reconciliation. See [SWAPS.md](SWAPS.md) for rate units, rollover
83
+ calendars, and native execution. For profiling and total-runtime comparisons,
84
+ see [the ingestion benchmark](examples/benchmark_ingestion.md).
85
+
86
+ ## Pull requests
87
+
88
+ Create a focused branch and describe the problem, resulting behavior, and
89
+ validation performed. Link the relevant issue using `Closes #number` when
90
+ the PR completes it. For behavior changes, add regression tests with small,
91
+ deterministic inputs and update documentation and the Unreleased changelog.
92
+ Explain intentional changes to fills, costs, timestamps, or statistics and
93
+ include migration guidance when existing results can change.
94
+
95
+ Use the bug template to report versions, input shape and timestamps, broker
96
+ settings, expected versus actual results, and a minimal runnable reproduction.
97
+ Use synthetic or shareable data rather than private trading records.