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
31 changes: 31 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ jobs:
# out of the navigation fails. Linux on purpose: it proves the reference
# never imports the Windows-only MetaTrader5 package.
name: documentation site (mkdocs --strict)
needs: coverage
runs-on: ubuntu-latest
steps:
# Actions are pinned to commit SHAs: a moved tag cannot inject code into CI.
Expand All @@ -37,11 +38,41 @@ jobs:
- run: mkdocs build --strict
env:
NO_MKDOCS_2_WARNING: "1"
# Only the coverage job's output joins the site: the tests and the dev
# tools never run on the machine that uploads it (ADR 0015).
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
with:
name: coverage
path: site
- if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
with:
path: site

coverage:
# The number the README badge shows, measured here and published with the
# site (ADR 0015): the HTML report under /coverage/ and the badge's data
# in coverage.json. A job of its own: the tests and the dev tools must not
# share a machine with the site artifact.
name: coverage report
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 -m pip install -e ".[dev]"
- run: pytest --cov --cov-report=json --cov-report=html:report/coverage
- run: python scripts/coverage_badge.py coverage.json report/coverage.json
- uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
with:
name: coverage
path: report
if-no-files-found: error
retention-days: 1

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
Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ __pycache__/
.pytest_cache/
.coverage
coverage.xml
coverage.json
htmlcov/

# Documentation build output (mkdocs build)
Expand Down
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@ All notable changes to this project are documented here. The format follows

## [Unreleased]

### Added
- A coverage badge in the README, measured by the tests on master and linked
to the full line-by-line report on the documentation 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.
Expand Down
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

[![CI](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml/badge.svg)](https://github.com/Akinzou/MetaTrader5-Python/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-online-blue?logo=materialformkdocs&logoColor=white)](https://akinzou.github.io/MetaTrader5-Python/)
[![Coverage](https://img.shields.io/endpoint?url=https://akinzou.github.io/MetaTrader5-Python/coverage.json)](https://akinzou.github.io/MetaTrader5-Python/coverage/)
[![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)
Expand Down Expand Up @@ -471,6 +472,7 @@ to MetaTrader 5. Details: [docs/architecture.md](https://github.com/Akinzou/Meta
| [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 |
| [0015](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0015-measured-coverage-badge.md) | A coverage badge measured on master, with the full report |

## Development

Expand All @@ -479,10 +481,13 @@ 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
pytest --cov # 100% line and branch coverage required
python scripts/check_file_length.py
```

Coverage of the latest master, line by line:
<https://akinzou.github.io/MetaTrader5-Python/coverage/> (ADR 0015).

The documentation site (ADR 0013) includes this README as its user guide:

```bash
Expand Down
52 changes: 52 additions & 0 deletions docs/adr/0015-measured-coverage-badge.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
# ADR 0015: A coverage badge measured on master, with the full report

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

## Context

Tests cover 100% of the lines and branches of the library and of the release
scripts in `scripts/`. The owner wants the README to show it. A coverage
number is only worth showing if a reader can trust that it is current, and
check it.

## Decision

- **The docs workflow measures it.** On every run, a `coverage` job in
`docs.yml` runs the tests with coverage. Its output is all that joins the
site; the tests and dev tools never run on the machine that uploads it. It
publishes two files:
- the HTML report at <https://akinzou.github.io/MetaTrader5-Python/coverage/>;
- `coverage.json`, written by `scripts/coverage_badge.py` in the shields.io
endpoint format.

The README badge reads that file and links to the report.
- **The number is coverage.py's own.** The badge shows coverage.py's display
value, which never rounds 99.9 up to 100. A report without totals fails the
step rather than publish a badge.
- **CI requires 100%** (`fail_under = 100`). A drop fails the pull request, and
on master it also stops the deploy, so the badge never shows a number that
the gate let slip.
- **`scripts/` is measured too.** The scripts decide what reaches PyPI (link
pinning, diagram replacement). Only `if __name__ == "__main__":` lines are
excluded, together with the existing `TYPE_CHECKING` and
impossible-state lines.

We chose a self-hosted badge over Codecov or Coveralls. Those need an account,
a token in the repository's secrets, and the source sent to a third party,
for the same badge. They would add history graphs, which this project does
not need.

We chose a measured badge over a static shields.io badge with the number typed
in, because the typed number goes stale at the first change and nothing would
notice.

## Consequences

- The badge shows master, like the CI badge, also on the README of older
releases on PyPI.
- 100% is a gate, not a target to game. A state the types rule out is written
so that it has no branch of its own and fails loudly at runtime, rather than
excluded or skipped quietly.
- The docs workflow runs the tests once more than CI does, which adds about
half a minute. We kept that over sharing CI's report across workflows,
because that would couple the deploy to another workflow's artifacts.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -144,5 +144,6 @@ nav:
- adr/0012-pin-readme-links-at-publish.md
- adr/0013-documentation-site.md
- adr/0014-mermaid-diagrams.md
- adr/0015-measured-coverage-badge.md
- Migrating from 2.x: MIGRATION.md
- Changelog: CHANGELOG.md
9 changes: 6 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -69,13 +69,16 @@ pythonpath = ["scripts"]
markers = ["integration: needs a running MetaTrader 5 terminal and MT5_* credentials"]

[tool.coverage.run]
source = ["PythonMetaTrader5"]
# scripts/ too: they gate every release (link pinning, diagram replacement).
source = ["PythonMetaTrader5", "scripts"]
branch = true

[tool.coverage.report]
fail_under = 95
# 100: the README shows the measured coverage, so CI keeps it from slipping
# unnoticed (ADR 0015).
fail_under = 100
show_missing = true
exclude_also = ["if TYPE_CHECKING:", "raise AssertionError"]
exclude_also = ["if TYPE_CHECKING:", "raise AssertionError", "if __name__ == .__main__.:"]

[tool.ruff]
line-length = 100
Expand Down
45 changes: 45 additions & 0 deletions scripts/coverage_badge.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
"""Turn coverage.py's JSON report into a shields.io endpoint badge (ADR 0015).

The docs workflow runs the tests on master, writes this next to the site and
the HTML report, and the README badge reads it: the number on the badge is the
number of the last run on master, never one typed in by hand.
"""

from __future__ import annotations

import json
import sys
from pathlib import Path

# Lowest total for each colour, highest first.
COLOURS = ((100.0, "brightgreen"), (95.0, "green"), (90.0, "yellow"), (80.0, "orange"))


def colour(percent: float) -> str:
return next((name for floor, name in COLOURS if percent >= floor), "red")


def main(argv: list[str]) -> int:
if len(argv) != 2: # noqa: PLR2004
print("usage: coverage_badge.py <coverage.json> <badge.json>")
return 1
source, target = Path(argv[0]), Path(argv[1])
report = json.loads(source.read_text(encoding="utf-8"))
totals = report.get("totals") if isinstance(report, dict) else None
if not totals:
print(f"{source}: no totals; refusing to publish a badge without a measurement")
return 1
# coverage.py's own display rounding: it never shows 100 for 99.9.
badge = {
"schemaVersion": 1,
"label": "coverage",
"message": f"{totals['percent_covered_display']}%",
"color": colour(totals["percent_covered"]),
}
target.write_text(json.dumps(badge), encoding="utf-8")
print(f"{target}: coverage {badge['message']}")
return 0


if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
13 changes: 8 additions & 5 deletions src/PythonMetaTrader5/application/batch.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,14 @@ def run_batch(
succeeded: list[TradeReceipt] = []
errors: list[TradeError] = []
for item in items:
match action(item):
case Ok(receipt):
succeeded.append(receipt)
case Err(error):
errors.append(replace(error, ticket=item.ticket))
# isinstance, not a match without a fallback: an action that broke the
# Result contract fails loudly on `.value` instead of being skipped,
# which would end in Ok([]), read as "all closed".
result = action(item)
if isinstance(result, Err):
errors.append(replace(result.error, ticket=item.ticket))
else:
succeeded.append(result.value)
if errors:
return Err(BatchFailure(tuple(succeeded), tuple(errors)))
return Ok(succeeded)
Expand Down
84 changes: 84 additions & 0 deletions tests/unit/test_check_diagrams_main.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
"""check_diagrams.main: each way a run ends, without starting a browser."""

from __future__ import annotations

import subprocess
from pathlib import Path

import check_diagrams as check
import pytest

URL = "https://unpkg.com/mermaid@11.17.2/dist/mermaid.min.js"
TAG = f'<script src="{URL}" integrity="sha384-abc" crossorigin="anonymous"></script>'
FLOW = "```mermaid\nflowchart LR\n a --> b\n```\n"


@pytest.fixture
def site(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
for name in ("README.md", "CHANGELOG.md", "MIGRATION.md"):
(tmp_path / name).write_text(FLOW if name == "README.md" else "", encoding="utf-8")
(tmp_path / "docs").mkdir()
(tmp_path / "overrides").mkdir()
(tmp_path / "overrides" / "main.html").write_text(TAG, encoding="utf-8")
monkeypatch.chdir(tmp_path)
monkeypatch.setenv("DIAGRAM_BROWSER", "browser")
return tmp_path


def browser_returns(monkeypatch: pytest.MonkeyPatch, stdout: str, stderr: str = "") -> None:
def fake(executable: str, content: str) -> subprocess.CompletedProcess[str]:
assert 'integrity="sha384-abc"' in content
return subprocess.CompletedProcess([executable], 0, stdout, stderr)

monkeypatch.setattr(check, "render", fake)


def test_every_diagram_parsing_passes(
site: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
browser_returns(monkeypatch, '<pre id="out">["OK README.md#1"]</pre>')
assert check.main([]) == 0
assert "all 1 Mermaid diagrams parse" in capsys.readouterr().out


def test_a_page_without_verdicts_reports_the_browser_output(
site: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
browser_returns(monkeypatch, '<pre id="out">pending</pre>', stderr="sandbox failed")
assert check.main([]) == 1
assert "browser exit 0: sandbox failed" in capsys.readouterr().out


def test_a_site_without_a_pinned_mermaid_fails(
site: Path, capsys: pytest.CaptureFixture[str]
) -> None:
(site / "overrides" / "main.html").write_text("<script src='x.js'></script>", encoding="utf-8")
assert check.main([]) == 1
assert "no pinned Mermaid" in capsys.readouterr().out


def test_an_unextractable_fence_fails_before_any_browser_runs(
site: Path, capsys: pytest.CaptureFixture[str]
) -> None:
(site / "README.md").write_text("~~~mermaid\nflowchart LR\n a --> b\n~~~\n", encoding="utf-8")
assert check.main([]) == 1
assert "form not checked" in capsys.readouterr().out


def test_no_browser_found_fails(
site: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
) -> None:
monkeypatch.delenv("DIAGRAM_BROWSER")
monkeypatch.setattr(check.shutil, "which", lambda name: None)
monkeypatch.setattr(check, "EDGE", site / "no-edge.exe")
assert check.main([]) == 1
assert "set DIAGRAM_BROWSER" in capsys.readouterr().out


def test_edge_is_the_fallback_on_windows(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
edge = tmp_path / "msedge.exe"
edge.write_text("", encoding="utf-8")
monkeypatch.delenv("DIAGRAM_BROWSER", raising=False)
monkeypatch.setattr(check.shutil, "which", lambda name: None)
monkeypatch.setattr(check, "EDGE", edge)
assert check.browser() == str(edge)
16 changes: 16 additions & 0 deletions tests/unit/test_check_file_length.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

from __future__ import annotations

import subprocess
from pathlib import Path

import check_file_length as script
Expand Down Expand Up @@ -41,3 +42,18 @@ def test_only_the_top_level_readme_is_exempt(
) -> None:
code = run_on(tmp_path, monkeypatch, "docs/README.md", 301)
assert code == 1


def test_binary_files_are_not_counted(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
assert run_on(tmp_path, monkeypatch, "docs/assets/logo.png", 5000) == 0


def test_the_files_checked_are_the_ones_git_tracks(monkeypatch: pytest.MonkeyPatch) -> None:
# git itself is faked: the test must pass outside a checkout too.
def ls_files(command: list[str], **kwargs: object) -> subprocess.CompletedProcess[str]:
assert command == ["git", "ls-files"]
listing = "\n".join(["README.md", "docs/a.md", "", ""])
return subprocess.CompletedProcess(command, 0, listing, "")

monkeypatch.setattr(script.subprocess, "run", ls_files)
assert script.tracked_files() == [Path("README.md"), Path("docs/a.md")]
Loading
Loading