Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,8 @@ jobs:
with:
python-version: "3.12"
- run: python scripts/check_file_length.py
# As the publish workflow does, so twine checks the README PyPI will get.
- run: python scripts/replace_readme_diagrams.py
- run: python -m pip install build twine
- run: python -m build
- run: twine check --strict dist/*
31 changes: 27 additions & 4 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,16 +37,39 @@ jobs:
- run: mkdocs build --strict
env:
NO_MKDOCS_2_WARNING: "1"
- if: github.event_name != 'pull_request'
- if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site

diagrams:
# The browser renders Mermaid, so the build cannot see a broken diagram;
# this parses each one in the runner's Chrome against the Mermaid release
# mkdocs.yml pins for the site (ADR 0014). A job of its own:
# the page runs a third-party script, which must not share a machine with
# the site artifact.
name: Mermaid diagrams parse
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
with:
python-version: "3.12"
- run: python scripts/check_diagrams.py

deploy:
name: publish to GitHub Pages
needs: build
# A pull request or a manual run from a branch must not replace the site.
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
# Waits for the diagrams too: a broken one must not reach the site, even
# through a merge that skipped the pull request checks. An unpkg.com
# outage then holds the deploy back loudly; re-run it when unpkg is up.
needs: [build, diagrams]
# Only a push to master or a manual run from it replaces the site; a pull
# request or a branch never does.
if: >-
github.ref == 'refs/heads/master' &&
(github.event_name == 'push' || github.event_name == 'workflow_dispatch')
# One deployment at a time, and a running one is never cancelled half-way.
concurrency:
group: pages
Expand Down
23 changes: 23 additions & 0 deletions .github/workflows/python-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,23 @@ jobs:
exit 1
}

# The PyPI page links the docs site, so the site shows this release
# before the package goes out (ADR 0013). The deploy job itself must have
# succeeded: a run whose deploy was skipped (a pull request, a manual run
# from the tag) still ends green and proves nothing.
- name: Require the docs site deployed from the tagged commit
env:
GH_TOKEN: ${{ github.token }}
run: |
deployed=""
for run in $(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/docs.yml/runs?head_sha=$GITHUB_SHA" --jq '.workflow_runs[].id'); do
deployed+=$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$run/jobs" --jq '.jobs[] | select(.name == "publish to GitHub Pages" and .conclusion == "success") | .id')
done
[ -n "$deployed" ] || {
echo "::error::no docs.yml deploy succeeded for $GITHUB_SHA; wait for the master run or re-run it from master"
exit 1
}

- name: Setup Python
uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
Expand All @@ -54,6 +71,12 @@ jobs:
- name: Clean previous builds
run: rm -rf dist build *.egg-info

# PyPI cannot render Mermaid: each diagram becomes a link to its section
# of the README on GitHub (ADR 0014). Before the pinning below, which
# pins those links to the tag too.
- name: Replace README diagrams with links
run: python scripts/replace_readme_diagrams.py

# Fails unless run from the tag v<version> (gh workflow run ... --ref vX.Y.Z),
# so the package and its README links come from the same release (ADR 0012).
- name: Pin README links to the release tag
Expand Down
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,10 @@ All notable changes to this project are documented here. The format follows

## [Unreleased]

## [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
Expand All @@ -15,6 +19,17 @@ All notable changes to this project are documented here. The format follows
- Docstrings on every public name and method, and on each `ErrorKind` member
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

Expand Down
31 changes: 31 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -224,6 +224,19 @@ magic **0**. Decision and reasoning:
| `close_positions(ticket=t)` | Position `t`, whatever its magic: you named it. With `magic=` too, `t` closes only if its magic matches |
| `positions()` / `pending_orders()` | Every magic by default: a read cannot close anything |

```mermaid
flowchart TD
call["close_positions() / cancel_pending_orders()"] --> ticket{"ticket= given?<br/>close_positions only"}
ticket -- "yes, no magic=" --> named(["Position ticket, whatever its magic"])
ticket -- "yes, with magic=" --> both(["Position ticket, only if its magic matches"])
ticket -- no --> magic{"magic="}
magic -- "omitted or None" --> own(["Only the trader's own magic, from connect()"])
magic -- "an integer, e.g. 7" --> seven(["Only magic 7"])
magic -- ANY_MAGIC --> every(["Every magic, manual trades included"])
own -. "own magic is 0<br/>and something matched" .-> shared["Warning: manual trades<br/>share magic 0"]
own -. "nothing matched while<br/>other magics are open" .-> left["Warning: how many<br/>were left open"]
```

A magic must be an integer from 0 to 2\*\*64-1 (MT5's ulong). `"42"`, `True`,
`1.5`, `-1` and `2**64` are refused as `INVALID_ARGUMENT` instead of matching
nothing and reporting an empty success.
Expand Down Expand Up @@ -337,6 +350,22 @@ position/order in a batch.
| refused before sending: no quote yet (`NO_PRICE`, e.g. a symbol just added to Market Watch) | waited for and rebuilt up to `RetryPolicy.attempts`, then `NO_PRICE`; nothing was sent |
| refused before sending: anything else | the matching `ErrorKind`, returned at once; nothing was sent |

```mermaid
flowchart LR
build["Build the request<br/>from a fresh quote"] --> sent{"Built<br/>and sent?"}
sent -- "refused before leaving<br/>the process" --> refused(["Err, nothing sent"])
sent -- "no quote yet" --> left{"Attempts<br/>left?"}
sent -- "lost in IPC" --> unknown(["Err OUTCOME_UNKNOWN<br/>check positions() first"])
sent -- yes --> answer{"Server<br/>answer"}
answer -- "done, or pending<br/>order placed" --> ok(["Ok(receipt)"])
answer -- "market deal<br/>partly filled" --> partial(["Err PARTIAL_FILL"])
answer -- "timeout, no connection,<br/>market deal only queued" --> unknown
answer -- other --> failed(["Err with its ErrorKind"])
answer -- "requote and alike" --> left
left -- "yes, after delay_seconds" --> build
left -- no --> exhausted(["Err NO_PRICE or<br/>RETRIES_EXHAUSTED"])
```

```python
from PythonMetaTrader5 import RetryPolicy, connect

Expand Down Expand Up @@ -441,6 +470,7 @@ to MetaTrader 5. Details: [docs/architecture.md](https://github.com/Akinzou/Meta
| [0011](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0011-close-all-defaults-to-own-magic.md) | Close-all and cancel-all default to the trader's own magic |
| [0012](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0012-pin-readme-links-at-publish.md) | Publish from the tag and pin the README's links there |
| [0013](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0013-documentation-site.md) | A documentation site built from the README and the source |
| [0014](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0014-mermaid-diagrams.md) | Diagrams as Mermaid, checked in CI and replaced on PyPI |

## Development

Expand All @@ -459,6 +489,7 @@ The documentation site (ADR 0013) includes this README as its user guide:
pip install -e ".[docs]"
mkdocs serve # preview at http://127.0.0.1:8000
mkdocs build --strict # what CI runs: broken links and anchors fail
python scripts/check_diagrams.py # every Mermaid diagram parses (needs Chrome or Edge)
```

`tests/contract` compares the unit-test fakes with the installed `MetaTrader5`
Expand Down
2 changes: 1 addition & 1 deletion docs/adr/0013-documentation-site.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# ADR 0013: A documentation site built from the README and the source

- Status: accepted (after 3.0.1, unreleased). Asked for by the package owner on 2026-11-11.
- Status: accepted (3.0.2). Asked for by the package owner on 2026-11-11.

## Context

Expand Down
72 changes: 72 additions & 0 deletions docs/adr/0014-mermaid-diagrams.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# ADR 0014: Diagrams as Mermaid, checked in CI and replaced on PyPI

- Status: accepted (3.0.2). Asked for by the package owner on 2026-11-11.

## Context

The owner asked for diagrams in the documentation and the README. The README
appears in three places: GitHub, the docs site (ADR 0013) and PyPI, where each
release keeps its README forever (ADR 0012). GitHub and Material for MkDocs
render Mermaid; PyPI does not, and would show a diagram's source.

Material renders Mermaid in the reader's browser, so `mkdocs build --strict`
never sees a diagram that fails to parse: the live page would show its source
in silence. A `;` inside a sequence diagram label did exactly that while this
record was being written. And by default Material loads whatever Mermaid 11.x
is newest, so a diagram that parsed yesterday can break without a commit.

## Decision

- **Diagrams are Mermaid fences in Markdown**, next to the text they explain:
the README (retries, magic-number scope) and `docs/architecture.md` (layers,
ports, request flow, concurrency). The site's palette themes them; there is
no image to regenerate when the code changes.
- **The site pins one Mermaid release with its integrity hash** in
`overrides/main.html` (11.17.2 from unpkg.com, Subresource Integrity as OWASP
ASVS requires for externally hosted scripts). A template, because
`extra_javascript` cannot carry an integrity attribute. Material uses an
already loaded Mermaid instead of fetching the newest 11.x, so a diagram
changes only with a commit, and a changed file on unpkg is refused.
- **`scripts/check_diagrams.py` renders every diagram** in the README, the
changelog, the migration guide and `docs/` with that same file and hash,
read from the template, in headless Chrome with its sandbox on. Rendering,
not only parsing: some errors appear only when a diagram is laid out.
`docs.yml` runs it on every pull request, in a job of its own, apart from
the site artifact, and the deploy waits for it. It judges every Mermaid fence where it starts, and
fails when one does not parse, when one is written in a form it cannot
extract (`~~~`, indented), and when Mermaid never loaded or fewer verdicts
than diagrams came back, because then nothing was checked.
- **`scripts/replace_readme_diagrams.py` swaps each diagram for a link to its
section of the README on GitHub** in the publish workflow. It runs before
the links are pinned (ADR 0012), so the link names the release tag and shows
the diagram of that release, not the site's, which follows master. It fails
on a Mermaid fence it cannot swap, and on a diagram whose match ran past its
own closing fence, rather than ship a README with source in it or text
missing. The CI hygiene job runs it before `twine check`, so the check covers
the README that PyPI receives.
- **`scripts/mermaid_fences.py` holds the one definition** of a diagram and of
a code block that both scripts use, so CI cannot pass a README the publish
then refuses.

We chose Mermaid over committed SVG or PNG files because an image drifts from
the code it shows, and the regeneration step would need its own check. The
cost is a browser in CI.

We chose a pinned URL over a copy of Mermaid in the repository because it pins
the version without a vendored file of about 3 MB. The cost: readers' browsers
still fetch it from unpkg.com.

We chose replacing the diagrams for PyPI over leaving the source there because
a release's README cannot be fixed once it is on PyPI.

## Consequences

- Moving to a newer Mermaid means a new URL and hash in the template, checked
like any other pull request: a wrong hash fails the diagram check.
- The diagram check depends on unpkg.com being reachable from CI. When it is
not, the check fails rather than passing unchecked, and the deploy, which
waits for it, does not run: a docs fix waits until unpkg is back and the
run is repeated. We chose that over deploying unchecked diagrams, because
merges can skip the pull request checks (`--admin`).
- On PyPI each diagram is a one-line link to the same diagram in that
release's README on GitHub.
94 changes: 89 additions & 5 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,17 @@

Clean Architecture with Ports & Adapters. Dependencies point inwards only:

```
legacy/ (Broker facade) ─┐
connection.py (connect) ─┼─► application/ ─► domain/ ─► result.py
adapters/ ───────────────┘ ▲
(implement the ports) ─────────┘
```mermaid
flowchart LR
connect["connect()"] --> trader
broker["Broker<br/>2.x facade"] --> trader
trader["application/<br/>Trader · execute()"] --> domain["domain/<br/>trading rules"]
domain --> result["result.py<br/>Ok · Err"]
trader --> ports{{"Ports<br/>Terminal · Clock"}}
adapters["adapters/<br/>MetaTrader5Terminal<br/>SystemClock"] -. implement .-> ports
adapters --> mt5[("terminal64.exe")]
connect -. wires .-> adapters
broker -. "default<br/>adapters" .-> adapters
```

| Layer | Package | Knows about | I/O |
Expand All @@ -25,6 +31,29 @@ There are exactly two, one per process boundary
- `Terminal`: the MetaTrader 5 terminal (IPC to `terminal64.exe`).
- `Clock`: waiting between retries.

```mermaid
classDiagram
direction LR
class Terminal {
<<Protocol>>
connect(credentials) Result
shutdown()
symbol(name) Result~SymbolSpec~
tick(name) Result~Tick~
send(request) Result~TradeReceipt~
positions(symbol, ticket) Result
pending_orders(symbol) Result
}
class Clock {
<<Protocol>>
sleep(seconds)
}
Terminal <|.. MetaTrader5Terminal : production
Terminal <|.. FakeTerminal : unit tests
Clock <|.. SystemClock : production
Clock <|.. FakeClock : unit tests
```

Pure logic (price normalisation, stop resolution, retcode classification,
volume checks) is plain functions and methods on domain objects, not ports.

Expand All @@ -40,6 +69,44 @@ volume checks) is plain functions and methods on domain objects, not ports.
([ADR 0003](adr/0003-bounded-retries.md)): success → `Ok`; retryable →
sleep and rebuild with a fresh quote; anything else → `Err` with the receipt.

```mermaid
sequenceDiagram
autonumber
actor Bot
participant T as Trader
participant D as Domain rules
participant P as Terminal port
participant S as Trade server
participant C as Clock port
Bot->>T: open_position(...)
T->>D: check the caller's values
T->>P: symbol(name)
T->>D: check volume and price levels against the spec
alt refused
T-->>Bot: Err, nothing sent
else accepted
loop at most RetryPolicy.attempts
T->>P: tick(name)
T->>D: build the request, point stops from this quote
alt request built
T->>P: send(request)
P->>S: order_send
S-->>P: retcode
P-->>T: TradeReceipt
T->>D: classify(retcode)
else no quote yet
Note over T,D: nothing sent, retried below
else other refusal while building
T-->>Bot: Err, nothing sent
end
opt retryable answer, or no quote yet
T->>C: sleep(delay_seconds)
end
end
T-->>Bot: Ok(receipt) or Err(TradeError)
end
```

## Concurrency

`last_error()` in the `MetaTrader5` package is process-global, so the adapter
Expand All @@ -48,6 +115,23 @@ explains it ([ADR 0009](adr/0009-one-lock-per-process.md)). The lock and the
single `MetaTrader5` import live in `adapters/mt5_session.py`, shared with the
lazy 2.x namespace re-export ([ADR 0010](adr/0010-keep-the-metatrader5-re-export.md)).

```mermaid
sequenceDiagram
participant A as Webhook thread A
participant B as Webhook thread B
participant L as Process-wide lock
participant M as MetaTrader5 module
A->>L: acquire
B-->>L: acquire, waits
A->>M: order_send(request)
A->>M: last_error()
Note over A,M: the error read belongs to A's call
A->>L: release
L-->>B: acquired
B->>M: positions_get()
B->>L: release
```

## Errors

Expected failures travel as `Result` values
Expand Down
Loading
Loading