Metadata-Version: 2.4
Name: siliconmetatrader5
Version: 1.2.0
Summary: MetaTrader5 for Apple Silicon via Docker
Author-email: Bahadir Umut Iscimen <buiscimen@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/buiscimen/siliconmetatrader5
Project-URL: Repository, https://github.com/buiscimen/siliconmetatrader5
Project-URL: Issues, https://github.com/buiscimen/siliconmetatrader5/issues
Keywords: metatrader5,mt5,trading,apple silicon,docker
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 :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: rpyc>=5.0.0

# SiliconMetaTrader5 🍏📈

**MetaTrader 5 Python library for macOS Apple Silicon**

[![PyPI](https://img.shields.io/pypi/v/siliconmetatrader5)](https://pypi.org/project/siliconmetatrader5/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

- 🇹🇷 [Türkçe Doküman](README_TR.md)
- 🆕 [Update Notes v1.2.0 (EN)](UPDATE_NOTES_v1.2.0_EN.md)
- 🆕 [Güncelleme Notları v1.2.0 (TR)](UPDATE_NOTES_v1.2.0_TR.md)

---

## Installation / Upgrade

To get this release, upgrade and pin to `1.2.0`:

```bash
python3 -m pip install --upgrade "siliconmetatrader5==1.2.0"
python3 -m pip show siliconmetatrader5
```

Expected output includes:

```text
Version: 1.2.0
```

---

## Why this release matters

This version is focused on **real-world multi-bot stability**:

- safer process shutdown behavior (`close()` no longer kills everyone)
- no false per-call timeout disconnects in slow/emulated environments
- watchdog support for "bridge alive but stuck" detection
- clearer bridge errors for easier debugging

---

## Quick Start

```python
from siliconmetatrader5 import MetaTrader5
import pandas as pd

mt5 = MetaTrader5(host="localhost", port=8001, keepalive=True)

if not mt5.initialize():
    raise RuntimeError("MT5 initialize failed")

rates = mt5.copy_rates_from_pos("EURUSD", mt5.TIMEFRAME_M15, 0, 100)
print(pd.DataFrame(rates).tail())

# Recommended: close only this process connection
mt5.close()
```

---

## v1.2.0 Changes Explained

### 1) `close()` vs `shutdown()` is now explicit

Before this behavior change, users could accidentally stop the shared remote terminal when one process exited.

Now:

- `close()` closes only the current Python client process.
- `shutdown()` or `close(remote_shutdown=True)` stops the remote MT5 terminal globally.

Why this is critical:

- If you run `monitor + trade + history` together, one process exiting with `close()` should not terminate the other two.

Behavior table:

| Method | Scope | Typical use |
|---|---|---|
| `close()` | This process only | Normal app exit, multi-bot safe |
| `shutdown()` | Global terminal | Intentional full stop |
| `close(remote_shutdown=True)` | This process + global terminal | Single-process controlled setup |

Concrete Bot1/Bot2/Bot3 example:

- Bot1 = monitor process
- Bot2 = trade process
- Bot3 = history/backtest process

Rules:

- If Bot1 exits normally, it should call `close()` only.
- If Bot2 restarts, it should call `close()` only.
- If Bot3 finishes replay, it should call `close()` only.
- None of the above should stop MT5 for other running bots.
- Only your orchestrator/controller process should call `shutdown()` (or `close(remote_shutdown=True)`) when you intentionally want to stop the whole MT5 terminal.

### 2) `timeout` is no longer active runtime behavior

Important clarification:

- `timeout` is **not** an idle connection lifetime control anymore.
- It is accepted only for backward compatibility.
- Active per-call timeout enforcement is removed to avoid false disconnects in emulated/slow environments.

Recommended pattern:

- Use `keepalive=True` for long-running bots.
- Close intentionally with `close()` or `shutdown()` based on your target scope.

### 3) Watchdog support added

New APIs:

- `start_watchdog(...)`
- `stop_watchdog()`
- `health_status()`

What watchdog can detect:

- repeated probe failures
- stuck in-flight calls (`CALL_STUCK`)
- optional auto-reconnect flow

Example:

```python
from siliconmetatrader5 import MetaTrader5

mt5 = MetaTrader5(host="localhost", port=8001, keepalive=True)
mt5.initialize()

mt5.start_watchdog(
    interval_sec=5,
    max_miss=3,
    probe_timeout_sec=2,
    stall_timeout_sec=20,
    auto_reconnect=False,
)

print(mt5.health_status())

mt5.stop_watchdog()
mt5.close()
```

### 4) Bridge reliability improvements

Internally this release also includes:

- core MT5 wrappers using direct remote calls (`getattr(self.__mt5, method)`) instead of broad eval-based forwarding
- normalized bridge exceptions via `MT5BridgeError`
- reason codes: `TIMEOUT`, `RESULT_EXPIRED`, `CONNECTION_CLOSED`, `RPC_ERROR`
- `market_book_release(symbol)` argument forwarding fix

This helps with:

- clearer error debugging in bots/logs
- fewer ambiguous failures
- safer handling of complex argument types in regular API calls

---

## Data Method Selection (Important)

Use-case based recommendation:

| Use case | Recommended |
|---|---|
| Live monitor / freshest bars | `copy_rates_from_pos()` |
| Backtest/history by date range | `copy_rates_from()` / `copy_rates_range()` |

```python
# live
live_rates = mt5.copy_rates_from_pos("EURUSD", mt5.TIMEFRAME_M5, 0, 500)

# backtest/history
hist_rates = mt5.copy_rates_range("EURUSD", mt5.TIMEFRAME_M5, dt_from, dt_to)
```

---

## Migration Checklist (from older versions)

1. Upgrade package:

```bash
python3 -m pip install --upgrade "siliconmetatrader5==1.2.0"
```

2. Verify version:

```bash
python3 -m pip show siliconmetatrader5
```

3. Review shutdown path in your bot:
- replace routine global stop calls with `close()` for normal exits
- keep `shutdown()` only for intentional full terminal stop

4. `timeout=...` in old code can remain for compatibility, but it has no active effect.

5. For long-running processes, use `keepalive=True` and optionally watchdog.

---

## API Snapshot

Constructor:

```python
mt5 = MetaTrader5(host="localhost", port=8001, keepalive=False, timeout=None)
```

`timeout` is accepted for backward compatibility and ignored in active runtime behavior.

Additional client methods:

- `ping()`
- `eval(command)`
- `execute(command)`
- `close(remote_shutdown=False)`
- `start_watchdog(...)`
- `stop_watchdog()`
- `health_status()`

---

## Requirements

- Python 3.9+
- `rpyc>=5.0.0`
- Running MT5 bridge server

## License

MIT License

## Author

**Bahadir Umut Iscimen**
- GitHub: [@bahadirumutiscimen](https://github.com/bahadirumutiscimen)
- Email: buiscimen@gmail.com
