Support Python 3.11 through 3.15

.github/actions/alpine-package-smoke/action.yml

@@ -20,7 +20,7 @@ inputs:
   python-image:
     description: "Alpine Python Docker image"
     required: false
-    default: "python:3.10-alpine"
+    default: "python:3.11-alpine"
 runs:
   using: composite
   steps:

.github/actions/release-smoke-package/action.yml

@@ -16,7 +16,7 @@ runs:
   steps:
     - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
       with:
-        python-version: "3.10"
+        python-version: "3.11"
     - name: Install package
       shell: bash
       env:

.github/workflows/ci.yml

@@ -20,15 +20,13 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python: ["3.10", "3.14"]
+        python: ["3.11", "3.15"]
         os: [ubuntu-latest, ubuntu-arm, macos-arm, windows-latest]
         include:
           - os: ubuntu-latest
-            python: "3.14"
+            python: "3.15"
             docsTarget: true
             clippyLinter: true
-          - python: "3.10"
-            pytestExtraArgs: '--reruns 3 --only-rerun "RuntimeError: Failed validating workflow"'
           - os: ubuntu-arm
             runsOn: ubuntu-24.04-arm64-2-core
           - os: macos-arm
@@ -106,7 +104,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           workspaces: temporalio/bridge -> target
@@ -181,9 +179,9 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - cibw-build: cp310-musllinux_x86_64
+          - cibw-build: cp311-musllinux_x86_64
             runsOn: ubuntu-latest
-          - cibw-build: cp310-musllinux_aarch64
+          - cibw-build: cp311-musllinux_aarch64
             runsOn: ubuntu-24.04-arm64-2-core
     runs-on: ${{ matrix.runsOn }}
     steps:
@@ -214,7 +212,7 @@ jobs:
       - uses: dtolnay/rust-toolchain@29eef336d9b2848a0b548edc03f92a220660cdb8 # stable
       - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
       - uses: Swatinem/rust-cache@e18b497796c12c097a38f9edb9d0641fb99eee32 # v2
         with:
           workspaces: temporalio/bridge -> target
@@ -226,19 +224,19 @@ jobs:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
       - uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
       - run: uv tool install poethepoet
-      - run: uv add --dev --python 3.10 "googleapis-common-protos==1.70.0"
-      - run: uv add --python 3.10 "protobuf<4"
       - run: uv sync --all-extras
       - run: cargo install --locked nexgen --version 0.2.8 --features advanced --force
       - run: poe build-develop
       - run: poe gen-protos
       - name: Check generation unchanged
         run: |
           [[ -z $(git status --porcelain temporalio tests) ]] || (git diff temporalio tests; echo "Protos changed"; exit 1)
-      - name: Test with protobuf 3.x
+      - run: uv add --dev --python 3.11 "googleapis-common-protos==1.70.0"
+      - run: uv add --python 3.11 "protobuf==4.21.12"
+      - run: uv sync --all-extras
+      - run: poe build-develop
+      - name: Test with minimum protobuf runtime
         run: poe test -s
-        env:
-          TEMPORAL_TEST_PROTO3: 1
 
   test-latest-deps:
     timeout-minutes: 30

.github/workflows/release-publish.yml

@@ -20,29 +20,29 @@ jobs:
         include:
           - os: ubuntu-latest
             package-suffix: linux-amd64
-            cibw-build: cp310-manylinux_x86_64
+            cibw-build: cp311-manylinux_x86_64
           - os: ubuntu-arm
             package-suffix: linux-aarch64
-            cibw-build: cp310-manylinux_aarch64
+            cibw-build: cp311-manylinux_aarch64
             runsOn: ubuntu-24.04-arm64-2-core
           - os: ubuntu-latest
             package-suffix: linux-musl-amd64
-            cibw-build: cp310-musllinux_x86_64
+            cibw-build: cp311-musllinux_x86_64
           - os: ubuntu-arm
             package-suffix: linux-musl-aarch64
-            cibw-build: cp310-musllinux_aarch64
+            cibw-build: cp311-musllinux_aarch64
             runsOn: ubuntu-24.04-arm64-2-core
           - os: macos-intel
             package-suffix: macos-amd64
-            cibw-build: cp310-macosx_x86_64
+            cibw-build: cp311-macosx_x86_64
             runsOn: macos-15-intel
           - os: macos-arm
             package-suffix: macos-aarch64
-            cibw-build: cp310-macosx_arm64
+            cibw-build: cp311-macosx_arm64
             runsOn: macos-15
           - os: windows-latest
             package-suffix: windows-amd64
-            cibw-build: cp310-win_amd64
+            cibw-build: cp311-win_amd64
     runs-on: ${{ matrix.runsOn || matrix.os }}
     permissions:
       contents: read

AGENTS.md

@@ -32,7 +32,8 @@ document as a quick reference when submitting pull requests.
 * Avoid unqualified imports from `temporalio` packages except `temporalio.types`.
   Relative imports are acceptable for private packages.
 * Do not commit `uv.lock` or `pyproject.toml` changes created only for temporary
-  protobuf downgrade workflows. Prefer to use poe gen-protos-docker when possible.
+  protobuf downgrade workflows. Use `poe gen-protos` for generation; uv manages
+  its isolated tool environment.
 
 ## Repo Specific Utilities
 
@@ -46,9 +47,8 @@ document as a quick reference when submitting pull requests.
   * `poe update-core` - update the Core pin and import its changelog fragments.
   * `poe format` - run Ruff import sorting, Ruff formatting, and `cargo fmt` for
     the bridge.
-  * `poe gen-protos-docker` - regenerate protobuf-related files using Docker.
-  * `poe gen-protos` - regenerate protobuf-related files without Docker, with
-    the Python/protobuf constraints documented in `README.md`.
+  * `poe gen-protos` - regenerate protobuf-related files with a uv-managed tool
+    environment, as documented in `README.md`.
 
 ## Building and Testing
 
@@ -121,7 +121,7 @@ Reviewers will look for:
 
 ## Notes
 
-* The SDK supports Python 3.10 and newer.
+* The SDK supports Python 3.11 through 3.15.
 * Generated protobuf and bridge files have specific regeneration workflows; see
   `README.md` before changing them.
 * The Rust bridge uses SDK Core from `temporalio/bridge/sdk-core`.
@@ -131,7 +131,7 @@ Reviewers will look for:
   and generated fragments together; do not update the pin and defer its notes
   until release time. The Python task copies Core path dependency versions from the new checkout
   and refreshes the bridge lockfile; review both and check Rust API compatibility as needed.
-  If Core protobuf definitions changed, run `poe gen-protos-docker` and commit the
+  If Core protobuf definitions changed, run `poe gen-protos` and commit the
   regenerated bindings with the pin update.
 * `__pycache__`, `build`, `dist`, and Rust `target` outputs are generated
   artifacts and should not be reviewed as source changes.

CONTRIBUTING.md

@@ -105,7 +105,7 @@ The command does not stage or commit changes or resolve Rust API
 compatibility issues. If dependency refresh fails, inspect the updated pin,
 fragments, and manifest before retrying.
 
-If Core protobuf definitions changed, run `poe gen-protos-docker` and include the
+If Core protobuf definitions changed, run `poe gen-protos` and include the
 regenerated bindings in the update PR.
 
 ## Things to Avoid

README.md

@@ -1,6 +1,6 @@
 ![Temporal Python SDK](https://assets.temporal.io/w/py.png)
 
-[![Python 3.10+](https://img.shields.io/pypi/pyversions/temporalio.svg?style=for-the-badge)](https://pypi.org/project/temporalio)
+[![Python 3.11+](https://img.shields.io/pypi/pyversions/temporalio.svg?style=for-the-badge)](https://pypi.org/project/temporalio)
 [![PyPI](https://img.shields.io/pypi/v/temporalio.svg?style=for-the-badge)](https://pypi.org/project/temporalio)
 [![MIT](https://img.shields.io/pypi/l/temporalio.svg?style=for-the-badge)](LICENSE)
 
@@ -112,7 +112,7 @@ informal introduction to the features and their implementation.
       - [Metrics](#metrics)
       - [OpenTelemetry Tracing](#opentelemetry-tracing)
       - [OpenTelemetry Metrics](#opentelemetry-metrics)
-    - [Protobuf 3.x vs 4.x](#protobuf-3x-vs-4x)
+    - [Protobuf compatibility](#protobuf-compatibility)
     - [Known Compatibility Issues](#known-compatibility-issues)
       - [gevent Patching](#gevent-patching)
 - [Development](#development)
@@ -2027,17 +2027,12 @@ async with MetricsExporter(buffer, meter_provider):
 exported, since it works by draining the buffer on a fixed interval (`poll_interval`, default one second) -- per the
 warning on `MetricBuffer`, updates are dropped if the buffer isn't drained regularly.
 
-### Protobuf 3.x vs 4.x
+### Protobuf compatibility
 
-Python currently has two somewhat-incompatible protobuf library versions - the 3.x series and the 4.x series. Python
-currently recommends 4.x and that is the primary supported version. Some libraries like
-[Pulumi](https://github.com/pulumi/pulumi) require 4.x. Other libraries such as [ONNX](https://github.com/onnx/onnx) and
-[Streamlit](https://github.com/streamlit/streamlit), for one reason or another, have/will not leave 3.x.
-
-To support these, Temporal Python SDK allows any protobuf library >= 3.19. However, the C extension in older Python
-versions can cause issues with the sandbox due to global state sharing. Temporal strongly recommends using the latest
-protobuf 4.x library unless you absolutely cannot at which point some proto libraries may have to be marked as
-[Passthrough Modules](#passthrough-modules).
+The SDK requires `protobuf>=4.21.12,<8` and supports protobuf 4, 5, 6, and 7 runtimes.
+Its Python bindings are generated with `grpcio-tools` 1.49.1, which bundles
+protoc 3.21.6 (Python protobuf 4.21.6).
+The optional `grpc` extra requires `grpcio>=1.49.1,<2`.
 
 ### Known Compatibility Issues
 
@@ -2052,7 +2047,7 @@ users are encouraged to not use gevent in asyncio applications (including Tempor
 
 # Development
 
-The Python SDK is built to work with Python 3.10 and newer. It is built using
+The Python SDK supports Python 3.11 through 3.15. It is built using
 [SDK Core](https://github.com/temporalio/sdk-rust/) which is written in Rust.
 
 ### Building
@@ -2248,18 +2243,16 @@ poe test -s --log-cli-level=DEBUG -k test_sync_activity_thread_cancel_caught
 
 #### Proto Generation and Testing
 
-If you have docker available, run
+Generate protobuf code:
 
 ```
-poe gen-protos-docker
+poe gen-protos
 ```
 
-Alternatively: to generate protobuf code, you must be on Python <= 3.10, and then run `uv add
-"protobuf<4"` + `uv sync --all-extras`. Then the protobuf files can be generated via `poe
-gen-protos` followed by `poe format`. Do not commit `uv.lock` or `pyproject.toml` changes. To go
-back from this downgrade, restore both of those files and run `uv sync --all-extras`. Tests can be
-run for protobuf version 3 by setting the `TEMPORAL_TEST_PROTO3` env var to `1` prior to running
-tests.
+`uv` runs the protobuf compiler in an isolated Python 3.11 environment using the
+dependencies declared in `scripts/gen_protos.py` and locked in
+`scripts/gen_protos.py.lock`. It downloads Python if needed and leaves the SDK
+development environment unchanged.
 
 ### Style
 

basedpyrightconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "pyproject.toml",
+  "reportAny": "none",
+  "reportExplicitAny": "none",
+  "reportIgnoreCommentWithoutRule": "none",
+  "reportImplicitAbstractClass": "none",
+  "reportUnannotatedClassAttribute": "none"
+}

changelog/added/leaping-python.md

@@ -0,0 +1 @@
+Add Python 3.15 support.

changelog/breaking-changes/dancing-python.md

@@ -0,0 +1 @@
+Drop Python 3.10 support; Python 3.11 or newer is now required.

changelog/breaking-changes/waltzing-protobuf.md

@@ -0,0 +1 @@
+Regenerate Python bindings with grpcio-tools 1.49.1. The SDK now requires protobuf >=4.21.12 (protobuf 3 is no longer supported), and the optional grpc extra requires grpcio >=1.49.1.