From 063afc7924c3b1db1d646cfd281b74e7cc044ab6 Mon Sep 17 00:00:00 2001 From: Wiktor Jelen <35398584+Akinzou@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:26:02 +0100 Subject: [PATCH] release: 3.0.1; publish from the tag with README links pinned to it PyPI keeps each release's README forever, and 3.0.0's links said blob/master, so its page drifts with master. scripts/pin_readme_links.py rewrites the README's master links to v in the publish job and refuses any other ref, a tag off master, a commit without a green ci.yml run, or a file link left on another ref (ADR 0012). Pinning at build time instead of in git, because pinned links in git would 404 for every document added after the last tag. Also: mypy covers scripts/, twine check --strict and no --skip-existing in the publish job, checkout without persisted credentials. --- .github/workflows/python-publish.yml | 33 +++- CHANGELOG.md | 8 + README.md | 10 +- docs/adr/0012-pin-readme-links-at-publish.md | 50 +++++ pyproject.toml | 6 +- scripts/pin_readme_links.py | 87 +++++++++ tests/unit/test_pin_readme_links.py | 190 +++++++++++++++++++ 7 files changed, 378 insertions(+), 6 deletions(-) create mode 100644 docs/adr/0012-pin-readme-links-at-publish.md create mode 100644 scripts/pin_readme_links.py create mode 100644 tests/unit/test_pin_readme_links.py diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index e0ac010..239ea21 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -5,6 +5,7 @@ on: permissions: contents: read + actions: read deployments: write jobs: @@ -18,6 +19,29 @@ jobs: steps: - name: Checkout uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + fetch-depth: 0 + # Nothing after checkout needs git auth; build tools run with no token. + persist-credentials: false + + # A tag can sit on any commit; release only what was merged to master. + - name: Require the tagged commit to be on master + run: | + git merge-base --is-ancestor "$GITHUB_SHA" origin/master || { + echo "::error::$GITHUB_REF is not on master; merge the release PR first" + exit 1 + } + + # Being on master is not being green: an --admin merge skips the PR checks. + - name: Require a successful CI run for the tagged commit + env: + GH_TOKEN: ${{ github.token }} + run: | + runs=$(gh api "repos/$GITHUB_REPOSITORY/actions/workflows/ci.yml/runs?head_sha=$GITHUB_SHA&status=success" --jq '.total_count') + [ "$runs" -gt 0 ] || { + echo "::error::ci.yml has no successful run for $GITHUB_SHA" + exit 1 + } - name: Setup Python uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 @@ -30,14 +54,19 @@ jobs: - name: Clean previous builds run: rm -rf dist build *.egg-info + # Fails unless run from the tag v (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 + run: python scripts/pin_readme_links.py "$GITHUB_REF" + - name: Build package run: python -m build - name: Twine check - run: twine check dist/* + run: twine check --strict dist/* - name: Publish to PyPI env: TWINE_USERNAME: __token__ TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} - run: twine upload --skip-existing dist/* + run: twine upload dist/* diff --git a/CHANGELOG.md b/CHANGELOG.md index d59c29d..e945b40 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +## [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 @@ -19,6 +21,12 @@ All notable changes to this project are documented here. The format follows 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/master` and `tree/master` links to the tag + `v`. 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 diff --git a/README.md b/README.md index 02e9716..53ba470 100644 --- a/README.md +++ b/README.md @@ -41,9 +41,10 @@ Built for bots (webhook executors, signal followers) where a trading call must - [Development](#development) - [License](#license) -Links to the other documents point to GitHub. On PyPI the Contents entries +Links to the other documents point to GitHub; on PyPI they open the files of +the release you are reading (ADR 0012). On PyPI the Contents entries above do not jump to their sections; read this page on -[GitHub](https://github.com/Akinzou/MetaTrader5-Python#contents) for that. +[GitHub](https://github.com/Akinzou/MetaTrader5-Python/blob/master/README.md#contents) for that. Other documents: [CHANGELOG.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/CHANGELOG.md) · [MIGRATION.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/MIGRATION.md) · [docs/architecture.md](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/architecture.md) · @@ -427,6 +428,7 @@ to MetaTrader 5. Details: [docs/architecture.md](https://github.com/Akinzou/Meta | [0009](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0009-one-lock-per-process.md) | One lock per process around terminal calls | | [0010](https://github.com/Akinzou/MetaTrader5-Python/blob/master/docs/adr/0010-keep-the-metatrader5-re-export.md) | Keep re-exporting the MetaTrader5 namespace, lazily | | [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 | ## Development @@ -445,6 +447,10 @@ 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`. +Releases are published from the tag `v`: the publish workflow runs +`scripts/pin_readme_links.py`, which points the README's `master` links at that +tag and refuses to run from any other ref (ADR 0012). + ## License [CC BY-NC 4.0](https://github.com/Akinzou/MetaTrader5-Python/blob/master/LICENSE). Trading carries risk; this software comes without any diff --git a/docs/adr/0012-pin-readme-links-at-publish.md b/docs/adr/0012-pin-readme-links-at-publish.md new file mode 100644 index 0000000..eb750be --- /dev/null +++ b/docs/adr/0012-pin-readme-links-at-publish.md @@ -0,0 +1,50 @@ +# ADR 0012: Publish from the tag and pin the README's links there + +- Status: accepted (3.0.1). Asked for by the package owner on 2026-11-09. + +## Context + +PyPI renders the README of each release and keeps it forever. Relative links +break there, so the README links other documents with absolute GitHub URLs. +In 3.0.0 those URLs said `blob/master`: the 3.0.0 page on PyPI shows whatever +master holds today, which may describe a later release. + +## Decision + +- The README in git keeps `blob/master` / `tree/master` links. +- `scripts/pin_readme_links.py` runs in the publish workflow before the build + and rewrites them to the tag `v`, taking `version` from the + `[project]` table of pyproject.toml. +- It refuses to run unless the workflow was dispatched from `refs/tags/v` + (`gh workflow run python-publish.yml --ref vX.Y.Z`), so the package and the + documents it links are the same tree. +- The workflow refuses a tag that is not on master, or whose commit has no + successful `ci.yml` run (an `--admin` merge skips the PR checks). +- It fails, and the release does not publish, when it finds nothing to pin or + when a `blob`, `tree`, `raw`, `blame`, `edit`, `commits`, `archive`, + `raw.githubusercontent.com` or `.git@` link to this repository names a ref + other than the tag. Other forms (`compare/...master`, `releases/latest`) + are not checked; the README has none. A bare link to the repository (the CI + badge, the home page) is not a document and stays as it is. +- The upload does not skip files already on PyPI: a re-run for a published + version fails instead of finishing green with nothing uploaded. + +Rejected: publishing on tag push. `gh release create` pushes the tag, so the +upload would stop being a separate, deliberate step; with manual dispatch a +wrong `--ref` fails loudly instead. + +Rejected: writing `blob/vX.Y.Z` into the README in git. A document added +after the last tag (the next ADR, say) would 404 from master's README until +the next release, and every release would need a sweep of the links. + +## Consequences + +- What PyPI shows for a release no longer changes after it ships. +- The README inside the sdist differs from git: only those links. +- Publishing from master now fails. The procedure: merge the release PR, + wait for the master CI run to finish green, tag the merge commit, then + dispatch the workflow with `--ref vX.Y.Z`. +- The `Changelog` URL in pyproject.toml stays on master on purpose: the PyPI + sidebar should lead to the newest CHANGELOG, which also lists every fix + released after the version a reader is looking at. +- 3.0.0 on PyPI keeps its master links; PyPI does not allow re-uploading it. diff --git a/pyproject.toml b/pyproject.toml index ff65d72..a58d701 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" [project] name = "PythonMetaTrader5" -version = "3.0.0" +version = "3.0.1" description = "Safe, typed trading layer over the official MetaTrader5 Python API" readme = "README.md" requires-python = ">=3.10" @@ -39,6 +39,7 @@ dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.6", "mypy>=1.10", "build>=1.2", "t [project.urls] Homepage = "https://github.com/Akinzou/MetaTrader5-Python" "Bug Tracker" = "https://github.com/Akinzou/MetaTrader5-Python/issues" +# master, not the release tag (ADR 0012): the newest CHANGELOG also lists later fixes. Changelog = "https://github.com/Akinzou/MetaTrader5-Python/blob/master/CHANGELOG.md" [tool.setuptools.packages.find] @@ -82,4 +83,5 @@ ignore = ["PLR0913", "N999"] strict = true python_version = "3.10" mypy_path = "src" -packages = ["PythonMetaTrader5"] +# scripts/ too: pin_readme_links.py gates every release (ADR 0012). +files = ["src/PythonMetaTrader5", "scripts"] diff --git a/scripts/pin_readme_links.py b/scripts/pin_readme_links.py new file mode 100644 index 0000000..e16e28f --- /dev/null +++ b/scripts/pin_readme_links.py @@ -0,0 +1,87 @@ +"""Pin the README's repository links to the release tag at build time (ADR 0012). + +Pinned here, not in git: master's README must keep linking documents added +after the last tag. Every refusal fails the publish, because PyPI keeps a +release's README forever and an unpinned link would go stale in silence. +""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +REPO = "https://github.com/Akinzou/MetaTrader5-Python" +# What ends a ref in a URL; `\b` would also stop at `-` and `.` and turn +# `master-old` into `v3.0.1-old`, a link that 404s and passes every check. +_END = r"(?=[/#?)\s\]>\"'`]|$)" +_REF = r"([^/#?)\s\]>\"'`]+)" +# Owner and repository ignore case on GitHub, branch names do not: `blob/Master` +# 404s in git too, and is reported below instead of repaired here. +MASTER_LINK = re.compile(f"(?i:{re.escape(REPO)})" + r"/(blob|tree)/master" + _END) +# Every way a link names a ref of this repository. Only the ref segment is +# read, so `master` in a file name or a badge's query string is no ref. +REF_LINKS = [ + re.compile(f"(?i:{p})" + _REF) + for p in ( + r"github\.com/akinzou/metatrader5-python/(?:blob|tree|raw|blame|edit|commits)/", + r"github\.com/akinzou/metatrader5-python/archive/(?:refs/(?:heads|tags)/)?", + r"raw\.githubusercontent\.com/akinzou/metatrader5-python/", + r"metatrader5-python\.git@", + ) +] +PROJECT_TABLE = re.compile(r"^\[project\]$(.*?)(?=^\[|\Z)", re.MULTILINE | re.DOTALL) +VERSION = re.compile(r'^version = "([^"]+)"$', re.MULTILINE) + + +def project_version(pyproject: Path) -> str | None: + """`version` of the [project] table; a regex because tomllib is 3.11+.""" + if not pyproject.is_file(): + return None + table = PROJECT_TABLE.search(pyproject.read_text(encoding="utf-8")) + found = VERSION.search(table.group(1)) if table else None + return found.group(1) if found else None + + +def unpinned(text: str, tag: str) -> list[str]: + """Links naming any ref but `tag`: master, main, HEAD, a branch, ...""" + # A tag archive is `.zip`; everything else names the ref alone. + return [ + m.group(0) + for p in REF_LINKS + for m in p.finditer(text) + if m.group(1) not in (tag, f"{tag}.zip", f"{tag}.tar.gz") + ] + + +def main(argv: list[str]) -> int: + version = project_version(Path("pyproject.toml")) + if version is None: + print("pyproject.toml: no `version` in the [project] table") + return 1 + tag = f"v{version}" + # The full ref, not the name: a branch called v3.0.1 must not pass for the tag. + if argv != [f"refs/tags/{tag}"]: + print(f"build from refs/tags/{tag}, not {' '.join(argv) or 'nothing'}") + return 1 + readme = Path("README.md") + # Bytes: Path.read_text has no newline= before Python 3.13, and text mode + # would turn LF into CRLF when run on Windows. + text = readme.read_bytes().decode("utf-8") + pinned, count = MASTER_LINK.subn(lambda m: f"{REPO}/{m.group(1)}/{tag}", text) + if count == 0: + # A renamed repository or a changed link style would otherwise ship + # master links to PyPI. + print("README.md: no master links to this repository to pin") + return 1 + left = unpinned(pinned, tag) + if left: + print(f"README.md links not pinned to {tag}: " + ", ".join(left)) + return 1 + readme.write_bytes(pinned.encode("utf-8")) + print(f"README.md: {count} link(s) pinned to {tag}") + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/tests/unit/test_pin_readme_links.py b/tests/unit/test_pin_readme_links.py new file mode 100644 index 0000000..44e8628 --- /dev/null +++ b/tests/unit/test_pin_readme_links.py @@ -0,0 +1,190 @@ +"""The README shipped to PyPI must link the documents of its own release.""" + +from __future__ import annotations + +import importlib.util +import shutil +from pathlib import Path +from types import ModuleType + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +REPO = "https://github.com/Akinzou/MetaTrader5-Python" +TAG = "refs/tags/v3.0.1" +PYPROJECT = '[project]\nname = "x"\nversion = "3.0.1"\n' + + +def load_script() -> ModuleType: + spec = importlib.util.spec_from_file_location("pin", ROOT / "scripts" / "pin_readme_links.py") + assert spec is not None + assert spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +pin = load_script() + + +def project( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, readme: str, pyproject: str = PYPROJECT +) -> Path: + (tmp_path / "pyproject.toml").write_text(pyproject, encoding="utf-8") + (tmp_path / "README.md").write_text(readme, encoding="utf-8") + monkeypatch.chdir(tmp_path) + return tmp_path / "README.md" + + +def test_master_file_and_folder_links_point_at_the_release_tag( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + readme = project( + tmp_path, + monkeypatch, + f"[a]({REPO}/blob/master/CHANGELOG.md) [b]({REPO}/tree/master/docs/adr)\n", + ) + + assert pin.main([TAG]) == 0 + assert readme.read_text(encoding="utf-8") == ( + f"[a]({REPO}/blob/v3.0.1/CHANGELOG.md) [b]({REPO}/tree/v3.0.1/docs/adr)\n" + ) + + +def test_links_outside_the_repository_and_the_ci_badge_stay( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + kept = ( + "[x](https://github.com/other/repo/blob/master/a.md) " + f"[ci]({REPO}/actions/workflows/ci.yml) [doc]({REPO}/blob/master/a.md)\n" + ) + readme = project(tmp_path, monkeypatch, kept) + + assert pin.main([TAG]) == 0 + assert readme.read_text(encoding="utf-8") == kept.replace( + f"{REPO}/blob/master/", f"{REPO}/blob/v3.0.1/" + ) + + +@pytest.mark.parametrize( + "written", + [f"{REPO.lower()}/blob/master/a.md", f"{REPO}/tree/master", f"{REPO}/blob/master#top"], +) +def test_case_and_a_missing_slash_are_still_pinned( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, written: str +) -> None: + readme = project(tmp_path, monkeypatch, f"[a]({written})\n") + + assert pin.main([TAG]) == 0 + assert "master" not in readme.read_text(encoding="utf-8") + + +@pytest.mark.parametrize( + "moving", + [ + "https://raw.githubusercontent.com/Akinzou/MetaTrader5-Python/master/a.png", + f"{REPO}/blob/HEAD/a.md", + f"{REPO}/tree/main/docs", + f"{REPO}/blob/master-old/a.md", + "git+https://github.com/Akinzou/MetaTrader5-Python.git@master", + f"{REPO}/raw/master/docs/img.png", + f"{REPO}/blame/master/a.md", + f"{REPO}/edit/master/a.md", + f"{REPO}/commits/master", + f"{REPO}/archive/refs/heads/master.zip", + # Branch names are case-sensitive: a link that 404s on GitHub is + # reported, not quietly repaired by the pin. + f"{REPO}/blob/Master/a.md", + ], +) +def test_a_link_to_a_moving_ref_fails_and_leaves_the_readme( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + moving: str, +) -> None: + original = f"[a]({REPO}/blob/master/CHANGELOG.md) [b]({moving})\n" + readme = project(tmp_path, monkeypatch, original) + + assert pin.main([TAG]) == 1 + assert "not pinned to v3.0.1" in capsys.readouterr().out + assert readme.read_text(encoding="utf-8") == original + + +def test_master_in_a_file_name_or_query_is_not_a_ref( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + readme = project( + tmp_path, + monkeypatch, + f"[a]({REPO}/blob/master/docs/adr/0013-master-account.md) " + f"[ci]({REPO}/actions/workflows/ci.yml/badge.svg?branch=master)\n", + ) + + assert pin.main([TAG]) == 0 + assert f"{REPO}/blob/v3.0.1/docs/adr/0013-master-account.md" in readme.read_text( + encoding="utf-8" + ) + + +@pytest.mark.parametrize("ref", ["refs/heads/master", "refs/heads/v3.0.1", "v3.0.1"]) +def test_a_ref_other_than_the_version_tag_refuses_and_leaves_the_readme( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str], ref: str +) -> None: + original = f"[a]({REPO}/blob/master/CHANGELOG.md)\n" + readme = project(tmp_path, monkeypatch, original) + + assert pin.main([ref]) == 1 + assert TAG in capsys.readouterr().out + assert readme.read_text(encoding="utf-8") == original + + +def test_nothing_to_pin_fails_instead_of_publishing_unpinned_links( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str] +) -> None: + project(tmp_path, monkeypatch, "no links here\n") + + assert pin.main([TAG]) == 1 + assert "no master links" in capsys.readouterr().out + + +def test_the_version_comes_from_the_project_table( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + pyproject = '[tool.other]\nversion = "9"\n\n[project]\nversion = "3.0.1"\n' + project(tmp_path, monkeypatch, f"[a]({REPO}/blob/master/a.md)\n", pyproject) + + assert pin.main([TAG]) == 0 + + +@pytest.mark.parametrize( + "pyproject", ['[project]\nname = "x"\n\n[tool.other]\nversion = "9"\n', None] +) +def test_no_readable_version_is_reported_not_raised( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + capsys: pytest.CaptureFixture[str], + pyproject: str | None, +) -> None: + project(tmp_path, monkeypatch, f"[a]({REPO}/blob/master/a.md)\n", pyproject or "") + if pyproject is None: + (tmp_path / "pyproject.toml").unlink() + + assert pin.main([TAG]) == 1 + assert "pyproject.toml" in capsys.readouterr().out + + +def test_the_repository_readme_pins_completely( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + shutil.copy(ROOT / "README.md", tmp_path / "README.md") + shutil.copy(ROOT / "pyproject.toml", tmp_path / "pyproject.toml") + monkeypatch.chdir(tmp_path) + version = pin.project_version(Path("pyproject.toml")) + assert version is not None + + assert pin.main([f"refs/tags/v{version}"]) == 0 + pinned = (tmp_path / "README.md").read_text(encoding="utf-8") + assert "/master" not in pinned + assert pin.unpinned(pinned, f"v{version}") == [] + assert f"{REPO}/blob/v{version}/README.md#contents" in pinned