Integration branch for ably-pubsub-server v4 package

.claude/skills/release/SKILL.md

@@ -17,7 +17,7 @@ Then perform these steps in order:
 1. Run `git checkout -b release/NEW_VERSION`
 2. Replace `OLD_VERSION` with `NEW_VERSION` in all of the following files:
     - `pyproject.toml` — the `version` property
-    - `ably/__init__.py` — lib_version value
+    - `ably/pubsub/version.py` — lib_version value
       3.Run `uv sync` to update `uv.lock` file
 4. Commit all files together with message: `chore: bump version to NEW_VERSION`
 3. Fetch merged PRs since the last release tag using:

.github/workflows/release.yml

@@ -42,27 +42,27 @@ jobs:
         with:
           name: python-package-distributions
           path: dist/
-      - name: Check that wheel and tarball contains ably/sync/
+      - name: Check that wheel and tarball contains ably/pubsub/sync/
         run: |
           # Check wheel
           WHEEL=$(ls dist/*.whl | head -n 1)
           echo "Checking wheel: $WHEEL"
-          if unzip -l "$WHEEL" | grep -q "ably/sync/"; then
-            echo "✅ Found ably/sync/ in wheel"
+          if unzip -l "$WHEEL" | grep -q "ably/pubsub/sync/"; then
+            echo "✅ Found ably/pubsub/sync/ in wheel"
           else
             unzip -l "$WHEEL" 
-            echo "❌ ably/sync/ not found in wheel"
+            echo "❌ ably/pubsub/sync/ not found in wheel"
             exit 1
           fi
 
           # Check tarball
           TARBALL=$(ls dist/*.tar.gz | head -n 1)
           echo "Checking tarball: $TARBALL"
-          if tar -tzf "$TARBALL" | grep -q "ably/sync/"; then
-            echo "✅ Found ably/sync/ in tarball"
+          if tar -tzf "$TARBALL" | grep -q "ably/pubsub/sync/"; then
+            echo "✅ Found ably/pubsub/sync/ in tarball"
           else
             tar -tzf "$TARBALL"
-            echo "❌ ably/sync/ not found in tarball"
+            echo "❌ ably/pubsub/sync/ not found in tarball"
             exit 1
           fi
 
@@ -74,7 +74,7 @@ jobs:
     runs-on: ubuntu-latest
     environment:
       name: pypi
-      url: https://pypi.org/p/ably
+      url: https://pypi.org/p/ably-pubsub-server
     permissions:
       id-token: write  # IMPORTANT: mandatory for trusted publishing
 
@@ -94,7 +94,7 @@ jobs:
       - name: Read VERSION_NAME from dist/
         id: version
         run: |
-          VERSION_NAME=$(basename dist/ably-*.tar.gz | sed -E 's/^ably-([^-]+)\.tar\.gz$/\1/')
+          VERSION_NAME=$(basename dist/ably_pubsub_server-*.tar.gz | sed -E 's/^ably_pubsub_server-([^-]+)\.tar\.gz$/\1/')
           echo "version=$VERSION_NAME" >> $GITHUB_OUTPUT
 
       - name: Compare version with tag
@@ -118,7 +118,7 @@ jobs:
 
     environment:
       name: testpypi
-      url: https://test.pypi.org/p/ably
+      url: https://test.pypi.org/p/ably-pubsub-server
 
     permissions:
       id-token: write  # IMPORTANT: mandatory for trusted publishing

.gitignore

@@ -55,5 +55,5 @@ ably/types/options.py.orig
 test/ably/restsetup.py.orig
 
 .idea/**/*
-ably/sync/**
+ably/pubsub/sync/**
 test/ably/sync/**

CLAUDE.md

@@ -16,7 +16,11 @@ arithmetic on the unix epoch, are not clock readings and stay as they are.
 
 `asyncio.wait_for` in `ConnectionManager.ping` is the one delay that runs on the event
 loop's clock rather than this one; a test which waits it out sets a short real
-`realtime_request_timeout`.
+`realtime_request_timeout_seconds`.
+
+The timing client options are seconds, named `*_seconds`, where the clock counts
+milliseconds. `Options` converts them in one place, `seconds_to_ms`, behind a private
+`_<option>_ms` property for each, and code scheduling on the clock reads those.
 
 `Auth._timestamp` signs a token request the server validates, so a client which reads a
 fake clock talks to a mock rather than to the sandbox.

CONTRIBUTING.md

@@ -40,7 +40,7 @@ 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, updating [`pyproject.toml`](./pyproject.toml) and [`ably/pubsub/version.py`](./ably/pubsub/version.py)
 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-pubsub-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

LONG_DESCRIPTION.rst

@@ -1,15 +1,22 @@
-Official Ably Bindings for Python
-==================================
+Official Ably Pub/Sub Bindings for Python Servers
+=================================================
 
-A Python client library for Ably Realtime messaging.
+A Python client library for Ably Pub/Sub realtime messaging, for use from
+servers.
 
 
 Setup
 -----
 
 You can install this package by using the pip tool and installing:
 
-    pip install ably
+    pip install ably-pubsub-server
+
+The package installs into ``ably.pubsub``. Both ``ably`` and ``ably.pubsub``
+are namespace packages shared with the other ``ably-*`` distributions, so the
+whole public API is reached through ``ably.pubsub.server``::
+
+    from ably.pubsub.server import create_http_client, create_realtime_client
 
 
 Using Ably for Python

README.md

@@ -1,5 +1,5 @@
 ![Ably Pub/Sub Python Header](images/pythonSDK-github.png)
-[![PyPI version](https://badge.fury.io/py/ably.svg)](https://pypi.org/project/ably/)
+[![PyPI version](https://badge.fury.io/py/ably-pubsub-server.svg)](https://pypi.org/project/ably-pubsub-server/)
 [![License](https://img.shields.io/github/license/ably/ably-pubsub-python)](https://github.com/ably/ably-pubsub-python/blob/main/LICENSE)
 
 
@@ -48,9 +48,31 @@ The following platforms are supported:
 To get started with your project, install the package:
 
 ```sh
-pip install ably
+pip install ably-pubsub-server
 ```
 
+The package installs into `ably.pubsub`, and the whole public API is reached
+through `ably.pubsub.server`:
+
+```python
+from ably.pubsub.server import create_http_client, create_realtime_client
+```
+
+Clients are built by these factories rather than by constructing a class, so
+that the package a client comes from names the side your application runs on.
+Annotate against the prototypes they return, `PubSubHttpClient` and
+`PubSubRealtimeClient`.
+
+The synchronous, HTTP-only flavour lives alongside it:
+
+```python
+from ably.pubsub.server.sync import create_http_client
+```
+
+Both `ably` and `ably.pubsub` are [namespace packages](https://peps.python.org/pep-0420/)
+shared with the other `ably-*` distributions, so neither exports anything
+itself — always import from `ably.pubsub.server`.
+
 > [!NOTE]
 Install [Python](https://www.python.org/downloads/) version 3.8 or greater.
 
@@ -59,8 +81,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.server import create_realtime_client
+
 # Initialize Ably Realtime client
-async with AblyRealtime('your-ably-api-key', client_id='me') as realtime_client:
+async with create_realtime_client(key='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 +102,53 @@ async with AblyRealtime('your-ably-api-key', client_id='me') as realtime_client:
     await channel.publish('test-event', 'hello world')
 ```
 
+### LiveObjects
+
+LiveObjects keeps shared, mutable state on a channel: maps and counters that every client
+attached to it reads, updates and subscribes to. The channel needs the object modes, and
+`channel.object.get()` attaches it, waits for the objects to sync, and returns the root map.
+Values are read through a typed view of their path — `as_live_map()`, `as_live_counter()` or
+`as_primitive()` — and reads are synchronous; writes are awaited.
+
+```python
+from ably.pubsub.server import ChannelMode, ChannelOptions, create_realtime_client
+from ably.pubsub.server.liveobjects import LiveCounter, LiveMap
+
+async with create_realtime_client(key='your-ably-api-key') as realtime_client:
+    channel = realtime_client.channels.get(
+        'my-objects',
+        ChannelOptions(modes=[ChannelMode.OBJECT_SUBSCRIBE, ChannelMode.OBJECT_PUBLISH]),
+    )
+
+    # Attach, wait for the objects to sync, and get the root map
+    root = await channel.object.get()
+
+    # Create objects by setting them on the root
+    await root.set('visits', LiveCounter.create(0))
+    await root.set('profile', LiveMap.create({'name': 'Alice', 'theme': 'dark'}))
+
+    # Read through a typed view of the path
+    visits = root.get('visits').as_live_counter()
+    print(visits.value())                                     # 0.0
+    print(root.at('profile.name').as_primitive().value(str))  # Alice
+
+    # Subscribe to changes at a path
+    def on_change(event):
+        print(f'{event.object.path()} changed')
+
+    subscription = root.get('visits').subscribe(on_change)
+
+    # Mutate
+    await visits.increment(5)
+
+    # Batch several writes into a single message
+    async with root.get('profile').as_live_map().batch() as profile:
+        profile.set('name', 'Bob')
+        profile.remove('theme')
+
+    subscription.unsubscribe()
+```
+
 ## Releases
 
 The [CHANGELOG.md](https://github.com/ably/ably-pubsub-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).