Split Pub/Sub SDK into ably-pubsub-core and ably-pubsub-server

[umair-ably]

Implements PDR-091b (PubSub package split) for the Python SDK — plan steps 11, 12, 13, 14, 14b, 14c of plan.md, which is row 1 of the PR stack in step 10b.

What and why

Today an application installs ably and gets one package regardless of where it runs. PDR-091 makes the package name the declaration of the side: the client you reach for is the one whose package matches where your code runs, and — because a server connection is exempt from monthly-active-user counting — that declaration has to reach the wire, not just the README.

PDR-091b settles how: new majors on a new core, not thin wrappers over the old package. The ably distribution is not touched, is not re-exported, and reaches EOL a year after GA; fixes for it ship from a maintenance branch.

So this repo stops publishing ably and starts publishing two distributions:

Distribution	Ships	For
ably-pubsub-core	ably_pubsub/core/**	internal — no direct dependency, no API stability promise
ably-pubsub-server	ably_pubsub/server/**	what applications install

Layout

pyproject.toml                              # workspace root only, nothing publishable
core/pyproject.toml                         # ably-pubsub-core   4.0.0
core/src/ably_pubsub/core/**                # today's ably/**, moved with `git mv`
core/src/ably_pubsub/core/sync/             # generated by unasync, gitignored
server/pyproject.toml                       # ably-pubsub-server 4.0.0
server/src/ably_pubsub/server/__init__.py   # the doors + enumerated re-exports
server/src/ably_pubsub/server/sync.py       # hand-written sync door
test/                                       # stays at the root, runs against both members

Three decisions worth calling out, all recorded in the plan:

• The import namespace is ably_pubsub, not ably. This is the Python-specific problem Ruby and JS did not have. The legacy distribution owns the top-level ably/ import package; if the core shipped ably/ too, pip would install both file sets into one directory and uninstalling either would delete the other's files. An environment mid-migration — one venv serving two services, or a transitive dependency still on ably — has to keep both importable. ably_pubsub is a PEP 420 namespace with no __init__.py in either source tree, so the two wheels each contribute a subpackage and never claim the same file.
• 4.0.0 for both, lockstep forever. ably reached 3.1.2; starting over at 1.0.0 would read as a downgrade. The server pins ably-pubsub-core==4.0.0 exactly — the analogue of ably-js's exact peer dependency — so there can never be two cores in one environment. Locally [tool.uv.sources] resolves that pin to the checkout, and one uv sync gives a venv with both members editable.
• Class names do not change here. AblyRest / AblyRealtime stay, so this diff is a restructure and nothing else. The 091d public-API rename is a later, mechanical PR (step 18) and is not blocking on this.

requires-python becomes >=3.8, aligning metadata with what CI already tests; only the 3.7 dependency branches and two 3.7 mock shims go. crypto, vcdiff and oldcrypto all survive and forward from server to core at the same exact pin.

The doors

from ably_pubsub.server import create_http_client, create_realtime_client
from ably_pubsub.server.sync import create_http_client  # no event loop; no sync realtime client

Each takes exactly the keyword arguments the constructor it wraps takes today — the same key/token/token_details disambiguation, reused rather than reimplemented — so the migration is a call rewrite, not a re-read of the options docs. An options-object-first signature like ably-js and ably-ruby use was considered and rejected as un-Pythonic.

The types consumers need are enumerated re-exports (not a star import), mirroring ably-js's core-exports, so ably_pubsub.core never has to be imported directly.

The wire

Ably-Agent: ably-pubsub-python/4.0.0 python/3.12.1 ably-pubsub-server

• The family identifier is renamed ably-python → ably-pubsub-python, still versioned with lib_version. It lands here, before any prerelease, so even prerelease traffic partitions cleanly from legacy ably-python/* traffic. The maintenance branch keeps ably-python.
• Options gains an additive agents: dict[str, str | None] client option. HttpUtils.default_headers() renders each entry as name/version, or as a bare flag when the version is None — matching how the agents registry records entries that carry no version of their own, like browser. Both HTTP requests and the websocket handshake already funnel through that one function, so both paths are stamped identically.
• The server doors stamp ably-pubsub-server with no version, applied last so it wins a collision on its own identifier — the side is the package's to declare, not the caller's to redefine. Caller-supplied agents are preserved, so an SDK layered on top keeps its attribution.
• The -server suffix is load-bearing: realtime grants the MAU server exemption by matching an agent entry ending in it. There is a comment saying exactly that where the constant is defined, copied in spirit from ably-ruby's server.rb and ably-js's packages/shared/side.ts.

Both identifiers are registered in ably-common#361.

Commits

Deliberately split so each is diffable on its own:

Move the ably package to core/src/ably_pubsub/core	pure git mv + mechanical import rewrite, no behaviour
Build two distributions from a uv workspace	pyprojects, READMEs, unasync paths, gitignore, ruff
Rename the agent family identifier and make agents extensible	the core-side agent work
Add the ably-pubsub-server factory doors	the new package
Test the factory doors, the agent header and the packaging invariants
Point CI at the workspace and check the built distributions

Verification

Run locally on macOS / CPython 3.14.6 against nonprod:sandbox.

• uv run ruff check — clean.
• uv run unasync — regenerates core/src/ably_pubsub/core/sync/ and test/ably/sync/ against the new paths; the import rewrite keys on the full ably_pubsub.core prefix so it cannot reach into the hand-written ably_pubsub.server.
• uv run pytest test/unit — 104 passed. That includes the three new modules:
  • pubsub_server_test.py — 16 tests. The doors return the core's clients and pass options through; the Ably-Agent value from create_http_client, from the sync door, and from the headers create_realtime_client's transport hands to websockets.connect all match ^ably-pubsub-python/\d+\.\d+\.\d+(\S*)? python/\S+ ably-pubsub-server$ and contain no ably-pubsub-server/ token (the name/None regression ably-js#2297 guards against); a bare core AblyRest declares no side; agents={'my-sdk': '1.0'} survives; agents={'ably-pubsub-server': 'x'} cannot override the side entry.
  • pubsub_packaging_test.py — 11 tests, including one that actually builds both wheels and asserts their file lists do not overlap, that the core wheel carries ably_pubsub/core/sync/, and that neither carries ably_pubsub/__init__.py.
  • pubsub_reexport_test.py — the server's __all__ stays level with the core's public surface.
• uv build for both packages — ably_pubsub_core-4.0.0 (wheel + sdist, 57 files under ably_pubsub/core/sync/) and ably_pubsub_server-4.0.0 (wheel + sdist, exactly ably_pubsub/server/__init__.py and sync.py). No overlap, no ably_pubsub/__init__.py.
• Full suite including the sandbox tests (uv run unasync && uv run pytest, against nonprod:sandbox) — 1284 passed, 2 skipped, 0 failed, in about 14 minutes. That covers the async and generated-sync flavours of every REST test, the realtime suite, and both protocols via VaryByProtocolTestsMetaclass.
  • The first run reported 4 failures and 12 errors, all in restcrypto_test.py and restchannelpublish_test.py's interoperability tests. They were the submodules/ (ably-common) checkout being absent from my worktree, not a regression: once the submodule was initialised, all 128 of those tests pass. CI already checks submodules out recursively.

test/ably/rest/resthttp_test.py's RSC7d assertion was rewritten for the new family identifier.

Out of scope / follow-ups

• PR 2 — release tooling (plan step 15): release.yml still builds and publishes the single ably distribution and does not work against the workspace. It carries a TODO saying so. The artifact checks it used to run at tag time have moved into check.yml, where they now run on every PR.
• PR 5 — docs: the root README.md, UPDATING.md, CHANGELOG.md and CONTRIBUTING.md are untouched. Each distribution has its own README as its readme; LONG_DESCRIPTION.rst is deleted.
• PR 6 — 091d rename: AblyRest/AblyRealtime → HttpClient/RealtimeClient, ably_pubsub.core.rest → .http, and the deprecated-surface deletions, gated on that DR being decided.
• Repo rename, PyPI trusted publishers and the prerelease are steps 16–21 and unchanged by this PR.
• .ably/capabilities.yaml already declares Agent Identifier: Agents, so it needed no change.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[umair-ably]

Follow-up from the docs pass (#686), pushed as c415b95.

#686 found that Message, PresenceMessage and TokenRequest were not reachable from ably_pubsub.server. 3.x users deep-imported those from ably.types.* (UPDATING.md literally shows from ably.types.message import Message), and after the split the only place they live is ably_pubsub.core — which the README tells people never to import. A type that is not re-exported is not nameable by supported means at all, so type hints and direct construction were impossible.

I grepped the test suite and UPDATING.md/CHANGELOG.md for what users are actually shown, and added everything a consumer would reasonably annotate or construct.

Added to ably_pubsub.server (22 names, __all__ now 49):

messages	Message, MessageAnnotations
presence	Presence, PresenceMessage, PresenceAction
tokens	TokenRequest (TokenDetails was already there)
channel metadata	ChannelDetails, ChannelStatus, ChannelOccupancy, ChannelMetrics — the full shape channel.status() returns
state	ChannelState, ChannelStateChange, ConnectionState, ConnectionEvent, ConnectionStateChange
results	PaginatedResult, HttpPaginatedResponse, Stats
client-reachable objects	Channel, RealtimeChannel, Connection, RealtimePresence

Added to ably_pubsub.server.sync (14 names, __all__ now 39): the same, minus the realtime object and state types which have no synchronous counterpart, and with unasync's renames applied — ChannelSync, PaginatedResultSync, HttpPaginatedResponseSync.

Two notes on the audit:

• There is no TokenParams class. Token params are passed as plain dicts throughout (auth.request_token(token_params={...})), so there is nothing to export. Worth saying explicitly in the docs rather than leaving readers hunting for it.
• ErrorInfo has no separate type in Python — AblyException (already exported, along with AblyAuthException and IncompatibleClientIdException) carries code/status_code and is the equivalent.

Deliberately not added: transports, the connection manager, HTTP utilities, TypedBuffer/DataType/CipherData, EncodeDataMixin/DecodingContext/DeltaExtras, ConnectionDetails, and Flag. Those are implementation rather than surface, and 091d may delete or reshape them. Say the word if the docs need any of them and I will add them.

pubsub_reexport_test.py now pins the consumer-reachable list by name for both flavours, so a future trim of the public surface has to drop something on purpose rather than by omission.

Verification: uv run ruff check clean; uv run pytest test/unit 106 passed; test/unit plus the sandbox tests that touch these types (resthttp, restchannelstatus, reststats, restpresence) 186 passed.