pubsub: add server and device packages

PDR-091 splits the Pub/Sub SDKs so that the package an application
installs names the side it runs on. Ship that for Python as two thin
additive distributions over the existing package, which takes on the
role of the shared core and is otherwise unchanged:

- ably-pubsub-server provides ably.pubsub.server, with
  create_http_client(), create_realtime_client(), and a sync submodule
- ably-pubsub-device provides ably.pubsub.device, with create_client()

Both re-export the core's public surface and return its clients
unchanged, so behaviour is identical by construction. AblyRest and
AblyRealtime emit a DeprecationWarning naming their replacement; they
keep working and are not scheduled for removal.

ably.pubsub is a PEP 420 namespace directory so that two distributions
can each contribute a subpackage to it. The source stays in the shared
ably/ tree because ably is a regular package, so Python resolves
ably.pubsub only under the directory ably was imported from; each sdist
reaches up to collect its subtree, and must therefore be built before
its wheel.

All three distributions publish in a single upload, since the wrappers
pin the core exactly and a partial release is unusable. That requires
all three PyPI projects to register the same trusted publisher.

The side-declaring agent value PDR-091 also calls for is not included
here: the packages name the side, but nothing distinguishes them on the
wire yet.

Tests cover factory pass-through and warning suppression, the
deprecation in both async and generated sync flavours, re-export parity
with the core, and the packaging invariants (namespace directory,
version lockstep, exact core pin).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: ttypic

.github/workflows/check.yml

@@ -51,3 +51,10 @@ jobs:
         run: uv run unasync
       - name: Test with pytest
         run: uv run pytest --verbose --tb=short --capture=no
+      # Packaging metadata for the wrapper distributions is otherwise only
+      # exercised at release time, where a mistake is expensive.
+      - name: Check that every distribution builds
+        run: |
+          uv build --out-dir dist
+          uv build packages/ably-pubsub-server --out-dir dist
+          uv build packages/ably-pubsub-device --out-dir dist

.github/workflows/release.yml

@@ -35,28 +35,35 @@ jobs:
         run: uv sync --extra crypto --extra dev
       - name: Generate rest sync code and tests
         run: uv run unasync
+      # All three distributions build into one directory and are uploaded in a
+      # single request, so that a release is all of them or none of them. The
+      # wrappers pin the core exactly, so a partial release is an unusable one.
       - name: Build a binary wheel and a source tarball
-        run: uv build
+        run: |
+          uv build --out-dir dist
+          uv build packages/ably-pubsub-server --out-dir dist
+          uv build packages/ably-pubsub-device --out-dir dist
       - name: Store the distribution packages
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         with:
           name: python-package-distributions
           path: dist/
+      # The wrappers normalise to ably_pubsub_*, so ably-* selects the core alone
       - name: Check that wheel and tarball contains ably/sync/
         run: |
           # Check wheel
-          WHEEL=$(ls dist/*.whl | head -n 1)
+          WHEEL=$(ls dist/ably-*.whl | head -n 1)
           echo "Checking wheel: $WHEEL"
           if unzip -l "$WHEEL" | grep -q "ably/sync/"; then
             echo "✅ Found ably/sync/ in wheel"
           else
-            unzip -l "$WHEEL" 
+            unzip -l "$WHEEL"
             echo "❌ ably/sync/ not found in wheel"
             exit 1
           fi
-          
+
           # Check tarball
-          TARBALL=$(ls dist/*.tar.gz | head -n 1)
+          TARBALL=$(ls dist/ably-*.tar.gz | head -n 1)
           echo "Checking tarball: $TARBALL"
           if tar -tzf "$TARBALL" | grep -q "ably/sync/"; then
             echo "✅ Found ably/sync/ in tarball"
@@ -66,8 +73,29 @@ jobs:
             exit 1
           fi
 
+      - name: Check that all three distributions were built
+        run: |
+          # Publishing is a single upload, so a distribution missing here would
+          # silently ship a release that the other two cannot be installed with.
+          for NAME in ably ably_pubsub_server ably_pubsub_device; do
+            for EXT in tar.gz whl; do
+              COUNT=$(ls -1 dist/"$NAME"-*."$EXT" 2>/dev/null | wc -l)
+              if [ "$COUNT" -ne 1 ]; then
+                ls dist/
+                echo "❌ expected exactly one $NAME .$EXT, found $COUNT"
+                exit 1
+              fi
+            done
+            echo "✅ $NAME"
+          done
+
+  # ably, ably-pubsub-server and ably-pubsub-device go up in one upload. The
+  # short-lived token PyPI mints from an OIDC request carries every project that
+  # trusts the requesting configuration, so one job publishes all three — which
+  # requires each of the three projects to register this repository, workflow
+  # and environment as a trusted publisher.
   publish-to-pypi:
-    name: Publish Python distribution to PyPI
+    name: Publish Python distributions to PyPI
     if: startsWith(github.ref, 'refs/tags/v')  # only publish to PyPI on tag pushes
     needs:
       - build
@@ -91,27 +119,27 @@ jobs:
           TAG=${GITHUB_REF#refs/tags/v}
           echo "tag=$TAG" >> $GITHUB_OUTPUT
 
-      - name: Read VERSION_NAME from dist/
-        id: version
+      - name: Compare every distribution's version with the tag
         run: |
-          VERSION_NAME=$(basename dist/ably-*.tar.gz | sed -E 's/^ably-([^-]+)\.tar\.gz$/\1/')
-          echo "version=$VERSION_NAME" >> $GITHUB_OUTPUT
-
-      - name: Compare version with tag
-        run: |
-          if [ "$VERSION" != "$TAG" ]; then
-            echo "VERSION ($VERSION) does not match tag ($TAG)."
-            exit 1
-          fi
+          # sdist names are <normalised name>-<version>.tar.gz, and a normalised
+          # version never contains a hyphen, so the last one starts the version.
+          # Checking all three also catches a version that drifted out of lockstep.
+          for TARBALL in dist/*.tar.gz; do
+            VERSION=$(basename "$TARBALL" | sed -E 's/^.*-([^-]+)\.tar\.gz$/\1/')
+            if [ "$VERSION" != "$TAG" ]; then
+              echo "❌ $(basename "$TARBALL"): version ($VERSION) does not match tag ($TAG)."
+              exit 1
+            fi
+            echo "✅ $(basename "$TARBALL") matches tag $TAG"
+          done
         env:
-          VERSION: ${{ steps.version.outputs.version }}
           TAG: ${{ steps.tag.outputs.tag }}
 
-      - name: Publish distribution 📦 to PyPI
+      - name: Publish distributions 📦 to PyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
 
   publish-to-testpypi:
-    name: Publish Python distribution to TestPyPI
+    name: Publish Python distributions to TestPyPI
     needs:
       - build
     runs-on: ubuntu-latest
@@ -129,7 +157,7 @@ jobs:
         with:
           name: python-package-distributions
           path: dist/
-      - name: Publish distribution 📦 to TestPyPI
+      - name: Publish distributions 📦 to TestPyPI
         uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
         with:
           repository-url: https://test.pypi.org/legacy/

CONTRIBUTING.md

@@ -15,12 +15,39 @@ git submodule update
 uv sync --extra crypto
 ```
 
+### Repository layout
+
+This repository builds three distributions, released together on the same version. They all install into the one `ably` package, so what you import never tells you which distribution shipped it:
+
+| Distribution | Source | Imported as | Role |
+|--------------|--------|-------------|------|
+| `ably` | [`ably/`](./ably), except `ably/pubsub` | `ably`, `ably.sync` | The shared core, containing all of the implementation |
+| `ably-pubsub-server` | [`ably/pubsub/server/`](./ably/pubsub/server) | `ably.pubsub.server` | The server-side factories |
+| `ably-pubsub-device` | [`ably/pubsub/device/`](./ably/pubsub/device) | `ably.pubsub.device` | The device-side factory |
+
+Each side re-exports the core's public surface and adds factories that return the core's clients unchanged, so that the package a caller installs names the side their application runs on. They pin the core exactly, so any change to the core's public surface needs the corresponding re-export added to both.
+
+The packaging metadata for the two pubsub distributions lives in [`packages/`](./packages), away from the code it ships. Two rules keep that arrangement working, and both are covered by [`test/unit/pubsub_packaging_test.py`](./test/unit/pubsub_packaging_test.py):
+
+- **`ably/pubsub/` must not gain an `__init__.py`.** It is a namespace directory (PEP 420) so that two distributions can each contribute a subpackage to it. An `__init__.py` would belong to whichever one shipped it, and removing that distribution would take the other side's subpackage with it.
+- **The source stays in the shared `ably/` tree**, not beside the `pyproject.toml` that ships it. `ably` is a regular package, so Python looks for `ably.pubsub` only under the directory `ably` itself was imported from — in a checkout, that is `ably/`. Each sdist reaches up to collect its subtree, and its wheel is then built from that sdist.
+
 ### Running the test suite
 
 ```shell
 uv run pytest
 ```
 
+Because the pubsub code lives in the `ably/` tree, `ably.pubsub.server` and `ably.pubsub.device` import from a checkout with nothing installed beyond the core. Their tests are in [`test/unit/`](./test/unit) and need no network.
+
+To build all three distributions — build the sdist first, which `uv build` does by default:
+
+```shell
+uv build --out-dir dist
+uv build packages/ably-pubsub-server --out-dir dist
+uv build packages/ably-pubsub-device --out-dir dist
+```
+
 ## Release Process (Claude Code)
 
 1. Ensure that all work intended for this release has landed to `main`
@@ -36,11 +63,13 @@ uv run pytest
 
 Releases should always be made through a release pull request (PR), which needs to bump the version number and add to the [change log](CHANGELOG.md).
 
+`ably`, `ably-pubsub-server` and `ably-pubsub-device` are published in a single upload, so that a release is all three or none of them — the wrappers pin the core exactly, so a partial release is an unusable one. This works because the short-lived token PyPI mints from an OIDC request carries every project that trusts the requesting configuration, which means **all three PyPI projects must register the same trusted publisher**: this repository, `release.yml`, and the `pypi` environment (and likewise `testpypi`). Adding a fourth distribution means registering it the same way before its first release, or the whole upload fails.
+
 The release process must include the following steps:
 
 1. Ensure that all work intended for this release has landed to `main`
 2. Create a release branch named like `release/2.0.1`
-3. Add a commit to bump the version number, updating [`pyproject.toml`](./pyproject.toml) and [`ably/__init__.py`](./ably/__init__.py)
+3. Add a commit to bump the version number. All three distributions release in lockstep, so this means [`pyproject.toml`](./pyproject.toml), [`ably/__init__.py`](./ably/__init__.py), and, for each pubsub distribution, its `pyproject.toml` under [`packages/`](./packages) (both its own version and its `ably==` pins) and the `__version__` in its module under [`ably/pubsub/`](./ably/pubsub). The tests in [`test/unit/pubsub_packaging_test.py`](./test/unit/pubsub_packaging_test.py) fail if any of these drift apart
 4. Run [`github_changelog_generator`](https://github.com/github-changelog-generator/github-changelog-generator) to automate the update of the [CHANGELOG](./CHANGELOG.md). This may require some manual intervention, both in terms of how the command is run and how the change log file is modified. Your mileage may vary:
    - The command you will need to run will look something like this: `github_changelog_generator -u ably -p ably-python --since-tag v2.0.0 --output delta.md --token $GITHUB_TOKEN_WITH_REPO_ACCESS`. Generate token [here](https://github.com/settings/tokens/new?description=GitHub%20Changelog%20Generator%20token).
    - Using the command above, `--output delta.md` writes changes made after `--since-tag` to a new file
@@ -51,7 +80,7 @@ The release process must include the following steps:
 7. Create a release PR (ensure you include an SDK Team Engineering Lead and the SDK Team Product Manager as reviewers) and gain approvals for it, then merge that to `main`
 8. Create a tag named like `v2.0.1` and push it to GitHub - e.g. `git tag v2.0.1 && git push origin v2.0.1`
 9. Create the release on GitHub including populating the release notes
-10. Go to the [Release Workflow](https://github.com/ably/ably-python/actions/workflows/release.yml) and ask [ably/team-sdk](https://github.com/orgs/ably/teams/team-sdk) member to approve publishing to the PyPI registry
+10. Go to the [Release Workflow](https://github.com/ably/ably-python/actions/workflows/release.yml) and ask [ably/team-sdk](https://github.com/orgs/ably/teams/team-sdk) member to approve publishing to the PyPI registry. All three distributions go up in a single upload, so there is one approval for the release as a whole
 11. Update the [Ably Changelog](https://changelog.ably.com/) (via [headwayapp](https://headwayapp.co/)) with these changes
 
 We tend to use [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator) to collate the information required for a change log update.

README.md

@@ -45,12 +45,18 @@ The following platforms are supported:
 
 ## Installation
 
-To get started with your project, install the package:
+Install the package for the side your application runs on. Each pulls in `ably` and adds an entry point under `ably.pubsub` naming that side:
 
 ```sh
-pip install ably
+# Trusted server environments — publishing, token issuing, backend subscribers
+pip install ably-pubsub-server   # provides ably.pubsub.server
+
+# End-user devices — desktop apps, CLIs, IoT and embedded clients
+pip install ably-pubsub-device   # provides ably.pubsub.device
 ```
 
+Installing `ably` on its own also still works, and remains fully supported. It is the shared core both build on, and the clients they return are its clients unchanged.
+
 > [!NOTE]
 Install [Python](https://www.python.org/downloads/) version 3.8 or greater.
 
@@ -59,8 +65,10 @@ Install [Python](https://www.python.org/downloads/) version 3.8 or greater.
 The following code connects to Ably's realtime messaging service, subscribes to a channel to receive messages, and publishes a test message to that same channel.
 
 ```python
+from ably.pubsub.device import create_client
+
 # Initialize Ably Realtime client
-async with AblyRealtime('your-ably-api-key', client_id='me') as realtime_client:
+async with create_client('your-ably-api-key', client_id='me') as realtime_client:
     # Wait for connection to be established
     await realtime_client.connection.once_async('connected')
     print('Connected to Ably')
@@ -78,6 +86,21 @@ async with AblyRealtime('your-ably-api-key', client_id='me') as realtime_client:
     await channel.publish('test-event', 'hello world')
 ```
 
+On a server, use `ably.pubsub.server.create_realtime_client()` for the same client over a persistent connection, or `ably.pubsub.server.create_http_client()` when publish, history, presence reads, stats and token issuing over HTTP are enough. A synchronous HTTP client is available from `ably.pubsub.server.sync`.
+
+### Migrating from the AblyRest and AblyRealtime constructors
+
+Constructing `ably.AblyRest` or `ably.AblyRealtime` directly still works and is not scheduled for removal, but it emits a `DeprecationWarning` pointing at the factory for your side:
+
+| Before | After |
+|--------|-------|
+| `ably.AblyRealtime(...)` on a device | `ably.pubsub.device.create_client(...)` |
+| `ably.AblyRealtime(...)` on a server | `ably.pubsub.server.create_realtime_client(...)` |
+| `ably.AblyRest(...)` | `ably.pubsub.server.create_http_client(...)` |
+| `ably.sync.AblyRestSync(...)` | `ably.pubsub.server.sync.create_http_client(...)` |
+
+The factories take the same arguments as the constructors they replace and behave identically to them, so migrating is a change of entry point only.
+
 ## Releases
 
 The [CHANGELOG.md](https://github.com/ably/ably-python/blob/main/CHANGELOG.md) contains details of the latest releases for this SDK. You can also view all Ably releases on [changelog.ably.com](https://changelog.ably.com).

ably/pubsub/device/__init__.py

@@ -0,0 +1,85 @@
+"""The Ably Pub/Sub client for devices.
+
+Devices are applications running in end-user environments — desktop apps, CLIs,
+IoT and embedded clients — whose connections are identified by a `client_id` and
+counted on accounts with monthly-active-user billing. This package names that
+side, so the client an application should reach for is the one whose package
+matches where it runs.
+
+Use `create_client()` to open a realtime connection with channels, presence and
+history. It returns the same client `ably` does, with identical behaviour.
+
+Ships in the `ably-pubsub-device` distribution, which adds this subpackage to
+the `ably` package installed by the `ably` distribution.
+"""
+
+import asyncio
+from typing import Optional
+
+from ably import (
+    AblyAuthException,
+    AblyException,
+    AblyRealtime,
+    AblyRest,
+    AblyVCDiffDecoder,
+    Annotation,
+    AnnotationAction,
+    Auth,
+    Capability,
+    ChannelMode,
+    ChannelOptions,
+    CipherParams,
+    DeviceDetails,
+    IncompatibleClientIdException,
+    MessageAction,
+    MessageOperation,
+    MessageVersion,
+    Options,
+    PublishResult,
+    Push,
+    PushChannelSubscription,
+    UpdateDeleteResult,
+    VCDiffDecoder,
+)
+from ably.util.deprecation import suppress_constructor_deprecation
+
+__version__ = '3.1.2'
+
+
+def create_client(key: Optional[str] = None, loop: Optional[asyncio.AbstractEventLoop] = None,
+                  **kwargs) -> AblyRealtime:
+    """Create a device Pub/Sub client: a realtime connection to Ably with
+    channels, presence and history.
+
+    Takes the same arguments as `ably.AblyRealtime`, and behaves identically to it.
+    """
+    with suppress_constructor_deprecation():
+        return AblyRealtime(key=key, loop=loop, **kwargs)
+
+
+__all__ = [
+    'AblyAuthException',
+    'AblyException',
+    'AblyRealtime',
+    'AblyRest',
+    'AblyVCDiffDecoder',
+    'Annotation',
+    'AnnotationAction',
+    'Auth',
+    'Capability',
+    'ChannelMode',
+    'ChannelOptions',
+    'CipherParams',
+    'DeviceDetails',
+    'IncompatibleClientIdException',
+    'MessageAction',
+    'MessageOperation',
+    'MessageVersion',
+    'Options',
+    'PublishResult',
+    'Push',
+    'PushChannelSubscription',
+    'UpdateDeleteResult',
+    'VCDiffDecoder',
+    'create_client',
+]