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