Merge remote-tracking branch 'origin/main' into backport-sourcing-consumer-config

# Conflicts:
#	nats/tests/test_js.py

Author: caspervonb

.github/workflows/check.yml

@@ -19,16 +19,16 @@ jobs:
             - name: Set up Python
               uses: actions/setup-python@v6
               with:
-                  python-version: "3.8"
+                  python-version: "3.13"
 
             - name: Install uv
               uses: astral-sh/setup-uv@v6
 
             - name: Install the project
-              run: uv sync --dev
+              run: uv sync --only-group check
 
             - name: Run format check
-              run: uv run ruff format --check
+              run: uv run --no-sync ruff format --check
 
     lint:
         runs-on: ubuntu-latest
@@ -40,16 +40,16 @@ jobs:
             - name: Set up Python
               uses: actions/setup-python@v6
               with:
-                  python-version: "3.8"
+                  python-version: "3.13"
 
             - name: Install uv
               uses: astral-sh/setup-uv@v6
 
             - name: Install the project
-              run: uv sync --dev
+              run: uv sync --only-group check
 
             - name: Run lint check
-              run: uv run ruff check
+              run: uv run --no-sync ruff check
 
     spell:
         runs-on: ubuntu-latest
@@ -61,16 +61,16 @@ jobs:
             - name: Set up Python
               uses: actions/setup-python@v6
               with:
-                  python-version: "3.8"
+                  python-version: "3.13"
 
             - name: Install uv
               uses: astral-sh/setup-uv@v6
 
             - name: Install the project
-              run: uv sync --dev
+              run: uv sync --only-group check
 
             - name: Run spell check
-              run: uv run codespell
+              run: uv run --no-sync codespell
 
     type:
         runs-on: ubuntu-latest
@@ -82,7 +82,7 @@ jobs:
             - name: Set up Python
               uses: actions/setup-python@v6
               with:
-                  python-version: "3.8"
+                  python-version: "3.13"
 
             - name: Install uv
               uses: astral-sh/setup-uv@v6
@@ -91,7 +91,7 @@ jobs:
               run: uv sync --dev
 
             - name: Run type check
-              run: uv run ty check nats-core nats-server
+              run: uv run --no-sync ty check nats-core nats-server
 
     build:
         runs-on: ubuntu-latest

.github/workflows/test.yml

@@ -15,18 +15,26 @@ jobs:
     nats:
         runs-on: ubuntu-latest
         timeout-minutes: 20
-        env:
-            NATS_SERVER_VERSION: ${{ matrix.nats_version }}
         strategy:
             fail-fast: false
             matrix:
                 python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
-                nats_version: ["latest"]
+                nats-server-version: ["latest"]
 
         steps:
             - name: Check out repository
               uses: actions/checkout@v5
 
+            - name: Set up Go
+              uses: actions/setup-go@v6
+              with:
+                  go-version: "stable"
+
+            - name: Install NATS Server
+              run: |
+                  go install github.com/nats-io/nats-server/v2@${{ matrix.nats-server-version }}
+              shell: bash
+
             - name: Set up Python ${{ matrix.python-version }}
               uses: actions/setup-python@v6
               with:
@@ -36,15 +44,15 @@ jobs:
               uses: astral-sh/setup-uv@v6
 
             - name: Install dependencies and project
+              # Installed outside the workspace: uv.lock is pinned to >=3.13 for the
+              # modern packages, so it cannot resolve the 3.8-3.12 legs of this matrix.
               run: |
-                  uv sync --dev
-                  ./nats/scripts/install_nats.sh
+                  uv venv --no-project --python python
+                  uv pip install --python .venv/bin/python --editable ./nats --group ./nats/pyproject.toml:dev
 
             - name: Run tests
               run: |
-                  uv run pytest -x -vv -s --continue-on-collection-errors ./nats/tests
-              env:
-                  PATH: $HOME/nats-server:$PATH
+                  .venv/bin/python -m pytest -x -vv -s --continue-on-collection-errors ./nats/tests
 
     project:
         name: ${{ matrix.project }} (python-${{ matrix.python-version }}, nats-server-${{ matrix.nats-server-version }}, ${{ matrix.os }})
@@ -54,7 +62,7 @@ jobs:
                 python-version: ["3.13"]
                 os: ["ubuntu-latest", "macos-latest", "windows-latest"]
                 nats-server-version: ["latest"]
-                project: ["nats-server", "nats-core", "nats-key-value"]
+                project: ["nats-server", "nats-core", "nats-jetstream", "nats-key-value"]
         steps:
             - name: Checkout repository
               uses: actions/checkout@v5
@@ -82,5 +90,5 @@ jobs:
               working-directory: ${{ matrix.project }}
 
             - name: Run tests for ${{ matrix.project }}
-              run: uv run pytest -v -n auto
+              run: uv run --no-sync pytest -v -n auto
               working-directory: ${{ matrix.project }}

examples/docs/README.md

@@ -0,0 +1,63 @@
+# NATS Documentation Examples
+
+These are the Python equivalents of the docs examples published in the NATS
+documentation. They mirror the
+[Rust](https://github.com/nats-io/nats.rs/tree/main/async-nats/examples)
+and [Java](https://github.com/nats-io/nats.java/tree/main/examples/src/main/java/io/nats/examples/natsIoDoc)
+versions of the same examples.
+
+The examples use the modern [`nats-core`](../../nats-core) client (and
+[`nats-jetstream`](../../nats-jetstream) for the JetStream example).
+They require **Python 3.13+**.
+
+## Running
+
+From the workspace root:
+
+```bash
+uv sync
+uv run python examples/docs/basics_publish.py
+```
+
+Most examples connect to the public `demo.nats.io` server. The JetStream
+example (`jetstream_basic.py`) needs a local server with JetStream enabled
+on `127.0.0.1:4222` — for example:
+
+```bash
+nats-server -js
+```
+
+Examples that mix a publisher and subscriber include both in the same file
+for convenience.
+
+## Examples
+
+### Basics
+- `basics_publish.py` — publish a message to a subject
+- `basics_subscribe.py` — subscribe to a subject
+
+### Getting Started
+- `getting_started_publish.py` — minimal publisher
+- `getting_started_subscribe.py` — minimal subscriber (async + sync)
+
+### Subjects
+- `subjects_single_wildcard.py` — `*` token wildcard subscriptions
+- `subjects_multi_wildcard.py` — `>` tail wildcard subscriptions
+- `subjects_monitoring.py` — wire-tap subscription with `>`
+
+### Queue Groups
+- `queue_groups_basic.py` — three workers in a queue group
+- `queue_groups_dynamic_scaling.py` — add/remove workers at runtime
+- `queue_groups_mixed_subscribers.py` — mix of plain subs and queue subs
+- `queue_groups_request_reply.py` — load-balanced request/reply
+
+### Request / Reply
+- `request_reply_basic.py` — basic request/reply
+- `request_reply_calculator.py` — small calculator service
+- `request_reply_headers.py` — request/reply with message headers
+- `request_reply_multiple_responders.py` — multiple responders, first wins
+- `request_reply_no_responders.py` — handling no-responders
+- `request_reply_timeout.py` — request with a custom timeout
+
+### JetStream
+- `jetstream_basic.py` — create a stream, publish, durable pull consumer

examples/docs/basics_publish.py

@@ -0,0 +1,19 @@
+import asyncio
+
+from nats import client
+
+
+async def main():
+    nc = await client.connect("nats://demo.nats.io")
+
+    # NATS-DOC-START
+    # Publish a message to the subject "weather.updates"
+    await nc.publish("weather.updates", "Temperature: 72°F".encode())
+    # NATS-DOC-END
+
+    await nc.flush()
+    await nc.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/docs/basics_subscribe.py

@@ -0,0 +1,26 @@
+import asyncio
+
+from nats import client
+
+
+async def main():
+    nc = await client.connect("nats://demo.nats.io")
+
+    # NATS-DOC-START
+    # Subscribe to 'weather.updates' synchronously
+    sub = await nc.subscribe("weather.updates")
+
+    # Process messages
+    while True:
+        try:
+            msg = await sub.next(timeout=1)
+            print(f"Received: {msg.data.decode()}")
+        except TimeoutError:
+            break
+    # NATS-DOC-END
+
+    await nc.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/docs/getting_started_publish.py

@@ -0,0 +1,24 @@
+import asyncio
+
+from nats import client
+
+
+# NATS-DOC-START
+async def main():
+    # Connect to NATS demo server
+    nc = await client.connect("nats://demo.nats.io")
+
+    # Publish a message to the subject "hello"
+    await nc.publish("hello", b"Hello NATS!")
+    await nc.flush()
+
+    print("Message published to hello")
+
+    await nc.close()
+
+
+# NATS-DOC-END
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/docs/getting_started_subscribe.py

@@ -0,0 +1,39 @@
+import asyncio
+
+from nats import client
+
+
+# NATS-DOC-START
+async def main():
+    nc = await client.connect("nats://demo.nats.io")
+
+    # Asynchronous subscriber - iterate messages in a background task
+    async_sub = await nc.subscribe("hello")
+
+    async def async_handler():
+        async for msg in async_sub:
+            print(f"Asynchronous Subscriber Received: {msg.data.decode()}")
+
+    asyncio.create_task(async_handler())
+
+    # Synchronous subscription
+    sync_sub = await nc.subscribe("hello")
+
+    print("Waiting for message on 'hello'")
+
+    # Process messages synchronously
+    while True:
+        try:
+            msg = await sync_sub.next(timeout=1)
+            print(f"Synchronous Subscriber Received: {msg.data.decode()}")
+        except TimeoutError:
+            break
+
+    await nc.close()
+
+
+# NATS-DOC-END
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/docs/jetstream_basic.py

@@ -0,0 +1,39 @@
+import asyncio
+
+from nats import client, jetstream
+
+
+async def main():
+    # JetStream requires a server with JetStream enabled (demo.nats.io does not).
+    nc = await client.connect("nats://127.0.0.1:4222")
+
+    # NATS-DOC-START
+    # JetStream context
+    js = jetstream.new(nc)
+
+    # Create a stream that captures any subject under `orders.`
+    stream = await js.create_stream(name="ORDERS", subjects=["orders.>"], storage="file")
+
+    # Publish a few orders
+    await js.publish("orders.new", b"Order #1001")
+    await js.publish("orders.new", b"Order #1002")
+    await js.publish("orders.shipped", b"Order #1001 shipped")
+
+    # Create a durable pull consumer that delivers from the beginning
+    consumer = await stream.create_or_update_consumer(
+        name="order-processor",
+        ack_policy="explicit",
+    )
+
+    # Fetch a batch and acknowledge each message
+    batch = await consumer.fetch(max_messages=3, max_wait=2.0)
+    async for msg in batch:
+        print(f"Received on {msg.subject}: {msg.data.decode()}")
+        await msg.ack()
+    # NATS-DOC-END
+
+    await nc.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/docs/learn_core_nats_publish_subscribe_publish.py

@@ -0,0 +1,21 @@
+import asyncio
+
+from nats.client import connect
+
+
+async def main():
+    client = await connect("nats://localhost:4222")
+
+    # NATS-DOC-START
+    # Publish one order to the orders.created subject. Publishing is
+    # fire-and-forget: the call hands the message to the server and returns.
+    order = '{"order_id":"ord_8w2k","customer":"acme-co","total_cents":4200,"ts":"2026-05-22T10:14:22Z"}'
+    await client.publish("orders.created", order.encode())
+    # NATS-DOC-END
+
+    await client.flush()
+    await client.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())