Changelog¶
All notable changes to this project are documented here. The format follows Keep a Changelog and the project uses Semantic Versioning.
[Unreleased]¶
Added¶
- A "Code Coverage" badge next to the title of the README and of the docs site's home page, measured by the tests on master and linked to the full line-by-line report, which also has a "Coverage report" tab on the site (ADR 0015). Coverage is 100% of lines and branches, release scripts included, and CI now requires 100%.
[3.0.2] - 2026-11-11¶
Documentation only: the library code behaves exactly as in 3.0.1.
Added¶
- Documentation site at https://akinzou.github.io/MetaTrader5-Python/: the
README as the user guide, an API reference generated from the source, the
architecture overview, every ADR, the migration guide and this changelog
(ADR 0013). Built with
mkdocs build --stricton every pull request and deployed from master.pip install -e ".[docs]"installs the toolchain. - Docstrings on every public name and method, and on each
ErrorKindmember saying what it means. A test fails when a public name has no reference entry or no docstring. - Diagrams: retries and magic-number scope in the README and user guide; layers, ports, the request flow and concurrency in the architecture page (ADR 0014). The site pins one Mermaid release with an integrity hash, and CI renders every diagram with it. On PyPI, where Mermaid does not render, each one is replaced at publish with a link to the same diagram in that release's README on GitHub.
- The README links the documentation site right after the description.
Changed¶
- The publish workflow refuses a release until the documentation site has been deployed from the tagged commit, so the site PyPI links to already describes the release.
[3.0.1] - 2026-11-09¶
Fixed¶
- A defaulted
close_positions()/cancel_pending_orders()that matched nothing dropped a failure of its follow-up check for items with other magics left open, soOk([])could read as "flat" in silence on a netting account. It now logs a warning that it could not check.
Changed¶
- README: a table of contents, an index of every ADR, and the essentials in one place: connecting, magic-number scope (symbol, ticket, magic 0 on a single-bot account, netting), error kinds with what to do, batch failures, and a checklist before trading real money. The README may have up to 600 lines; every other file keeps the 300-line limit. Links to other documents are absolute GitHub URLs, so they also work on PyPI.
- The README published to PyPI links the documents of its own release: the
publish workflow pins
blob/masterandtree/masterlinks to the tagv<version>. It runs only from that tag, only if the tag is on master with a green CI run, and fails if a file or folder link names another ref (ADR 0012). The README in git keeps linking master. The upload no longer skips versions already on PyPI, so a re-run fails instead of passing empty.
[3.0.0] - 2026-11-09¶
Complete rewrite. See MIGRATION.md for every behaviour change.
Added¶
connect()and theTraderAPI returningResult(Ok/Err) values.- Typed errors (
TradeError,ErrorKind) andBatchFailurefor close-all / cancel-all with per-ticket outcomes. Stop.points()/Stop.at_price()for SL/TP; plain floats are prices.Stop.parse(value, StopKind)returnsOk(stop)/Err(INVALID_STOPS)for values that may be bad at runtime; the constructors raiseValueError, and akindthat is not aStopKindraisesTypeError.- Magic-number support for entries and as a filter for close/cancel/queries.
close_positions()/cancel_pending_orders()default to the trader's own magic;ANY_MAGICacts on the whole account; aticketis closed whatever its magic (ADR 0011).Broker.Close/CancelOrderskeep acting on every magic, as in 2.x.connect(magic=...)must be an integer from 0 to 2**64-1; a magic-0 trader logs a warning when a close/cancel affects magic-0 (manual) trades. - Volume validation against the symbol's min/max/step.
- Filling mode chosen from the symbol's allowed modes.
- Hidden symbols are selected into Market Watch automatically.
py.typed: the package ships type information.- CI: ruff, mypy --strict, tests on Python 3.10-3.14, a Windows job against the
real
MetaTrader5package, Semgrep, a 300-line file limit, build checks. - Integration tests against a demo account.
- Contract tests comparing the unit-test fakes with the real
MetaTrader5package (run by the Windows CI job). - Thread safety: every terminal call holds one process-wide lock.
Changed¶
Brokeris a deprecated facade overTraderwith the 2.x method names. It returnsLegacyPosition/LegacyReceiptnamed tuples with the fields and field order of MT5'sTradePosition/OrderSendResult.- The
MetaTrader5namespace is still re-exported forimport *and attribute access, but lazily, and each re-exported call holds the session lock (a sequence of calls is not atomic; ADR 0010).Ticknow means the library's quote model, and importing the library no longer importsMetaTrader5. Positioncarries everyTradePositionfield (swap,identifier, ...);TradeReceiptgainsretcode_external.- Bounded retries (requotes only) instead of endless loops.
- Prices snap to the symbol's tick size instead of rounding to
digits. - Logging moved from
loguruto the standardloggingmodule. - Minimum Python version is 3.10.
- License metadata is CC-BY-NC-4.0 (the MIT classifier was wrong).
Removed¶
pyautoguiCtrl+E hotkey on retcode 10027.- The
import *re-exports oftime, loguru'sloggerandpyautogui. - The
Broker.passwordattribute.
Safety¶
- An empty symbol (
"") is rejected instead of meaning "every symbol". order_sendfailures that may have reached the server are reported asOUTCOME_UNKNOWN, never as a plain terminal error.- Market deals (entries and closes) succeed only on DONE: a partial fill is a
PARTIAL_FILLerror, a queued (PLACED) one isOUTCOME_UNKNOWN; neither is re-sent. - Logins that would be coerced (
True,12345678.9, non-ASCII digits) are rejected, inconnect()and inBroker. - Every failed login shuts the terminal session down, and
Brokerrefuses to trade until a login succeeds. sl=0/tp=0, stops that resolve to zero or below, tickets that are not positive integers,volume=Trueand non-finite numbers are rejected before sending.- Entries on a symbol whose data cannot price an order (no usable tick size
or point, a NaN tick size, negative digits, volume step 0, ...) return
BROKEN_SYMBOL_DATAinstead of sending NaN prices or stops on the entry price. Points stops additionally need a usablepoint. NaN or infinite quotes areNO_PRICE. Closing still works on such symbols. positions(symbol, ticket=...)applies both filters (MT5 drops the symbol once a ticket is given).- Pending orders on exchange-execution symbols use RETURN filling.
Broker.Close(None)/Broker.CancelOrders(None)act on nothing.
Fixed¶
Close(ticket=...)withsymbol=Nonecrashed.CancelOrdersandClosecould loop forever.- Limit orders confirmed with
PLACED(10008) were re-sent. len(None)crash when the terminal returned no positions.- Comments of 30 or more UTF-16 units (most emoji count as 2), which the
MetaTrader5package refuses although its docs allow 31, and comments that are notstr, are refused locally asINVALID_ARGUMENT.
[2.3.2]¶
Last release of the 2.x line.