PythonMetaTrader5 2.2__py3-none-any.whl → 3.0.0__py3-none-any.whl

pythonmetatrader5-3.0.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: PythonMetaTrader5
+Version: 3.0.0
+Summary: Safe, typed trading layer over the official MetaTrader5 Python API
+Author-email: Wiktor Jelen <wiktorjn@gmail.com>
+License-Expression: CC-BY-NC-4.0
+Project-URL: Homepage, https://github.com/Akinzou/MetaTrader5-Python
+Project-URL: Bug Tracker, https://github.com/Akinzou/MetaTrader5-Python/issues
+Project-URL: Changelog, https://github.com/Akinzou/MetaTrader5-Python/blob/master/CHANGELOG.md
+Keywords: metatrader5,mt5,trading,forex,algotrading
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: MetaTrader5; sys_platform == "win32"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Dynamic: license-file
+
+# PythonMetaTrader5
+
+[![CI](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5)](https://pypi.org/project/PythonMetaTrader5/)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg)
+[![PyPI Downloads](https://static.pepy.tech/badge/pythonmetatrader5)](https://pepy.tech/projects/pythonmetatrader5)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/BARYa55KS8)
+
+A safe, typed trading layer over the official
+[`MetaTrader5`](https://pypi.org/project/MetaTrader5/) Python package.
+
+Built for bots (webhook executors, signal followers) where a trading call must
+**never hang, never retry blindly, and never fail silently**:
+
+- **Every trading call returns.** Requotes are retried a bounded number of times
+  with a fresh quote; everything else comes back immediately as a typed error.
+  (The deprecated `Broker.login(ToEffect=True)` is the one exception: as in
+  2.x, it keeps trying until the login works.)
+- **No silent defaults.** Values that MT5 would quietly read as something else
+  are refused before sending: `sl=0` ("no stop"), `ticket=0` (possibly "no
+  filter"), `volume=True` (one lot), NaN and infinities.
+- **No double fills.** Timeouts and lost connections are never auto-retried:
+  the order may already be live.
+- **Typed results.** `Ok(receipt)` or `Err(TradeError)` with an `ErrorKind`
+  (`MARKET_CLOSED`, `NO_MONEY`, `INVALID_STOPS`, ...) instead of magic numbers.
+- **Correct prices and lots.** Prices snap to the symbol's tick grid, volumes
+  are checked against min/max/step, the filling mode is chosen from the symbol.
+- **Magic numbers.** Tag your bot's trades and close/cancel only those.
+- **SL/TP as prices or distances in points.**
+- **2.x compatible.** The old `Broker` class still works (deprecated).
+
+> One connection per process: the official package keeps a single global
+> terminal session, so a second `connect()` (or its failed login) affects the
+> first. Run one process per account.
+>
+> Thread-safe within the library: every terminal call holds one process-wide
+> lock, so a threaded webhook server can share a `Trader`. The MT5 functions
+> re-exported through `PythonMetaTrader5` hold it for each single call (a pair
+> such as `order_send` + `last_error` is not atomic). Calls you make to the
+> `MetaTrader5` module directly bypass it.
+>
+> Requires Windows with a MetaTrader 5 terminal installed (the official
+> `MetaTrader5` package is Windows-only). Enable **Algo Trading** in the terminal.
+
+## Installation
+
+```bash
+pip install PythonMetaTrader5
+```
+
+## Quick start
+
+```python
+from PythonMetaTrader5 import Err, Ok, Side, Stop, connect
+
+match connect(12345678, "password", "MetaQuotes-Demo", magic=1001):
+    case Err(error):
+        raise SystemExit(f"cannot connect: {error}")
+    case Ok(trader):
+        pass
+
+with trader:  # shuts the terminal connection down on exit
+    result = trader.open_position(
+        "EURUSD", Side.BUY, 0.10,
+        sl=Stop.points(1000),  # 1000 points below the entry price
+        tp=1.12500,            # a plain float is an absolute price
+        comment="webhook #42",
+    )
+    match result:
+        case Ok(receipt):
+            print("filled at", receipt.price, "deal", receipt.deal)
+        case Err(error):
+            print("not opened:", error.kind, error.message)
+
+    trader.close_positions("EURUSD")  # only this bot's (magic 1001) positions
+```
+
+## API
+
+`connect(login, password, server, *, path=None, timeout_ms=60000, magic=0,
+deviation=10, retry=None) -> Result[Trader, TradeError]`
+
+`login` must be a positive integer or a string of ASCII digits; `True`,
+`12345678.9` and similar values are rejected rather than coerced.
+
+| `Trader` method | Returns |
+|---|---|
+| `open_position(symbol, side, volume, *, sl=None, tp=None, price=None, comment=None)` | `Result[TradeReceipt, TradeError]` |
+| `place_limit_order(symbol, side, volume, price, *, sl=None, tp=None, comment=None)` | `Result[TradeReceipt, TradeError]` |
+| `close_positions(symbol=None, *, ticket=None, magic=<own>, comment=None)` | `Result[list[TradeReceipt], BatchFailure]` |
+| `cancel_pending_orders(symbol=None, *, magic=<own>, kind=None)` | `Result[list[TradeReceipt], BatchFailure]` |
+| `positions(symbol=None, *, ticket=None, magic=None)` | `Result[list[Position], TradeError]` |
+| `pending_orders(symbol=None, *, magic=None, kind=None)` | `Result[list[PendingOrder], TradeError]` |
+| `shutdown()` | `None` |
+
+- `side`: `Side.BUY` / `Side.SELL`, or the strings `"buy"`, `"sell"`, `"long"`, `"short"`.
+- `sl` / `tp`: a float is an **absolute price**; `Stop.points(n)` is a distance
+  of `n` points from the entry price (`Stop.at_price(p)` is the explicit form).
+  For limit orders the distance is measured from the limit price, and for a
+  market order with an explicit `price` from that price. A float stop that is
+  zero, negative or not finite is rejected (`INVALID_STOPS`); pass `None` for
+  no stop. `Stop.points()` / `Stop.at_price()` raise `ValueError` unless the
+  value is a positive finite number (bool and str included; a zero stop would
+  mean "no stop" to MT5); the sign of a points distance is ignored. A `kind`
+  that is not a `StopKind` raises `TypeError`. A stop that resolves outside
+  the tick grid's range, or to zero or below, is `INVALID_STOPS` when the
+  order is built. For a value that may be bad at runtime, such as
+  an ATR that is NaN during warm-up, use
+  `Stop.parse(value, StopKind.POINTS)`, which returns `Ok(stop)` /
+  `Err(INVALID_STOPS)`.
+- Amounts may be `int`, `float`, `Decimal` or numpy scalars; `bool` and strings
+  are refused (the deprecated `Broker` still converts numeric strings).
+- `price` (market orders): send at this price once instead of the live quote.
+- `comment`: at most 29 UTF-16 units: 29 characters, but characters outside
+  the BMP, such as most emoji, count as 2 (combined emoji more). The `MetaTrader5` package refuses 30 or more (measured on 5.0.6231; its
+  docs say 31). Longer comments, and comments that are not `str`, are rejected
+  before sending, not truncated.
+- **`close_positions()` and `cancel_pending_orders()` act only on the trader's
+  own `magic`** unless you pass another one (ADR 0011); `magic=None` is still
+  "own". To act on the whole account, manual trades included, pass
+  `magic=ANY_MAGIC`. A `ticket` is closed whatever its magic. `positions()`
+  and `pending_orders()` still list every magic by default.
+- Manual trades have magic 0, the `connect()` default, so set your own `magic`
+  for this to protect them. Until then a close/cancel that affects magic-0
+  items logs a warning; `magic=0` passed explicitly acknowledges it. On a
+  netting account a position keeps the magic of the deal that opened it, so
+  merged volume cannot be told apart by magic; a defaulted close/cancel that
+  matches nothing logs how many items with other magics it left open.
+- A magic must be an integer from 0 to 2\*\*64-1 (MT5's ulong); `connect()`
+  returns `Err(INVALID_ARGUMENT)` otherwise, e.g. for `None`. An empty string
+  `""` as symbol is rejected too.
+- `BatchFailure.errors` names every position/order that failed
+  (`TradeError.ticket`). `BatchFailure.succeeded` holds the receipts of the
+  ones that worked; their `order` / `deal` are the IDs of the closing deal, not
+  the position ticket.
+- `ticket` must be a positive integer; `0`, `True` or `"7"` are rejected.
+
+### Errors
+
+`TradeError(kind, message, retcode=None, receipt=None, ticket=None)`. The
+`receipt` carries the broker's raw answer when there was one. Retry policy:
+
+| Server answer | What happens |
+|---|---|
+| market deal (entry or close): done | `Ok(receipt)` |
+| pending order: placed or done | `Ok(receipt)` |
+| market deal: partial fill | `PARTIAL_FILL` with the receipt; part of the deal exists, never re-sent |
+| market deal: placed (queued, not executed) | `OUTCOME_UNKNOWN` with the receipt, never re-sent |
+| requote, price changed, no quotes, too many requests | retried with a fresh quote, up to `RetryPolicy.attempts` (default 3, 0.5 s apart), then `RETRIES_EXHAUSTED` |
+| timeout, no connection, or `order_send` lost in IPC | `OUTCOME_UNKNOWN`, never retried: check `positions()` first |
+| anything else | the matching `ErrorKind`, returned at once |
+| refused before sending: the terminal's symbol data cannot price an order (point 0, NaN tick size, volume step 0, ...) | `BROKEN_SYMBOL_DATA`, the same on every resend: escalate, don't retry. Closing still works on such symbols |
+
+```python
+from PythonMetaTrader5 import RetryPolicy, connect
+
+connect(..., retry=RetryPolicy(attempts=5, delay_seconds=0.2))
+```
+
+### Logging
+
+The library logs through the standard `logging` module under the
+`PythonMetaTrader5` logger and never configures handlers itself. Without any
+logging configuration, warnings and errors still reach stderr.
+
+## Migrating from 2.x
+
+`from PythonMetaTrader5 import Broker` keeps working and emits a
+`DeprecationWarning`. `from PythonMetaTrader5 import *` still brings in the
+`MetaTrader5` functions and constants, as in 2.x. Several 2.x behaviours were unsafe and changed: see
+[MIGRATION.md](MIGRATION.md).
+
+## Development
+
+```bash
+python -m venv .venv && .venv\Scripts\activate
+pip install -e ".[dev]"
+ruff check src tests scripts && ruff format --check src tests scripts
+mypy
+pytest --cov
+```
+
+`tests/contract` compares the unit-test fakes with the installed `MetaTrader5`
+package and is skipped where it is not installed (anywhere but Windows).
+Integration tests trade on a **demo** account and are skipped unless
+`MT5_LOGIN`, `MT5_PASSWORD` and `MT5_SERVER` are set (they refuse to run on a
+live account): `pytest -m integration`.
+
+Architecture and decisions: [docs/architecture.md](docs/architecture.md),
+[docs/adr](docs/adr).
+
+## License
+
+[CC BY-NC 4.0](LICENSE). Trading carries risk; this software comes without any
+warranty.

pythonmetatrader5-3.0.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+PythonMetaTrader5/__init__.py,sha256=bALjGPZAZJwaduG6zQ_2ifF1yYSlSUwug6iRujTnw58,2761
+PythonMetaTrader5/connection.py,sha256=xA6VhhqNM-oXGh3ieWS8bCr9yAb4aEVtontgDsHwrQ4,1898
+PythonMetaTrader5/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+PythonMetaTrader5/result.py,sha256=Q3RpcspZgb8nEf8Tnm_W4cx9IldyUDIN_DiCwZg5nEQ,956
+PythonMetaTrader5/adapters/__init__.py,sha256=SfTHYRiDD8Qyi9zAtjh1WQJbT2XKL9C58zDM7P-RU0c,67
+PythonMetaTrader5/adapters/mt5_mapping.py,sha256=YYQO_pFSbavKpeir2zGbZyYmMcp_tqssJa0la_VaB2Y,3089
+PythonMetaTrader5/adapters/mt5_session.py,sha256=hoXlaKMdM1INqOE8Cc4bo3S8vvWNivXq_d1jgA0v9YE,1837
+PythonMetaTrader5/adapters/mt5_terminal.py,sha256=OlpWUIR8wYAb7slKcCulni3JiwsQB8574FcOq6oQPpw,9476
+PythonMetaTrader5/adapters/system_clock.py,sha256=h5dDN-xHNREghu0pCfbO5wM7BvawZQ9YDDAm36KpTkM,188
+PythonMetaTrader5/application/__init__.py,sha256=sAbMrgqvIrwVA1TMdDfkVyh3dO9matXRVTiihb91ns4,64
+PythonMetaTrader5/application/batch.py,sha256=krKHiBXU49aaBGmtC82O8L2oNKjUny5hqdC8YNBPR1o,1940
+PythonMetaTrader5/application/entries.py,sha256=8uL4rI7h4iZjEh4nGVpi5UJQBL2Z7pdpXKN7cNKjWuQ,6025
+PythonMetaTrader5/application/execution.py,sha256=uCJlMnvJKCteAvFw8mLBgndoYU_oooBn91VTpWS2P_Y,4208
+PythonMetaTrader5/application/magic_scope.py,sha256=zxUyY_8z-96SCwr3lu-W8AdVqoG_Ug17TQHabnJdwOQ,2429
+PythonMetaTrader5/application/ports.py,sha256=yeJrWLbdh1ncdYxn8c9cNGMdwppReTrigCPPc8OIKoA,2642
+PythonMetaTrader5/application/trader.py,sha256=Ahw1WEleyYGs3V0b59pmBLdf878pHiSJ31r7dyN0PFM,10203
+PythonMetaTrader5/domain/__init__.py,sha256=ZZ7iypJWkoG-nK2y_Dj0CG4IRZETi7IGJ90jY06cak8,57
+PythonMetaTrader5/domain/amounts.py,sha256=ab_shtLiqn1I__9R7LtG_Vrz2hjrKwFqUZ1JE5F4tTo,1475
+PythonMetaTrader5/domain/errors.py,sha256=Or7wDSlBO6Yo6miQiQOnXsInUXR67aMRhLhtZXKSVz8,2013
+PythonMetaTrader5/domain/inputs.py,sha256=g_Z3s3e0H-VlKqNvvBTnXdavkVcKXt9kzE-PYryfcB0,4075
+PythonMetaTrader5/domain/market.py,sha256=rBMc17-Uki3boAvPcDZNNPbYRtFxVFWGrGxoPZaBYrE,2051
+PythonMetaTrader5/domain/orders.py,sha256=QA_AlOENgEZSD0ssP0WYJeJRdOC4zZ4z8-xtyRr0RTI,2399
+PythonMetaTrader5/domain/requests.py,sha256=WngSUCpcSlQGBn8a7pMBV-TKVwNtFFqzRQNMuWZ-F9A,857
+PythonMetaTrader5/domain/retcodes.py,sha256=Zstjn2Z-fbl4LZY7EacvSnYnxKJLxj5tzKoNF2YXDTI,3825
+PythonMetaTrader5/domain/stops.py,sha256=G-eKU1z_LiKTugkfuPbMfoyUpCww1NhB7GqrNDKjTKU,3325
+PythonMetaTrader5/domain/symbol.py,sha256=UnNJETCa7JXXqZrEWXVk07AxSBpOPsptV-aKtbPlJH8,7039
+PythonMetaTrader5/legacy/__init__.py,sha256=g-HN0OW4CQ2xmYPdzjsIKoFJlZQquypd_wbairdEWiw,72
+PythonMetaTrader5/legacy/arguments.py,sha256=bkklwl-9e6-JSY3bdPztwaElLXz8ro0qLieVkqozlbI,1802
+PythonMetaTrader5/legacy/broker.py,sha256=qQC9gCsNQqjpH-AvX6PG6uVxU8Sm5bnziyDChoG_1sg,11168
+PythonMetaTrader5/legacy/mt5_namespace.py,sha256=z-Woo4SnWu7ACk4j9zZ62h5K41cwhAae4ZAwtl4PKRQ,2411
+PythonMetaTrader5/legacy/views.py,sha256=O_vDxru28cIn6j0kqNJerDcyVbRY4oLEnTtSAlA1H08,3260
+pythonmetatrader5-3.0.0.dist-info/licenses/LICENSE,sha256=XDOg33_Bini4gyXwSu3XzYs5Gf3Han6tAojB-dZD5DQ,659
+pythonmetatrader5-3.0.0.dist-info/METADATA,sha256=IUDIfEZPg2tx9fyBQLvdUL1hch2pMAxicnQ1M4U978Y,11658
+pythonmetatrader5-3.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pythonmetatrader5-3.0.0.dist-info/top_level.txt,sha256=r8xFh3BXAc7RVgR1j6wCYfyk_mm_DaDoGUYFk2IqBLE,18
+pythonmetatrader5-3.0.0.dist-info/RECORD,,

{pythonmetatrader5-2.2.dist-info → pythonmetatrader5-3.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pythonmetatrader5-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,16 @@
+PythonMetaTrader5
+Copyright (c) Wiktor Jelen
+
+This work is licensed under the Creative Commons Attribution-NonCommercial 4.0
+International License (CC BY-NC 4.0).
+
+You are free to share and adapt this work for non-commercial purposes, provided
+you give appropriate credit, link to the license, and indicate if changes were
+made.
+
+Full legal code: https://creativecommons.org/licenses/by-nc/4.0/legalcode
+Summary:         https://creativecommons.org/licenses/by-nc/4.0/
+
+THE WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. TRADING FINANCIAL
+INSTRUMENTS CARRIES RISK; THE AUTHORS ARE NOT LIABLE FOR ANY LOSSES INCURRED
+THROUGH THE USE OF THIS SOFTWARE.

pythonmetatrader5-2.2.dist-info/METADATA

@@ -1,29 +0,0 @@
-Metadata-Version: 2.4
-Name: PythonMetaTrader5
-Version: 2.2
-Summary: Connect MT5 with Python
-Author-email: Wiktor Jelen <wiktorjn@gmail.com>
-License: CC BY-NC 4.0
-Project-URL: Homepage, https://github.com/Akinzou/MetaTrader5-Python
-Project-URL: Bug Tracker, https://github.com/Akinzou/MetaTrader5-Python/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.6
-Description-Content-Type: text/markdown
-Requires-Dist: MetaTrader5
-Requires-Dist: loguru
-Requires-Dist: pyautogui
-
-# PythonMetaTrader5  [![PyPI Publish](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/python-publish.yml)  ![PyPI](https://img.shields.io/pypi/v/pythonmetatrader5)  ![Python](https://img.shields.io/badge/python-3.6%2B-blue?logo=python&logoColor=white)  ![License](https://img.shields.io/badge/license-CC_BY--NC_4.0-lightgrey.svg)  [![PyPI Downloads](https://static.pepy.tech/badge/pythonmetatrader5)](https://pepy.tech/projects/pythonmetatrader5)
-
-[![Discord](https://img.shields.io/badge/Join_us_on-Discord-5865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/BARYa55KS8)
-
-
-MetaTrader 5
-This Python library enables you to connect with the MetaTrader 5 trading platform and interact with its features using Python. It allows executing trading operations, fetching market data, receiving notifications, and more.
-
-Soon -> huge update
-
-
-

pythonmetatrader5-2.2.dist-info/RECORD

@@ -1,5 +0,0 @@
-PythonMetaTrader5/__init__.py,sha256=FQYk4BheVnCjEDqIKFw_i5bR6tTOquydzNtxbKkO9F8,21318
-pythonmetatrader5-2.2.dist-info/METADATA,sha256=f38h338TRs8_BgUkKsR-CGp3lm0ab8vICuxV8ZZaGmU,1565
-pythonmetatrader5-2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pythonmetatrader5-2.2.dist-info/top_level.txt,sha256=r8xFh3BXAc7RVgR1j6wCYfyk_mm_DaDoGUYFk2IqBLE,18
-pythonmetatrader5-2.2.dist-info/RECORD,,