pubsub: breaking changes to exports

.claude/skills/uts-to-python/SKILL.md

@@ -703,9 +703,8 @@ test that needs the connection to suspend before the channel does must set
 
 **21. `presence.subscribe()` and `annotations.subscribe()` are coroutines that
 attach.** They must be awaited, and they cannot run before `connect()`. `unsubscribe()`
-is not a coroutine. Presence event names are the lowercase action names from
-`PresenceAction._action_name`, which is monkey-patched onto `PresenceAction` at the
-bottom of `presence.py` and exists only once that module is imported.
+is not a coroutine. Presence event names are the lowercase names of the `PresenceAction`
+members, an `IntEnum`, as `_action_name` in `realtime/presence.py` gives them.
 
 **22. `RecordedUrl` cannot survive a URL httpx rejects.** `httpx.URL` caps at 64 KiB
 and raises inside `PendingConnection.__init__` **before** the attempt is recorded, so

UPDATING.md

@@ -47,7 +47,10 @@ from ably.pubsub.server.sync import create_http_client
 Where 3.x left you reaching into submodules such as `ably.types.message` or
 `ably.http.paginatedresult`, import from `ably.pubsub.server` instead. It is
 the whole public API, and `ably.pubsub.server.sync` is its synchronous
-counterpart. The packages beneath them are internal and free to move.
+counterpart. The packages beneath them are internal and free to move. The
+types a client returns, hands to a listener or accepts are exported there,
+including those 3.x left in submodules only, such as `ConnectionState` and
+`PresenceMessage`, as the section on exports below lists.
 
 For example, the encryption helpers move from `ably.util.crypto`:
 
@@ -922,6 +925,130 @@ milliseconds is sent as before.
 
 No change is needed.
 
+### `PresenceAction` is an `IntEnum`
+
+`PresenceAction` is now an `IntEnum`, as `MessageAction` and `AnnotationAction` are, and the
+`action` of a `PresenceMessage` received from Ably is one of its members, where 3.x gave a
+bare `int` from a plain class of constants. A member is still an `int`: it compares equal to
+its wire value, so `member.action == 2` and `member.action == PresenceAction.ENTER` both still
+hold, it hashes like that value, and it is still sent to Ably as the number. Two things do
+change. `type(member.action) is int` no longer holds, and `repr()` of an action is now
+`<PresenceAction.ENTER: 2>` rather than `2`; before Python 3.11, `str()` and `%s` give
+`PresenceAction.ENTER` too, though an f-string still gives `2`. Use `int()` where you need the
+plain number, and `.name` for the name. An action this version does not know is left as the
+`int` Ably sent.
+
+Example 3.x code:
+```python
+if type(member.action) is int:
+    log.info('presence action %s', member.action)
+```
+
+Example 4.0.0 code:
+```python
+from ably.pubsub.server import PresenceAction
+
+if isinstance(member.action, PresenceAction):
+    log.info('presence action %s', member.action.name)
+```
+
+### Every handle of the synchronous client ends in `Sync`
+
+The synchronous client's presence, annotations and push admin objects are now instances of
+`PresenceSync`, `HttpAnnotationsSync`, `PushDeviceRegistrationsSync` and
+`PushChannelSubscriptionsSync`, as its auth, channels, channel and push objects already were of
+`AuthSync`, `ChannelsSync`, `ChannelSync`, `PushSync` and `PushAdminSync`. In 3.x these four
+were named `Presence`, `RestAnnotations`, `PushDeviceRegistrations` and
+`PushChannelSubscriptions`, the same names as the asynchronous classes, so a traceback, a
+`repr()` or `type(x).__name__` could not say which flavour an object came from. Data types,
+enums, exceptions and the `PubSubHttpClient` prototype keep their names in both flavours.
+
+Only code that names these classes, in an annotation or an `isinstance` check, needs a change:
+
+Example 3.x code:
+```python
+from ably.sync.types.presence import Presence
+
+def members(presence: Presence) -> list: ...
+```
+
+Example 4.0.0 code:
+```python
+from ably.pubsub.server.sync import PresenceSync
+
+def members(presence: PresenceSync) -> list: ...
+```
+
+### Every public type is exported from `ably.pubsub.server`
+
+`ably.pubsub.server` now exports the types a client returns, hands to a listener or accepts,
+so no import needs to reach into the packages beneath it. 3.x exported only some of them from
+`ably`, and left the rest, such as `ConnectionState` and `PresenceMessage`, in submodules. These
+names are new:
+
+| | Names |
+|---|---|
+| States | `ChannelState`, `ChannelStateChange`, `ConnectionState`, `ConnectionEvent`, `ConnectionStateChange` |
+| Presence and stats | `PresenceMessage`, `PresenceAction`, `Stats` |
+| Auth and channel status | `TokenRequest`, `ChannelDetails`, `ChannelStatus`, `ChannelOccupancy`, `ChannelMetrics` |
+| Objects a client hands out | `Channel`, `Presence`, `HttpAnnotations`, `RealtimeChannel`, `RealtimePresence`, `RealtimeAnnotations`, `PushAdmin`, `PushDeviceRegistrations`, `PushChannelSubscriptions` |
+| Errors and push | `InvalidArgumentException`, `DevicePushDetails` |
+
+`Channel`, `Presence` and `HttpAnnotations` are the HTTP client's channel and its presence
+and annotations, and `RealtimeChannel` is a subclass of `Channel`. Like the clients, the
+objects these classes describe come from a client: the classes are exported for annotations
+and `isinstance` checks, not to be constructed. A few types reached only through an attribute
+of another, such as `connection.connection_details`, `message.annotations` and
+`response.headers`, are not exported yet; read their attributes without naming the type.
+
+Example 3.x code:
+```python
+from ably.realtime.channel import RealtimeChannel
+from ably.types.connectionstate import ConnectionState, ConnectionStateChange
+from ably.types.presence import PresenceMessage
+
+def on_state(change: ConnectionStateChange) -> None:
+    if change.current == ConnectionState.FAILED:
+        ...
+
+async def members(channel: RealtimeChannel) -> list[PresenceMessage]:
+    return await channel.presence.get()
+```
+
+Example 4.0.0 code:
+```python
+from ably.pubsub.server import ConnectionState, ConnectionStateChange, PresenceMessage, RealtimeChannel
+
+def on_state(change: ConnectionStateChange) -> None:
+    if change.current == ConnectionState.FAILED:
+        ...
+
+async def members(channel: RealtimeChannel) -> list[PresenceMessage]:
+    return await channel.presence.get()
+```
+
+`ably.pubsub.server.sync` exports the same names, apart from the realtime client's:
+`ChannelState`, `ChannelStateChange`, `ConnectionState`, `ConnectionEvent`,
+`ConnectionStateChange`, `RealtimeChannel`, `RealtimePresence` and `RealtimeAnnotations`, as
+well as `Connection`, `RealtimeChannels`, `PubSubRealtimeClient` and `create_realtime_client`,
+which it never had. The classes of the objects the synchronous client hands out end in
+`Sync`, so its new names are `ChannelSync`, `PresenceSync`, `HttpAnnotationsSync`,
+`PushAdminSync`, `PushDeviceRegistrationsSync` and `PushChannelSubscriptionsSync`, beside
+`PresenceMessage`, `PresenceAction`, `Stats`, `TokenRequest`, `ChannelDetails`,
+`ChannelStatus`, `ChannelOccupancy`, `ChannelMetrics`, `InvalidArgumentException` and
+`DevicePushDetails` under their plain names:
+
+Example 3.x code:
+```python
+from ably.sync.rest.channel import ChannelSync
+from ably.sync.types.presence import PresenceMessage
+```
+
+Example 4.0.0 code:
+```python
+from ably.pubsub.server.sync import ChannelSync, PresenceMessage
+```
+
 ## Version 2.x to 3.0.0
 
 The 3.0.0 version of ably-python introduces several breaking changes to improve the realtime experience and align the API with the Ably specification. These include:

ably/pubsub/realtime/presence.py

@@ -215,12 +215,12 @@ async def _enter_or_update_client(
             ConnectionState.DISCONNECTED
         ]:
             raise AblyException(
-                f'Unable to {PresenceAction._action_name(action).lower()} presence channel; '
+                f'Unable to {_action_name(action)} presence channel; '
                 f'connection state = {channel.ably.connection.state}',
                 400, 90001
             )
 
-        action_name = PresenceAction._action_name(action).lower()
+        action_name = _action_name(action)
 
         log.info(
             f'RealtimePresence.{action_name}(): '
@@ -590,7 +590,7 @@ def set_presence(
 
         # Broadcast messages to subscribers
         for presence in broadcast_messages:
-            action_name = PresenceAction._action_name(presence.action).lower()
+            action_name = _action_name(presence.action)
             self._subscriptions._emit(action_name, presence)
 
     def on_attached(self, has_presence: bool = False) -> None:
@@ -774,18 +774,9 @@ def _fail_pending_presence(self, error: AblyException | None = None) -> None:
                 item['future'].set_exception(exception)
 
 
-# Helper for PresenceAction to convert action to string
-def _action_name_impl(action: int) -> str:
-    """Convert presence action to string name."""
-    names = {
-        PresenceAction.ABSENT: 'absent',
-        PresenceAction.PRESENT: 'present',
-        PresenceAction.ENTER: 'enter',
-        PresenceAction.LEAVE: 'leave',
-        PresenceAction.UPDATE: 'update',
-    }
-    return names.get(action, f'unknown({action})')
-
-
-# Monkey-patch the helper onto PresenceAction
-PresenceAction._action_name = staticmethod(_action_name_impl)
+def _action_name(action) -> str:
+    """The lowercase name of a presence action, which is the event it is emitted as."""
+    try:
+        return PresenceAction(action).name.lower()
+    except ValueError:
+        return f'unknown({action})'

ably/pubsub/scripts/unasync.py

@@ -4,12 +4,21 @@
 
 import tokenize_rt
 
+# Classes whose generated flavour takes a `Sync` suffix: the clients, the handles the HTTP
+# surface hands out, and the result wrappers whose methods it awaits. Data types, enums and
+# exceptions keep their names. A class here also changes the name its private attributes
+# are mangled under, so a `_<Class>__attr` written outside the class needs its own entry in
+# _TOKEN_REPLACE below.
 rename_classes = [
     "DefaultPubSubHttpClient",
     "Push",
     "PushAdmin",
+    "PushDeviceRegistrations",
+    "PushChannelSubscriptions",
     "Channel",
     "Channels",
+    "Presence",
+    "HttpAnnotations",
     "Auth",
     "Http",
     "PaginatedResult",

ably/pubsub/server/__init__.py

@@ -11,6 +11,12 @@
 :class:`~ably.pubsub.prototypes.PubSubHttpClient` and
 :class:`~ably.pubsub.prototypes.PubSubRealtimeClient`.
 
+The types a client hands out or accepts are exported here too: the messages,
+states and results it returns, and the classes of the objects it hands out,
+such as :class:`RealtimeChannel` and :class:`Presence`, for annotations and
+``isinstance`` checks. Those objects come from the client; construct them
+through it rather than directly.
+
 This is the public API of the ``ably-pubsub-server`` distribution. Both
 ``ably`` and ``ably.pubsub`` are PEP 420 namespace packages shared with the
 other ``ably-*`` distributions, so neither carries an ``__init__.py`` of its
@@ -19,13 +25,18 @@
 from :mod:`ably.pubsub.server.liveobjects` for LiveObjects.
 """
 
+from ably.pubsub.http.annotations import HttpAnnotations
 from ably.pubsub.http.auth import Auth
+from ably.pubsub.http.channel import Channel
 from ably.pubsub.http.channel import Channels as HttpChannels
 from ably.pubsub.http.http import DefaultPubSubHttpClient as _DefaultPubSubHttpClient
-from ably.pubsub.http.push import Push
+from ably.pubsub.http.push import Push, PushAdmin, PushChannelSubscriptions, PushDeviceRegistrations
 from ably.pubsub.prototypes import PubSubHttpClient, PubSubRealtimeClient
+from ably.pubsub.realtime.annotations import RealtimeAnnotations
 from ably.pubsub.realtime.channel import Channels as RealtimeChannels
+from ably.pubsub.realtime.channel import RealtimeChannel
 from ably.pubsub.realtime.connection import Connection
+from ably.pubsub.realtime.presence import RealtimePresence
 from ably.pubsub.realtime.realtime import DefaultPubSubRealtimeClient as _DefaultPubSubRealtimeClient
 from ably.pubsub.request.paginatedresult import HttpPaginatedResponse, PaginatedResult
 from ably.pubsub.types.annotation import Annotation, AnnotationAction
@@ -38,17 +49,28 @@
     BatchResult,
 )
 from ably.pubsub.types.capability import Capability
+from ably.pubsub.types.channeldetails import ChannelDetails, ChannelMetrics, ChannelOccupancy, ChannelStatus
 from ably.pubsub.types.channelmode import ChannelMode
 from ably.pubsub.types.channeloptions import ChannelOptions
+from ably.pubsub.types.channelstate import ChannelState, ChannelStateChange
 from ably.pubsub.types.channelsubscription import PushChannelSubscription
-from ably.pubsub.types.device import DeviceDetails
+from ably.pubsub.types.connectionstate import ConnectionEvent, ConnectionState, ConnectionStateChange
+from ably.pubsub.types.device import DeviceDetails, DevicePushDetails
 from ably.pubsub.types.message import Message, MessageAction, MessageVersion
 from ably.pubsub.types.operations import MessageOperation, PublishResult, UpdateDeleteResult
 from ably.pubsub.types.options import Options, VCDiffDecoder
+from ably.pubsub.types.presence import Presence, PresenceAction, PresenceMessage
+from ably.pubsub.types.stats import Stats
 from ably.pubsub.types.tokendetails import TokenDetails
+from ably.pubsub.types.tokenrequest import TokenRequest
 from ably.pubsub.util.construction import factory_construction
 from ably.pubsub.util.crypto import CipherParams, generate_random_key, get_default_params
-from ably.pubsub.util.exceptions import AblyAuthException, AblyException, IncompatibleClientIdException
+from ably.pubsub.util.exceptions import (
+    AblyAuthException,
+    AblyException,
+    IncompatibleClientIdException,
+    InvalidArgumentException,
+)
 from ably.pubsub.vcdiff.defaultvcdiffdecoder import AblyVCDiffDecoder
 from ably.pubsub.version import api_version, lib_version
 
@@ -275,27 +297,51 @@ def create_realtime_client(**kwargs) -> PubSubRealtimeClient:
     'BatchPublishSuccessResult',
     'BatchResult',
     'Capability',
+    'Channel',
+    'ChannelDetails',
+    'ChannelMetrics',
     'ChannelMode',
+    'ChannelOccupancy',
     'ChannelOptions',
+    'ChannelState',
+    'ChannelStateChange',
+    'ChannelStatus',
     'CipherParams',
     'Connection',
+    'ConnectionEvent',
+    'ConnectionState',
+    'ConnectionStateChange',
     'DeviceDetails',
+    'DevicePushDetails',
+    'HttpAnnotations',
     'HttpChannels',
     'HttpPaginatedResponse',
     'IncompatibleClientIdException',
+    'InvalidArgumentException',
     'Message',
     'MessageAction',
     'MessageOperation',
     'MessageVersion',
     'Options',
     'PaginatedResult',
+    'Presence',
+    'PresenceAction',
+    'PresenceMessage',
     'PubSubHttpClient',
     'PubSubRealtimeClient',
     'PublishResult',
     'Push',
+    'PushAdmin',
     'PushChannelSubscription',
+    'PushChannelSubscriptions',
+    'PushDeviceRegistrations',
+    'RealtimeAnnotations',
+    'RealtimeChannel',
     'RealtimeChannels',
+    'RealtimePresence',
+    'Stats',
     'TokenDetails',
+    'TokenRequest',
     'UpdateDeleteResult',
     'VCDiffDecoder',
     'api_version',