From e54ae495c78d0d797d5a18e177d08e4cb41f9345 Mon Sep 17 00:00:00 2001 From: mrgh97 <44031031+mrgh97@users.noreply.github.com> Date: Fri, 20 Nov 2026 07:53:08 +0000 Subject: [PATCH] fix(tool): support Python 3.11 and prepare 2.0.1 release --- .github/workflows/publish-pypi.yml | 10 ++++-- CHANGELOG.md | 9 ++++++ README.md | 4 +-- README_zh.md | 4 +-- RELEASING.md | 2 +- packages/tool/README.md | 19 ++++++----- packages/tool/pyproject.toml | 4 +-- packages/tool/src/forge_tool/dora.py | 5 +-- .../tool/src/forge_tool/endpoint/models.py | 22 ++++++------- packages/tool/src/forge_tool/handler.py | 4 +-- packages/tool/src/forge_tool/wire/envelope.py | 4 +-- packages/tool/src/forge_tool/wire/messages.py | 6 ++-- .../tool/tests/test_python_compatibility.py | 19 +++++++++++ packages/tool/tests/test_wire.py | 2 +- scripts/tests/test_publish_workflow.py | 32 +++++++++++++++++++ uv.lock | 2 +- versions.toml | 2 +- 17 files changed, 110 insertions(+), 40 deletions(-) create mode 100644 packages/tool/tests/test_python_compatibility.py diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml index b90fb33..c768f30 100644 --- a/.github/workflows/publish-pypi.yml +++ b/.github/workflows/publish-pypi.yml @@ -81,6 +81,9 @@ jobs: name: Publish ${{ needs.resolve.outputs.tag }} needs: resolve runs-on: ubuntu-latest + defaults: + run: + working-directory: release-source environment: name: pypi-${{ needs.resolve.outputs.family }} permissions: @@ -91,13 +94,14 @@ jobs: uses: actions/checkout@v4 with: ref: ${{ needs.resolve.outputs.tag }} + path: release-source fetch-depth: 0 persist-credentials: false - name: Check out release tooling from the workflow commit uses: actions/checkout@v4 with: ref: ${{ github.workflow_sha }} - path: .release-tools + path: release-tools persist-credentials: false - name: Set up Python uses: actions/setup-python@v5 @@ -107,7 +111,7 @@ jobs: env: RELEASE_TAG: ${{ needs.resolve.outputs.tag }} RELEASE_LINE: ${{ needs.resolve.outputs.release_line }} - run: python .release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --default-branch master + run: python ../release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --default-branch master - name: Verify annotated tag and commit shell: bash env: @@ -142,7 +146,7 @@ jobs: uses: actions/upload-artifact@v4 with: name: ${{ needs.resolve.outputs.distribution }}-${{ needs.resolve.outputs.version }} - path: dist/release/python/${{ needs.resolve.outputs.family }}/* + path: release-source/dist/release/python/${{ needs.resolve.outputs.family }}/* if-no-files-found: error - name: Publish wheel and source distribution to PyPI shell: bash diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c252dc..5ebc19d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,15 @@ Forge package families are versioned independently. Python, Rust, and C++ implem ## Unreleased +## forge-tool 2.0.1 - 2026-11-20 + +Family tag: `forge-tool-v2.0.1` + +- Support Python 3.11 in the standalone Tool package and its optional Arrow/Dora binding; the complete Forge workspace still requires Python 3.12. +- Replace Python 3.12-only type aliases and generic-function syntax with `typing.TypeAlias` and `TypeVar`, without changing the ToolEndpoint wire protocol or execution lifecycle. Runtime type inspection now uses `typing.get_args(alias)` rather than `alias.__value__`. +- Add a Python 3.11 syntax guard to the existing test suite and validate the built wheel in a separate Python 3.11 environment. +- Keep release tooling in a sibling checkout so family builds retain the clean-source check without rejecting CI's own tooling checkout. + ## forge-msgs 2.1.0 - 2026-11-12 Family tag: `forge-msgs-v2.1.0` diff --git a/README.md b/README.md index 86b5f35..f942c14 100644 --- a/README.md +++ b/README.md @@ -35,14 +35,14 @@ packages, for example a separate `forge_robots` repository. ## Status Forge tracks six package families: Common, Msgs, Robot, Policy, Kinematics, and Tool. -Common is `2.1.0`; Msgs is `2.1.0`; Robot, Policy, Kinematics and Tool remain +Common and Msgs are `2.1.0`; Tool is `2.0.1`; Robot, Policy and Kinematics remain at the coordinated Dora 1.x `2.0.0` baseline. Families can receive independent minor and patch releases. Package versions within one family remain synchronized across languages; capabilities may differ, and language-neutral interface versions are tracked separately. The Python Msgs compressed-image codec requires Pillow `>=13.0.0,<14`. -Msgs still supports Python 3.11; the complete workspace requires Python 3.12. +Common, Msgs, and Tool support Python 3.11; the complete workspace requires Python 3.12. Consumers pinning Pillow below 13 must update their dependency constraints. Raw RGB/depth payloads and the Arrow wire schema are unchanged. diff --git a/README_zh.md b/README_zh.md index f105a77..b4f826d 100644 --- a/README_zh.md +++ b/README_zh.md @@ -25,12 +25,12 @@ Forge 是面向 Dora 数据流的机器人基础框架,提供公共消息 sche ## 版本状态 Forge 按 Common、Msgs、Robot、Policy、Kinematics、Tool 六个包家族维护。 -Common 为 `2.1.0`,Msgs 为 `2.1.0`;Robot、Policy、Kinematics、Tool 保持 Dora 1.x 对齐的 `2.0.0` 基线。 +Common 和 Msgs 为 `2.1.0`,Tool 为 `2.0.1`;Robot、Policy、Kinematics 保持 Dora 1.x 对齐的 `2.0.0` 基线。 各家族可独立发布次版本和修订版本;同一家族跨语言包版本保持一致, 实际能力允许不同,语言无关接口版本另行跟踪。 Python Msgs 的压缩图像编解码要求 Pillow `>=13.0.0,<14`。 -Msgs 继续支持 Python 3.11;完整工作区要求 Python 3.12。 +Common、Msgs 和 Tool 支持 Python 3.11;完整工作区要求 Python 3.12。 固定使用 Pillow 13 以下版本的使用方需要更新依赖约束。 原始 RGB/深度数据及 Arrow 线协议保持不变。 diff --git a/RELEASING.md b/RELEASING.md index 84e3988..6c1488f 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -13,7 +13,7 @@ msgs = "2.1.0" robot = "2.0.0" policy = "2.0.0" kinematics = "2.0.0" -tool = "2.0.0" +tool = "2.0.1" [interfaces] msgs = 1 diff --git a/packages/tool/README.md b/packages/tool/README.md index a1f0733..a6b12e3 100644 --- a/packages/tool/README.md +++ b/packages/tool/README.md @@ -34,7 +34,7 @@ handling therefore does not imply a complete caller-to-provider Action or Sessio ## Installation -Python 3.12 or newer is required. Install the current Tool release from PyPI: +Python 3.11 or newer is required. Install the current Tool release from PyPI: ```bash pip install forge-tool @@ -47,13 +47,16 @@ Dora-capable Operator or Adapter node: pip install 'forge-tool[dora]' ``` -From a Forge source checkout, run code through the repository workspace instead of -syncing the package subproject in isolation: +The complete Forge source workspace still requires Python 3.12 or newer. From a +source checkout, run code through that workspace: ```bash uv run python your_endpoint.py ``` +For Python 3.11, install the standalone Tool distribution into a separate environment; +the workspace also includes packages that require Python 3.12. + The base package has no runtime dependencies. `import forge_tool` does not import `forge_msgs` or PyArrow. The optional extra adds the carrier stack, not `dora-rs`; the concrete node package remains responsible for its Dora dependency. @@ -413,10 +416,10 @@ Explicitly import from `forge_tool.dora`: ## Protocol documentation -- [Tool documentation index](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/README.md) -- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/ARCHITECTURE.md) -- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/PROTOCOL.md) -- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v2.0.0/interfaces/forge_msgs/tool.v1.yaml) +- [Tool documentation index](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/interfaces/forge_tool/README.md) +- [Architecture](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/interfaces/forge_tool/ARCHITECTURE.md) +- [ToolEndpoint Wire protocol](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/interfaces/forge_tool/PROTOCOL.md) +- [Canonical `ToolMessage` Arrow schema](https://github.com/PhyAgentOS/forge/blob/forge-msgs-v2.1.0/interfaces/forge_msgs/tool.v1.yaml) ## Development @@ -428,4 +431,4 @@ uv run pytest packages/tool/tests ## License -Apache-2.0. See the release [LICENSE](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/LICENSE). +Apache-2.0. See the release [LICENSE](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/LICENSE). diff --git a/packages/tool/pyproject.toml b/packages/tool/pyproject.toml index f9e34bf..ab25e1c 100644 --- a/packages/tool/pyproject.toml +++ b/packages/tool/pyproject.toml @@ -1,9 +1,9 @@ [project] name = "forge-tool" -version = "2.0.0" +version = "2.0.1" description = "Typed endpoint contracts for Forge query, action, and session tools." readme = "README.md" -requires-python = ">=3.12" +requires-python = ">=3.11" license = "Apache-2.0" license-files = ["LICENSE"] authors = [ diff --git a/packages/tool/src/forge_tool/dora.py b/packages/tool/src/forge_tool/dora.py index 6060c74..503ae9c 100644 --- a/packages/tool/src/forge_tool/dora.py +++ b/packages/tool/src/forge_tool/dora.py @@ -5,6 +5,7 @@ import asyncio import logging from collections.abc import Awaitable, Callable +from typing import TypeAlias import pyarrow as pa from forge_msgs import ToolMessage, ToolMessageSizeError @@ -26,8 +27,8 @@ _MIN_BINDING_MESSAGE_BYTES = 1_024 _DEFAULT_CARRIER_OVERHEAD_BYTES = 65_536 -type _ToolArrowValue = pa.RecordBatch | pa.Table | pa.StructArray -type DoraEventSink = Callable[[pa.RecordBatch], Awaitable[None]] +_ToolArrowValue: TypeAlias = pa.RecordBatch | pa.Table | pa.StructArray +DoraEventSink: TypeAlias = Callable[[pa.RecordBatch], Awaitable[None]] def _message_envelope(message: ToolMessage) -> ToolEnvelope: diff --git a/packages/tool/src/forge_tool/endpoint/models.py b/packages/tool/src/forge_tool/endpoint/models.py index ce55fbc..30b3d72 100644 --- a/packages/tool/src/forge_tool/endpoint/models.py +++ b/packages/tool/src/forge_tool/endpoint/models.py @@ -5,12 +5,12 @@ import math from collections.abc import Mapping from dataclasses import dataclass, field -from typing import Any, Literal +from typing import Any, Literal, TypeAlias -type ToolSemantics = Literal["query", "action", "session"] -type EndpointState = Literal["ready", "busy", "degraded", "unavailable"] -type ExecutionPhase = Literal[ +ToolSemantics: TypeAlias = Literal["query", "action", "session"] +EndpointState: TypeAlias = Literal["ready", "busy", "degraded", "unavailable"] +ExecutionPhase: TypeAlias = Literal[ "accepted", "running", "stopping", @@ -20,7 +20,7 @@ "stopped", "unknown", ] -type ToolEventType = Literal[ +ToolEventType: TypeAlias = Literal[ "progress", "heartbeat", "executor_completed", @@ -28,18 +28,18 @@ "cancelled", "stopped", ] -type ToolResultStatus = Literal[ +ToolResultStatus: TypeAlias = Literal[ "succeeded", "failed", "cancelled", "stopped", "unknown", ] -type ToolResultResponseStatus = Literal["pending", "available", "not_found"] -type ToolControlCommand = Literal["cancel", "stop"] -type EndpointRegistryOperation = Literal["register", "unregister"] -type EndpointRegistryResponseStatus = Literal["accepted", "rejected"] -type ToolControlStatus = Literal[ +ToolResultResponseStatus: TypeAlias = Literal["pending", "available", "not_found"] +ToolControlCommand: TypeAlias = Literal["cancel", "stop"] +EndpointRegistryOperation: TypeAlias = Literal["register", "unregister"] +EndpointRegistryResponseStatus: TypeAlias = Literal["accepted", "rejected"] +ToolControlStatus: TypeAlias = Literal[ "accepted", "rejected", "terminal", diff --git a/packages/tool/src/forge_tool/handler.py b/packages/tool/src/forge_tool/handler.py index ad12ee7..d41c9b7 100644 --- a/packages/tool/src/forge_tool/handler.py +++ b/packages/tool/src/forge_tool/handler.py @@ -6,7 +6,7 @@ from collections import OrderedDict from collections.abc import Awaitable, Callable, Mapping from dataclasses import dataclass, field -from typing import cast +from typing import TypeAlias, cast from .endpoint import ( ActionToolEndpoint, @@ -40,7 +40,7 @@ validate_message_envelope, ) -type ToolEventSink = Callable[[ToolEnvelope], Awaitable[None]] +ToolEventSink: TypeAlias = Callable[[ToolEnvelope], Awaitable[None]] _REQUIRED_METHODS = { "query": ("query",), diff --git a/packages/tool/src/forge_tool/wire/envelope.py b/packages/tool/src/forge_tool/wire/envelope.py index 75397b4..cc1abb8 100644 --- a/packages/tool/src/forge_tool/wire/envelope.py +++ b/packages/tool/src/forge_tool/wire/envelope.py @@ -5,7 +5,7 @@ import math from collections.abc import Mapping from dataclasses import dataclass, field -from typing import Any, Literal +from typing import Any, Literal, TypeAlias from .errors import ToolProtocolError @@ -13,7 +13,7 @@ MAX_SAFE_JSON_INTEGER = 9_007_199_254_740_991 MAX_JSON_DEPTH = 64 -type ToolMessageType = Literal[ +ToolMessageType: TypeAlias = Literal[ "endpoint.register", "endpoint.unregister", "endpoint.registry.response", diff --git a/packages/tool/src/forge_tool/wire/messages.py b/packages/tool/src/forge_tool/wire/messages.py index a63f69b..bba0d9f 100644 --- a/packages/tool/src/forge_tool/wire/messages.py +++ b/packages/tool/src/forge_tool/wire/messages.py @@ -3,7 +3,7 @@ from __future__ import annotations from collections.abc import Mapping -from typing import Any, cast +from typing import Any, TypeVar, cast from ..endpoint import ( EndpointRegistryResponse, @@ -24,6 +24,8 @@ from .envelope import ToolEnvelope, _is_blank, _json_value from .errors import ToolProtocolError +_T = TypeVar("_T") + def _error(message: str, path: str) -> ToolProtocolError: return ToolProtocolError( @@ -59,7 +61,7 @@ def _fields( raise _error("; ".join(details), path) -def _construct[T](factory: type[T], path: str, **values: Any) -> T: +def _construct(factory: type[_T], path: str, **values: Any) -> _T: try: return factory(**values) except (TypeError, ValueError) as error: diff --git a/packages/tool/tests/test_python_compatibility.py b/packages/tool/tests/test_python_compatibility.py new file mode 100644 index 0000000..12b55e9 --- /dev/null +++ b/packages/tool/tests/test_python_compatibility.py @@ -0,0 +1,19 @@ +"""Keep the package's minimum Python syntax covered by the workspace CI.""" + +import ast +from pathlib import Path + +import pytest + +import forge_tool + +_SOURCE_ROOT = Path(forge_tool.__file__).resolve().parent + + +@pytest.mark.parametrize( + "source", + sorted(_SOURCE_ROOT.rglob("*.py")), + ids=lambda source: str(source.relative_to(_SOURCE_ROOT)), +) +def test_source_supports_python_311(source: Path) -> None: + ast.parse(source.read_text(encoding="utf-8"), filename=str(source), feature_version=(3, 11)) diff --git a/packages/tool/tests/test_wire.py b/packages/tool/tests/test_wire.py index fad1d13..f0030b7 100644 --- a/packages/tool/tests/test_wire.py +++ b/packages/tool/tests/test_wire.py @@ -63,7 +63,7 @@ def _tool_envelope(**overrides: object) -> ToolEnvelope: def test_message_type_literal_matches_runtime_registry() -> None: - assert set(get_args(ToolMessageType.__value__)) == TOOL_MESSAGE_TYPES + assert set(get_args(ToolMessageType)) == TOOL_MESSAGE_TYPES def test_generic_invoke_envelope_round_trips_as_deterministic_utf8_json() -> None: diff --git a/scripts/tests/test_publish_workflow.py b/scripts/tests/test_publish_workflow.py index af5228a..993e400 100644 --- a/scripts/tests/test_publish_workflow.py +++ b/scripts/tests/test_publish_workflow.py @@ -95,3 +95,35 @@ def test_manual_release_rejects_wrong_line_before_remote_lookup(tmp_path, tag, l ) assert result.returncode == 1 assert message in result.stderr + + +def test_release_tooling_checkout_preserves_clean_source_guard(tmp_path, monkeypatch): + workflow = yaml.safe_load((ROOT / ".github/workflows/publish-pypi.yml").read_text()) + job = workflow["jobs"]["publish"] + checkouts = [step for step in job["steps"] if step.get("uses", "").startswith("actions/checkout@")] + source = tmp_path / checkouts[0]["with"].get("path", ".") + tooling = tmp_path / checkouts[1]["with"]["path"] + source.mkdir(parents=True, exist_ok=True) + subprocess.run(["git", "init", "-q", str(source)], check=True) + (source / "versions.toml").write_text('[packages]\ntool = "2.0.1"\n') + subprocess.run(["git", "-C", str(source), "add", "versions.toml"], check=True) + subprocess.run( + ["git", "-C", str(source), "-c", "user.name=Release Test", + "-c", "user.email=release-test@example.invalid", "-c", "commit.gpgsign=false", + "commit", "-qm", "Release fixture"], + check=True, + ) + tooling.mkdir(parents=True, exist_ok=True) + (tooling / "helper.py").write_text("# Release tooling from the workflow revision.\n") + + working_directory = tmp_path / job.get("defaults", {}).get("run", {}).get("working-directory", ".") + monkeypatch.syspath_prepend(str(ROOT / "scripts")) + import build_python_distributions as builder + + monkeypatch.setattr(builder, "ROOT", working_directory) + builder._check_release_context("tool", None) + + # Unexpected source files must still block a release. + (source / "unexpected.py").write_text("# Unreviewed source change.\n") + with pytest.raises(builder.BuildError, match="clean Git working tree"): + builder._check_release_context("tool", None) diff --git a/uv.lock b/uv.lock index c4d3737..6903734 100644 --- a/uv.lock +++ b/uv.lock @@ -390,7 +390,7 @@ requires-dist = [ [[package]] name = "forge-tool" -version = "2.0.0" +version = "2.0.1" source = { editable = "packages/tool" } [package.optional-dependencies] diff --git a/versions.toml b/versions.toml index 76e8feb..a76f05f 100644 --- a/versions.toml +++ b/versions.toml @@ -6,7 +6,7 @@ msgs = "2.1.0" robot = "2.0.0" policy = "2.0.0" kinematics = "2.0.0" -tool = "2.0.0" +tool = "2.0.1" [interfaces] msgs = 1