pondsocket-client 0.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,12 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.egg-info/
6
+ .pytest_cache/
7
+ .mypy_cache/
8
+ .ruff_cache/
9
+ build/
10
+ dist/
11
+ .coverage
12
+ htmlcov/
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.4
2
+ Name: pondsocket-client
3
+ Version: 0.0.1
4
+ Summary: PondSocket Python client — connect to a PondSocket server from Python.
5
+ Author: eleven-am
6
+ License: GPL-3.0-or-later
7
+ Requires-Python: >=3.11
8
+ Requires-Dist: pondsocket-common<0.1.0,>=0.0.1
9
+ Requires-Dist: websockets>=13
10
+ Description-Content-Type: text/markdown
11
+
12
+ # pondsocket-client
13
+
14
+ Python client for the [PondSocket](../pondsocket/) server. Connects to PondSocket servers (Python, Go, or TypeScript implementation) over WebSocket.
15
+
16
+ Modeled after the JavaScript client architecture (`@eleven-am/pondsocket-client`) rather than the Go one — the JS client fixes several bugs the Go client has (see [Parity notes](#parity-notes) below).
17
+
18
+ ## Install
19
+
20
+ ```
21
+ pip install pondsocket-client
22
+ ```
23
+
24
+ ## Quick start
25
+
26
+ ```python
27
+ import asyncio
28
+ from pondsocket_client import PondClient
29
+
30
+
31
+ async def main() -> None:
32
+ client = PondClient("ws://localhost:8000/ws", {"token": "secret"})
33
+ await client.connect()
34
+
35
+ channel = client.create_channel("/chat/42", {"username": "alice"})
36
+ channel.on_message_event("message", lambda m: print(m.payload))
37
+ channel.on_join(lambda user: print("joined:", user))
38
+ channel.join()
39
+
40
+ channel.send_message("message", {"text": "hello"})
41
+
42
+ response = await channel.send_for_response("ping", {"text": "abc"})
43
+ print("got pong:", response)
44
+
45
+ await asyncio.sleep(10)
46
+ await client.disconnect()
47
+
48
+
49
+ asyncio.run(main())
50
+ ```
51
+
52
+ ## Architecture
53
+
54
+ ```
55
+ BaseClient (abstract)
56
+ ├── channel registry
57
+ ├── inbound event routing (ACK / UNAUTHORIZED / CONNECTION / per-channel)
58
+ ├── connection state machine: DISCONNECTED → CONNECTING → CONNECTED
59
+ └── exponential reconnect
60
+
61
+ WebSocketClient(BaseClient) (abstract)
62
+ ├── opens via `websockets` library
63
+ └── receive loop pumps inbound to BaseClient
64
+
65
+ PondClient(WebSocketClient) (concrete)
66
+ ├── URL handling (http → ws, https → wss)
67
+ └── appends query-string params
68
+ ```
69
+
70
+ The `Channel` class holds the per-channel state machine (IDLE → JOINING → JOINED → STALLED → CLOSED/DECLINED), a bounded outbound queue (drops oldest on overflow), and a `send_for_response` that correlates inbound replies by `requestId`.
71
+
72
+ ## Connection states
73
+
74
+ Subscribe via `client.on_connection_change(handler)`:
75
+
76
+ | State | When |
77
+ |---|---|
78
+ | `DISCONNECTED` | initial; after disconnect or socket close |
79
+ | `CONNECTING` | `connect()` called; socket handshake in flight |
80
+ | `CONNECTED` | socket open AND server sent the CONNECTION event |
81
+
82
+ ## Channel states
83
+
84
+ Subscribe via `channel.on_channel_state_change(handler)`:
85
+
86
+ | State | Meaning |
87
+ |---|---|
88
+ | `IDLE` | created but `join()` not called |
89
+ | `JOINING` | `join()` called; awaiting ACKNOWLEDGE |
90
+ | `JOINED` | server acknowledged; messages flow |
91
+ | `STALLED` | socket dropped while JOINED; will rejoin on reconnect |
92
+ | `CLOSED` | `leave()` called |
93
+ | `DECLINED` | server sent UNAUTHORIZED; channel is terminal — create a new one |
94
+
95
+ ## Parity notes
96
+
97
+ Compared to the Go client (`go/pondsocket-client/`):
98
+
99
+ | Behavior | Go | Python |
100
+ |---|---|---|
101
+ | `send_for_response` correlation | event name (buggy) | `requestId` (correct) |
102
+ | Reconnect backoff | linear despite comment | true exponential, capped |
103
+ | `UNAUTHORIZED` handling | not implemented | → `DECLINED` state |
104
+ | Connection state | bool (no CONNECTING) | three-state enum |
105
+ | Outbound queue | unbounded | bounded, drops oldest |
106
+ | Join while disconnected | dropped silently | deferred until CONNECTED |
107
+
108
+ The Python client follows the JS client design where the two diverge.
109
+
110
+ ## Public API
111
+
112
+ ```python
113
+ from pondsocket_client import (
114
+ PondClient,
115
+ Channel,
116
+ ConnectionState,
117
+ ClientOptions,
118
+ ResponseTimeoutError,
119
+ )
120
+ ```
121
+
122
+ Also exposed for adapter authors: `BaseClient`, `WebSocketClient`, `Publisher` (type alias).
123
+
124
+ ## License
125
+
126
+ GPL-3.0-or-later.
@@ -0,0 +1,115 @@
1
+ # pondsocket-client
2
+
3
+ Python client for the [PondSocket](../pondsocket/) server. Connects to PondSocket servers (Python, Go, or TypeScript implementation) over WebSocket.
4
+
5
+ Modeled after the JavaScript client architecture (`@eleven-am/pondsocket-client`) rather than the Go one — the JS client fixes several bugs the Go client has (see [Parity notes](#parity-notes) below).
6
+
7
+ ## Install
8
+
9
+ ```
10
+ pip install pondsocket-client
11
+ ```
12
+
13
+ ## Quick start
14
+
15
+ ```python
16
+ import asyncio
17
+ from pondsocket_client import PondClient
18
+
19
+
20
+ async def main() -> None:
21
+ client = PondClient("ws://localhost:8000/ws", {"token": "secret"})
22
+ await client.connect()
23
+
24
+ channel = client.create_channel("/chat/42", {"username": "alice"})
25
+ channel.on_message_event("message", lambda m: print(m.payload))
26
+ channel.on_join(lambda user: print("joined:", user))
27
+ channel.join()
28
+
29
+ channel.send_message("message", {"text": "hello"})
30
+
31
+ response = await channel.send_for_response("ping", {"text": "abc"})
32
+ print("got pong:", response)
33
+
34
+ await asyncio.sleep(10)
35
+ await client.disconnect()
36
+
37
+
38
+ asyncio.run(main())
39
+ ```
40
+
41
+ ## Architecture
42
+
43
+ ```
44
+ BaseClient (abstract)
45
+ ├── channel registry
46
+ ├── inbound event routing (ACK / UNAUTHORIZED / CONNECTION / per-channel)
47
+ ├── connection state machine: DISCONNECTED → CONNECTING → CONNECTED
48
+ └── exponential reconnect
49
+
50
+ WebSocketClient(BaseClient) (abstract)
51
+ ├── opens via `websockets` library
52
+ └── receive loop pumps inbound to BaseClient
53
+
54
+ PondClient(WebSocketClient) (concrete)
55
+ ├── URL handling (http → ws, https → wss)
56
+ └── appends query-string params
57
+ ```
58
+
59
+ The `Channel` class holds the per-channel state machine (IDLE → JOINING → JOINED → STALLED → CLOSED/DECLINED), a bounded outbound queue (drops oldest on overflow), and a `send_for_response` that correlates inbound replies by `requestId`.
60
+
61
+ ## Connection states
62
+
63
+ Subscribe via `client.on_connection_change(handler)`:
64
+
65
+ | State | When |
66
+ |---|---|
67
+ | `DISCONNECTED` | initial; after disconnect or socket close |
68
+ | `CONNECTING` | `connect()` called; socket handshake in flight |
69
+ | `CONNECTED` | socket open AND server sent the CONNECTION event |
70
+
71
+ ## Channel states
72
+
73
+ Subscribe via `channel.on_channel_state_change(handler)`:
74
+
75
+ | State | Meaning |
76
+ |---|---|
77
+ | `IDLE` | created but `join()` not called |
78
+ | `JOINING` | `join()` called; awaiting ACKNOWLEDGE |
79
+ | `JOINED` | server acknowledged; messages flow |
80
+ | `STALLED` | socket dropped while JOINED; will rejoin on reconnect |
81
+ | `CLOSED` | `leave()` called |
82
+ | `DECLINED` | server sent UNAUTHORIZED; channel is terminal — create a new one |
83
+
84
+ ## Parity notes
85
+
86
+ Compared to the Go client (`go/pondsocket-client/`):
87
+
88
+ | Behavior | Go | Python |
89
+ |---|---|---|
90
+ | `send_for_response` correlation | event name (buggy) | `requestId` (correct) |
91
+ | Reconnect backoff | linear despite comment | true exponential, capped |
92
+ | `UNAUTHORIZED` handling | not implemented | → `DECLINED` state |
93
+ | Connection state | bool (no CONNECTING) | three-state enum |
94
+ | Outbound queue | unbounded | bounded, drops oldest |
95
+ | Join while disconnected | dropped silently | deferred until CONNECTED |
96
+
97
+ The Python client follows the JS client design where the two diverge.
98
+
99
+ ## Public API
100
+
101
+ ```python
102
+ from pondsocket_client import (
103
+ PondClient,
104
+ Channel,
105
+ ConnectionState,
106
+ ClientOptions,
107
+ ResponseTimeoutError,
108
+ )
109
+ ```
110
+
111
+ Also exposed for adapter authors: `BaseClient`, `WebSocketClient`, `Publisher` (type alias).
112
+
113
+ ## License
114
+
115
+ GPL-3.0-or-later.
@@ -0,0 +1,22 @@
1
+ [project]
2
+ name = "pondsocket-client"
3
+ version = "0.0.1"
4
+ description = "PondSocket Python client — connect to a PondSocket server from Python."
5
+ readme = "README.md"
6
+ requires-python = ">=3.11"
7
+ license = { text = "GPL-3.0-or-later" }
8
+ authors = [{ name = "eleven-am" }]
9
+ dependencies = [
10
+ "pondsocket-common>=0.0.1,<0.1.0",
11
+ "websockets>=13",
12
+ ]
13
+
14
+ [build-system]
15
+ requires = ["hatchling"]
16
+ build-backend = "hatchling.build"
17
+
18
+ [tool.hatch.build.targets.wheel]
19
+ packages = ["src/pondsocket_client"]
20
+
21
+ [tool.uv.sources]
22
+ pondsocket-common = { workspace = true }
@@ -0,0 +1,52 @@
1
+ from __future__ import annotations
2
+
3
+ from ._base import BaseClient, ConnectionStateHandler, ErrorHandler
4
+ from ._channel import (
5
+ Channel,
6
+ ChannelStateHandler,
7
+ MessageHandler,
8
+ PresenceHandler,
9
+ PresenceUpdateHandler,
10
+ ResponseTimeoutError,
11
+ UsersChangeHandler,
12
+ )
13
+ from ._websocket import WebSocketClient
14
+ from .client import PondClient
15
+ from .types import (
16
+ DEFAULT_BASE_RECONNECT_DELAY,
17
+ DEFAULT_CONNECTION_TIMEOUT,
18
+ DEFAULT_MAX_QUEUE_SIZE,
19
+ DEFAULT_MAX_RECONNECT_DELAY,
20
+ DEFAULT_PING_INTERVAL,
21
+ DEFAULT_RESPONSE_TIMEOUT,
22
+ ClientOptions,
23
+ ConnectionState,
24
+ Publisher,
25
+ )
26
+
27
+ __version__ = "0.0.1"
28
+
29
+ __all__ = [
30
+ "DEFAULT_BASE_RECONNECT_DELAY",
31
+ "DEFAULT_CONNECTION_TIMEOUT",
32
+ "DEFAULT_MAX_QUEUE_SIZE",
33
+ "DEFAULT_MAX_RECONNECT_DELAY",
34
+ "DEFAULT_PING_INTERVAL",
35
+ "DEFAULT_RESPONSE_TIMEOUT",
36
+ "BaseClient",
37
+ "Channel",
38
+ "ChannelStateHandler",
39
+ "ClientOptions",
40
+ "ConnectionState",
41
+ "ConnectionStateHandler",
42
+ "ErrorHandler",
43
+ "MessageHandler",
44
+ "PondClient",
45
+ "PresenceHandler",
46
+ "PresenceUpdateHandler",
47
+ "Publisher",
48
+ "ResponseTimeoutError",
49
+ "UsersChangeHandler",
50
+ "WebSocketClient",
51
+ "__version__",
52
+ ]
@@ -0,0 +1,181 @@
1
+ from __future__ import annotations
2
+
3
+ import abc
4
+ import asyncio
5
+ from collections.abc import Callable
6
+ from typing import TypeAlias
7
+
8
+ from pondsocket_common import (
9
+ BehaviorSubject,
10
+ ChannelEvent,
11
+ ClientMessage,
12
+ JoinParams,
13
+ Subject,
14
+ Unsubscribe,
15
+ ValidationError,
16
+ parse_channel_event,
17
+ )
18
+
19
+ from ._channel import Channel
20
+ from .types import ClientOptions, ConnectionState
21
+
22
+ ConnectionStateHandler: TypeAlias = Callable[[ConnectionState], None]
23
+ ErrorHandler: TypeAlias = Callable[[BaseException], None]
24
+
25
+
26
+ class BaseClient(abc.ABC):
27
+ __slots__ = (
28
+ "_broadcaster",
29
+ "_channels",
30
+ "_connection_state",
31
+ "_disconnecting",
32
+ "_errors",
33
+ "_options",
34
+ "_reconnect_attempts",
35
+ "_reconnect_task",
36
+ "_tasks",
37
+ )
38
+
39
+ def __init__(self, options: ClientOptions | None = None) -> None:
40
+ self._options = options or ClientOptions()
41
+ self._channels: dict[str, Channel] = {}
42
+ self._broadcaster: Subject[ChannelEvent] = Subject()
43
+ self._connection_state: BehaviorSubject[ConnectionState] = BehaviorSubject(
44
+ ConnectionState.DISCONNECTED
45
+ )
46
+ self._errors: Subject[BaseException] = Subject()
47
+ self._reconnect_attempts: int = 0
48
+ self._reconnect_task: asyncio.Task[None] | None = None
49
+ self._disconnecting: bool = False
50
+ self._tasks: set[asyncio.Task[None]] = set()
51
+ self._broadcaster.subscribe(self._route_event)
52
+
53
+ @property
54
+ def options(self) -> ClientOptions:
55
+ return self._options
56
+
57
+ def get_state(self) -> ConnectionState:
58
+ return self._connection_state.value or ConnectionState.DISCONNECTED
59
+
60
+ def create_channel(
61
+ self, name: str, params: JoinParams | None = None
62
+ ) -> Channel:
63
+ existing = self._channels.get(name)
64
+ if existing is not None and existing.channel_state.value not in ("CLOSED", "DECLINED"):
65
+ return existing
66
+ channel = Channel(
67
+ name=name,
68
+ params=params,
69
+ publisher=self._publish_outbound,
70
+ connection_state=self._connection_state,
71
+ max_queue_size=self._options.max_queue_size,
72
+ response_timeout=self._options.response_timeout,
73
+ )
74
+ self._channels[name] = channel
75
+ return channel
76
+
77
+ def on_connection_change(self, callback: ConnectionStateHandler) -> Unsubscribe:
78
+ return self._connection_state.subscribe(callback)
79
+
80
+ def on_error(self, callback: ErrorHandler) -> Unsubscribe:
81
+ return self._errors.subscribe(callback)
82
+
83
+ async def connect(self) -> None:
84
+ self._disconnecting = False
85
+ if self.get_state() != ConnectionState.DISCONNECTED:
86
+ return
87
+ self._connection_state.publish(ConnectionState.CONNECTING)
88
+ try:
89
+ await self._open_transport()
90
+ except Exception as exc:
91
+ self._errors.publish(exc)
92
+ self._connection_state.publish(ConnectionState.DISCONNECTED)
93
+ self._schedule_reconnect()
94
+
95
+ async def disconnect(self) -> None:
96
+ self._disconnecting = True
97
+ if self._reconnect_task is not None and not self._reconnect_task.done():
98
+ self._reconnect_task.cancel()
99
+ self._reconnect_task = None
100
+ await self._close_transport()
101
+ self._connection_state.publish(ConnectionState.DISCONNECTED)
102
+ for channel in list(self._channels.values()):
103
+ channel._force_close()
104
+ self._channels.clear()
105
+
106
+ def _mark_connected(self) -> None:
107
+ self._reconnect_attempts = 0
108
+ self._connection_state.publish(ConnectionState.CONNECTED)
109
+
110
+ def _mark_disconnected(self) -> None:
111
+ self._connection_state.publish(ConnectionState.DISCONNECTED)
112
+ if not self._disconnecting:
113
+ self._schedule_reconnect()
114
+
115
+ def _handle_inbound_text(self, text: str) -> None:
116
+ try:
117
+ import json
118
+
119
+ data = json.loads(text)
120
+ except json.JSONDecodeError as e:
121
+ self._errors.publish(e)
122
+ return
123
+ try:
124
+ event = parse_channel_event(data)
125
+ except ValidationError as e:
126
+ self._errors.publish(e)
127
+ return
128
+ self._broadcaster.publish(event)
129
+
130
+ def _route_event(self, event: ChannelEvent) -> None:
131
+ channel = self._channels.get(event.channel_name)
132
+ if channel is None:
133
+ return
134
+ channel.handle_event(event)
135
+
136
+ def _schedule_reconnect(self) -> None:
137
+ if self._disconnecting:
138
+ return
139
+ max_attempts = self._options.max_reconnect_attempts
140
+ if max_attempts >= 0 and self._reconnect_attempts >= max_attempts:
141
+ return
142
+ if self._reconnect_task is not None and not self._reconnect_task.done():
143
+ return
144
+ delay = min(
145
+ self._options.base_reconnect_delay * (2 ** self._reconnect_attempts),
146
+ self._options.max_reconnect_delay,
147
+ )
148
+ self._reconnect_attempts += 1
149
+ self._reconnect_task = asyncio.create_task(self._reconnect_after(delay))
150
+ self._reconnect_task.add_done_callback(self._on_reconnect_task_done)
151
+
152
+ def _on_reconnect_task_done(self, _task: asyncio.Task[None]) -> None:
153
+ self._reconnect_task = None
154
+
155
+ async def _reconnect_after(self, delay: float) -> None:
156
+ try:
157
+ await asyncio.sleep(delay)
158
+ except asyncio.CancelledError:
159
+ return
160
+ if self._disconnecting:
161
+ return
162
+ await self.connect()
163
+
164
+ async def _publish_outbound(self, message: ClientMessage) -> None:
165
+ await self._send_outbound(message)
166
+
167
+ @abc.abstractmethod
168
+ async def _open_transport(self) -> None: ...
169
+
170
+ @abc.abstractmethod
171
+ async def _close_transport(self) -> None: ...
172
+
173
+ @abc.abstractmethod
174
+ async def _send_outbound(self, message: ClientMessage) -> None: ...
175
+
176
+
177
+ __all__ = [
178
+ "BaseClient",
179
+ "ConnectionStateHandler",
180
+ "ErrorHandler",
181
+ ]