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
33 changes: 31 additions & 2 deletions .github/workflows/python-publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ on:

permissions:
contents: read
actions: read
deployments: write

jobs:
Expand All @@ -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
Expand All @@ -30,14 +54,19 @@ jobs:
- name: Clean previous builds
run: rm -rf dist build *.egg-info

# 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
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/*
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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<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

Expand Down
10 changes: 8 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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) ·
Expand Down Expand Up @@ -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

Expand All @@ -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<version>`: 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
Expand Down
50 changes: 50 additions & 0 deletions docs/adr/0012-pin-readme-links-at-publish.md
Original file line number Diff line number Diff line change
@@ -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<version>`, taking `version` from the
`[project]` table of pyproject.toml.
- It refuses to run unless the workflow was dispatched from `refs/tags/v<version>`
(`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.
6 changes: 4 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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"]
87 changes: 87 additions & 0 deletions scripts/pin_readme_links.py
Original file line number Diff line number Diff line change
@@ -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 `<tag>.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:]))
Loading
Loading