phoenix-channels-python-client 0.2.4__py3-none-any.whl → 0.2.5__py3-none-any.whl

phoenix_channels_python_client/__init__.py

@@ -19,7 +19,7 @@ from phoenix_channels_python_client.protocol_handler import (
 )
 from phoenix_channels_python_client.utils import setup_logging
 
-__version__ = "0.2.4"
+__version__ = "0.2.5"
 __author__ = "Phoenix Channels Python Client"
 
 __all__ = [

phoenix_channels_python_client/client.py

@@ -25,6 +25,7 @@ from phoenix_channels_python_client.reconnect_controller import ReconnectControl
 from phoenix_channels_python_client.supervisor import SupervisorMixin
 from phoenix_channels_python_client.topic_runtime import TopicRuntimeMixin
 from phoenix_channels_python_client.topic_subscription import TopicSubscription
+from phoenix_channels_python_client.utils import cancel_and_wait
 
 logger = logging.getLogger(__name__)
 
@@ -145,6 +146,7 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._connected_event = asyncio.Event()
         self._conn_generation = 0
         self._supervisor_task: asyncio.Task[None] | None = None
+        self._shutdown_task: asyncio.Task[None] | None = None
         self._message_routing_task: asyncio.Task[None] | None = None
         self._initial_connection_future: asyncio.Future[None] | None = None
         self._rapid_disconnects: deque[float] = deque()
@@ -157,13 +159,26 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self._on_heartbeat_ack = on_heartbeat_ack
         self._forced_close_pending = False
 
+    @property
+    def _active_shutdown(self) -> asyncio.Task[None] | None:
+        task = self._shutdown_task
+        return task if task is not None and not task.done() else None
+
+    @property
+    def _is_fully_closed(self) -> bool:
+        return (
+            self._state == ClientState.CLOSED
+            and not self._topic_subscriptions
+            and self.connection is None
+        )
+
     @staticmethod
     def reconnect_policy_is_invalid(policy: ReconnectPolicy) -> bool:
         return reconnect_policy_is_invalid(policy)
 
     async def __aenter__(self) -> PHXChannelsClient:
         self.logger.debug("Entering PHXChannelsClient context")
-        if self._state != ClientState.CLOSED:
+        if self._state != ClientState.CLOSED or self._active_shutdown is not None:
             raise PHXConnectionError("Client is already running")
 
         self._shutdown_event.clear()
@@ -192,51 +207,52 @@ class PHXChannelsClient(SupervisorMixin, TopicRuntimeMixin, ReconnectControllerM
         self.logger.debug("Leaving PHXChannelsClient context")
         await self.shutdown("Leaving PHXChannelsClient context")
 
-    async def shutdown(
-        self,
-        reason: str,
-    ) -> None:
-        if (
-            self._state == ClientState.CLOSED
-            and not self._topic_subscriptions
-            and self.connection is None
-        ):
-            return
-
+    async def shutdown(self, reason: str) -> None:
+        task = self._active_shutdown
+        if task is None:
+            if self._is_fully_closed:
+                return
+            task = self._shutdown_task = asyncio.create_task(self._shutdown(reason))
+        # Every caller waits for the same shutdown, and one caller's
+        # cancellation never aborts it.
+        await asyncio.shield(task)
+
+    async def _shutdown(self, reason: str) -> None:
         self.logger.info("Event loop shutting down! reason=%s", reason)
 
         if self._state not in (ClientState.SHUTTING_DOWN, ClientState.CLOSED):
             self._transition_state(ClientState.SHUTTING_DOWN)
-
         self._shutdown_event.set()
 
-        topics_to_unsubscribe = list(self._topic_subscriptions.keys())
-        if topics_to_unsubscribe:
-            unsubscribe_tasks = [
-                self.unsubscribe_from_topic(topic, _allow_disconnected=True)
-                for topic in topics_to_unsubscribe
-            ]
-            results = await asyncio.gather(*unsubscribe_tasks, return_exceptions=True)
-
-            for topic, result in zip(topics_to_unsubscribe, results, strict=False):
-                if isinstance(result, Exception):
-                    self.logger.warning(
-                        "Failed to unsubscribe from topic %s during shutdown: %s",
-                        topic,
-                        result,
-                    )
-
-        if self._supervisor_task and not self._supervisor_task.done():
-            self._supervisor_task.cancel()
-            try:
-                await self._supervisor_task
-            except asyncio.CancelledError:
-                self.logger.debug("Supervisor task cancelled during shutdown")
-
+        await self._unsubscribe_all()
+        await self._stop_supervisor()
         await self._cleanup_connection()
         self._connected_event.clear()
         self._transition_state(ClientState.CLOSED)
 
+    async def _unsubscribe_all(self) -> None:
+        topics = list(self._topic_subscriptions)
+        results = await asyncio.gather(
+            *(
+                self.unsubscribe_from_topic(topic, _allow_disconnected=True)
+                for topic in topics
+            ),
+            return_exceptions=True,
+        )
+        for topic, result in zip(topics, results, strict=True):
+            if isinstance(result, Exception):
+                self.logger.warning(
+                    "Failed to unsubscribe from topic %s during shutdown: %s",
+                    topic,
+                    result,
+                )
+
+    async def _stop_supervisor(self) -> None:
+        # Cleared, so run_forever() after the stop reports the client isn't running.
+        supervisor, self._supervisor_task = self._supervisor_task, None
+        if supervisor is not None and not supervisor.done():
+            await cancel_and_wait(supervisor)
+
     def _transition_state(self, new_state: ClientState) -> None:
         if self._state == new_state:
             return

phoenix_channels_python_client/shutdown_signals.py

@@ -0,0 +1,119 @@
+"""Process-wide SIGTERM/SIGINT handling shared by every waiting event loop.
+
+Handlers are installed with ``signal.signal`` and the previous handler is put
+back exactly, as ``asyncio.Runner`` does. Signal handlers interrupt main-thread
+code between bytecodes, so nothing here takes a lock: the OS handler table
+decides ownership, the handler never iterates a live container or removes
+entries, and ``_previous`` entries are only ever overwritten.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import signal
+import threading
+from collections.abc import Callable, Generator
+from contextlib import contextmanager
+from types import FrameType
+from typing import Any, NamedTuple
+
+logger = logging.getLogger(__name__)
+
+SHUTDOWN_SIGNALS = (signal.SIGTERM, signal.SIGINT)
+
+# typeshed's signal._HANDLER is private.
+_Handler = Callable[[int, FrameType | None], Any] | int | None
+
+
+class _Waiter(NamedTuple):
+    loop: asyncio.AbstractEventLoop
+    event: asyncio.Event
+
+    @property
+    def live(self) -> bool:
+        return not self.loop.is_closed()
+
+
+# Each waiter maps to the last signal it took, if any.
+_waiters: dict[_Waiter, int | None] = {}
+_previous: dict[int, _Handler] = {}
+
+
+def _on_main_thread() -> bool:
+    return threading.current_thread() is threading.main_thread()
+
+
+def _owned(sig: int) -> bool:
+    return signal.getsignal(sig) is _on_shutdown_signal
+
+
+def _on_shutdown_signal(signum: int, frame: FrameType | None) -> None:
+    live = [waiter for waiter in tuple(_waiters) if waiter.live]
+    for waiter in live:
+        _waiters[waiter] = signum
+        waiter.loop.call_soon_threadsafe(waiter.event.set)
+    # Every waiting loop closed without unwinding: hand the signal back. If a
+    # newer handler chained to this one instead, that handler already has it.
+    if not live and _owned(signum):
+        _restore()
+        signal.raise_signal(signum)
+
+
+def _install() -> bool:
+    try:
+        for sig in SHUTDOWN_SIGNALS:
+            # None means a handler set outside Python, which can't be restored.
+            if not _owned(sig) and signal.getsignal(sig) is not None:
+                _previous[sig] = signal.signal(sig, _on_shutdown_signal)
+    except ValueError:
+        # The main thread can't take signals (embedded interpreter, gh-91880).
+        return False
+    return True
+
+
+def _restore() -> None:
+    for sig in SHUTDOWN_SIGNALS:
+        if _owned(sig):  # never overwrite a handler installed after ours
+            signal.signal(sig, _previous[sig])
+
+
+def _unregister(waiter: _Waiter) -> int | None:
+    """Drop ``waiter``, restoring the handlers if it was the last one.
+
+    Returns the last signal it took, if any.
+    """
+    received = _waiters.pop(waiter, None)
+    for orphan in [other for other in tuple(_waiters) if not other.live]:
+        _waiters.pop(orphan, None)  # a closed loop never blocks a restore
+    # GC may finalize an orphaned body off the main thread, where
+    # signal.signal raises.
+    if not _waiters and _on_main_thread():
+        _restore()
+    return received
+
+
+@contextmanager
+def handle_shutdown_signals(event: asyncio.Event) -> Generator[None, None, None]:
+    """Set ``event`` on SIGTERM/SIGINT while inside.
+
+    A signal is consumed only if the body completes with ``event`` set, and the
+    caller must then act on it. Any other signal taken is handed back on exit.
+    """
+    if not _on_main_thread():
+        logger.debug("Signal handlers not available off the main thread")
+        yield
+        return
+    waiter = _Waiter(asyncio.get_running_loop(), event)
+    consumed = False
+    try:
+        # Register before installing so a signal mid-install is never dropped.
+        _waiters[waiter] = None
+        if not _install():
+            logger.debug("Signal handlers not available in this interpreter")
+        yield
+        consumed = event.is_set()
+    finally:
+        received = _unregister(waiter)
+        if received is not None and not consumed and not _owned(received):
+            signal.raise_signal(received)  # nobody acted on it: hand it back

phoenix_channels_python_client/supervisor.py

@@ -3,10 +3,9 @@ from __future__ import annotations
 import asyncio
 import inspect
 import logging
-import signal
 from collections import deque
 from collections.abc import Awaitable, Callable
-from contextlib import suppress
+from contextlib import nullcontext
 from typing import Protocol, cast
 
 from websockets import ClientConnection, connect
@@ -24,8 +23,9 @@ from phoenix_channels_python_client.phx_messages import (
     Event,
 )
 from phoenix_channels_python_client.protocol_handler import PHXProtocolHandler
+from phoenix_channels_python_client.shutdown_signals import handle_shutdown_signals
 from phoenix_channels_python_client.topic_subscription import TopicSubscription
-from phoenix_channels_python_client.utils import make_message
+from phoenix_channels_python_client.utils import cancel_and_wait, make_message
 
 # RFC 6455 §7.4.2 private-use range (4000-4999, unregistrable); outside
 # _classify_disconnect's specially-handled codes, so a forced close
@@ -235,6 +235,10 @@ class SupervisorMixin:
                     continue
 
                 self.connection = connection
+                if self._shutdown_event.is_set():
+                    # shutdown() began during the handshake; its own cleanup
+                    # closes this socket.
+                    break
                 self._conn_generation += 1
                 generation = self._conn_generation
                 self._connected_event.set()
@@ -288,7 +292,6 @@ class SupervisorMixin:
                     routing_error=routing_error,
                 )
                 forced_close = self._forced_close_pending
-                self._forced_close_pending = False
 
                 await self._cleanup_connection()
 
@@ -351,6 +354,7 @@ class SupervisorMixin:
                 delay = runtime_deps._apply_disconnect_delay_override(delay, decision)
                 await self._wait_for_shutdown_or_timeout(delay)
 
+        finally:
             if (
                 self._initial_connection_future
                 and not self._initial_connection_future.done()
@@ -360,8 +364,6 @@ class SupervisorMixin:
                         "Connection supervisor stopped before connecting"
                     )
                 )
-
-        finally:
             self._connected_event.clear()
             if self._state != ClientState.SHUTTING_DOWN:
                 runtime_deps._transition_state(ClientState.CLOSED)
@@ -374,75 +376,71 @@ class SupervisorMixin:
 
     async def _cleanup_connection(self) -> None:
         connection = self.connection
+        running = [
+            task
+            for task in (self._heartbeat_task, self._message_routing_task)
+            if task is not None and not task.done()
+        ]
         self.connection = None
-        self._connected_event.clear()
-
-        if self._heartbeat_task and not self._heartbeat_task.done():
-            self._heartbeat_task.cancel()
-            with suppress(asyncio.CancelledError):
-                await self._heartbeat_task
         self._heartbeat_task = None
-        self._pending_heartbeat_ref = None
-
-        if self._message_routing_task and not self._message_routing_task.done():
-            self._message_routing_task.cancel()
-            with suppress(asyncio.CancelledError):
-                await self._message_routing_task
-
         self._message_routing_task = None
+        self._pending_heartbeat_ref = None
+        self._connected_event.clear()
+        self._forced_close_pending = False
 
-        if connection is not None:
-            try:
-                await connection.close()
-            except Exception:
-                self.logger.exception("Failed while closing websocket connection")
+        try:
+            await cancel_and_wait(*running)
+        finally:
+            # Close the socket even if the caller is cancelled meanwhile.
+            if connection is not None:
+                await self._close_websocket(connection)
 
-    async def run_forever(self) -> None:
+    async def _close_websocket(self, connection: ClientConnection) -> None:
+        try:
+            await connection.close()
+        except Exception:
+            self.logger.exception("Failed while closing websocket connection")
+
+    async def run_forever(self, *, install_signal_handlers: bool = True) -> None:
+        """Wait until the client stops, then raise why if it failed.
+
+        With ``install_signal_handlers`` (the default), SIGTERM and SIGINT shut
+        the client down. The handlers in place before the call are restored once
+        the last waiting ``run_forever()`` stops waiting, so a second signal
+        during the shutdown reaches them. A host handler registered with
+        ``loop.add_signal_handler`` before the call also fires; one registered
+        during it replaces ours. Hosts that own their process signals pass
+        ``False`` and schedule ``shutdown()`` on the client's loop from their
+        own handler.
+        """
         runtime_deps = cast(_SupervisorRuntimeDeps, self)
-        if self._supervisor_task is None:
+        supervisor = self._supervisor_task
+        if supervisor is None:
             raise PHXConnectionError(
                 "Client is not connected. Use 'async with' context manager."
             )
 
-        shutdown_signal = asyncio.Event()
-
-        def signal_handler(*_: object) -> None:
-            shutdown_signal.set()
-
-        loop = asyncio.get_running_loop()
-        signal_handlers_registered = False
-        try:
-            for sig in (signal.SIGTERM, signal.SIGINT):
-                loop.add_signal_handler(sig, signal_handler)
-            signal_handlers_registered = True
-        except (RuntimeError, NotImplementedError):
-            self.logger.debug(
-                "Signal handlers not available (not running on main thread)"
-            )
-
-        shutdown_task = asyncio.create_task(shutdown_signal.wait())
-
-        try:
-            done, pending = await asyncio.wait(
-                [shutdown_task, self._supervisor_task],
-                return_when=asyncio.FIRST_COMPLETED,
-            )
-
-            for task in pending:
-                task.cancel()
-                with suppress(asyncio.CancelledError):
-                    await task
-
-            if shutdown_task in done:
-                await runtime_deps.shutdown("Signal received")
-                return
-
-            # Supervisor task ended unexpectedly: propagate if it failed.
-            if self._terminal_error is not None:
-                raise self._terminal_error
-            self._supervisor_task.result()
-
-        finally:
-            if signal_handlers_registered:
-                for sig in (signal.SIGTERM, signal.SIGINT):
-                    loop.remove_signal_handler(sig)
+        signaled = asyncio.Event()
+        signals = (
+            handle_shutdown_signals(signaled)
+            if install_signal_handlers
+            else nullcontext()
+        )
+        with signals:
+            signal_wait = asyncio.create_task(signaled.wait())
+            try:
+                await asyncio.wait(
+                    {supervisor, signal_wait}, return_when=asyncio.FIRST_COMPLETED
+                )
+            finally:
+                signal_wait.cancel()
+
+        # No await since leaving the `with`, so this sees `signaled` exactly as
+        # handle_shutdown_signals judged it consumed.
+        if signaled.is_set():
+            await runtime_deps.shutdown("Signal received")
+        if self._terminal_error is not None:
+            raise self._terminal_error
+        if supervisor.cancelled() and self._shutdown_event.is_set():
+            return  # a requested stop
+        supervisor.result()

phoenix_channels_python_client/topic_runtime.py

@@ -4,7 +4,6 @@ import asyncio
 import logging
 from asyncio import Queue
 from collections.abc import Awaitable, Callable
-from contextlib import suppress
 from typing import Any
 
 from websockets import ClientConnection
@@ -24,7 +23,7 @@ from phoenix_channels_python_client.topic_subscription import (
     TopicProcessingState,
     TopicSubscription,
 )
-from phoenix_channels_python_client.utils import make_message
+from phoenix_channels_python_client.utils import cancel_and_wait, make_message
 
 
 class TopicRuntimeMixin:
@@ -274,9 +273,7 @@ class TopicRuntimeMixin:
 
         task = topic_subscription.process_topic_messages_task
         if task and not task.done() and asyncio.current_task() is not task:
-            task.cancel()
-            with suppress(asyncio.CancelledError):
-                await task
+            await cancel_and_wait(task)
 
         self.logger.info("Unregistered topic %s", topic_name)
 
@@ -501,14 +498,10 @@ class TopicRuntimeMixin:
                         "Callback for topic %s did not finish before reconnect; cancelling",
                         topic_name,
                     )
-                    callback_task.cancel()
-                    with suppress(asyncio.CancelledError):
-                        await callback_task
+                    await cancel_and_wait(callback_task)
 
             if previous_task and not previous_task.done():
-                previous_task.cancel()
-                with suppress(asyncio.CancelledError):
-                    await previous_task
+                await cancel_and_wait(previous_task)
 
             topic_subscription.conn_generation = generation
             topic_subscription.join_ref = self._generate_ref()

phoenix_channels_python_client/utils.py

@@ -1,3 +1,4 @@
+import asyncio
 import logging
 from typing import Any, Optional
 
@@ -9,6 +10,8 @@ from phoenix_channels_python_client.phx_messages import (
     PHXMessage,
 )
 
+logger = logging.getLogger(__name__)
+
 
 def parse_event(event: ChannelEvent) -> ChannelEvent:
     try:
@@ -46,6 +49,22 @@ def make_message(
         )
 
 
+async def cancel_and_wait(*futures: asyncio.Future[Any]) -> None:
+    """Cancel ``futures`` and wait until they have all finished.
+
+    Unlike ``suppress(CancelledError)``, the caller's own cancellation still
+    propagates. A failure raised while a future unwinds is logged, not raised.
+    """
+    if not futures:
+        return
+    for future in futures:
+        future.cancel()
+    await asyncio.wait(futures)
+    for future in futures:
+        if not future.cancelled() and (error := future.exception()):
+            logger.error("Failed while being cancelled", exc_info=error)
+
+
 def setup_logging(level: int = logging.INFO) -> None:
     """
     Configure clean logging with timestamps for Phoenix Channels Python Client.

{phoenix_channels_python_client-0.2.4.dist-info → phoenix_channels_python_client-0.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.2.4
+Version: 0.2.5
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -17,14 +17,14 @@ License-File: LICENSE
 Requires-Dist: websockets>=14.2
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4; extra == "dev"
 Requires-Dist: pre-commit>=3.0.0; extra == "dev"
 Requires-Dist: commitizen>=3.13.0; extra == "dev"
 Requires-Dist: pyrefly; extra == "dev"
 Requires-Dist: ruff; extra == "dev"
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
-Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: pytest-asyncio>=1.4; extra == "test"
 Dynamic: license-file
 
 # Phoenix Channels Python Client
@@ -39,7 +39,11 @@ A modern, async Python client library for connecting to [Phoenix Channels](https
 
 ### For Users
 
-Install from source:
+```bash
+pip install phoenix-channels-python-client
+```
+
+Or from source:
 
 ```bash
 git clone https://github.com/band-ai/phoenix-channels-python-client.git
@@ -65,7 +69,6 @@ pip install -e ".[dev]"
 Run tests:
 
 ```bash
-pip install -e ".[test]"
 pytest
 ```
 
@@ -96,26 +99,56 @@ async def main():
         # Subscribe to a topic
         await client.subscribe_to_topic("room:lobby", handle_message)
         
-        # Use built-in convenience method to keep connection alive
-        await client.run_forever()  # Handles Ctrl+C automatically
+        # Ctrl+C or SIGTERM shuts the client down and run_forever() returns.
+        # The previous handlers are restored first, so a second signal reaches them.
+        await client.run_forever()
 
 if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-## Phoenix System Events
+### Owning process signals yourself
+
+If your application owns its process signals (a service, desktop app or test
+runner), call `client.run_forever(install_signal_handlers=False)`. It then
+leaves signal handlers alone; stop the client by scheduling
+`client.shutdown(reason)` on the client's event loop, and `run_forever()`
+returns `None`:
+
+```python
+loop = asyncio.get_running_loop()
+async with asyncio.TaskGroup() as tasks:
+    loop.add_signal_handler(
+        signal.SIGTERM, lambda: tasks.create_task(client.shutdown("SIGTERM"))
+    )
+    try:
+        await client.run_forever(install_signal_handlers=False)
+    finally:
+        # Once the group exits, a later SIGTERM must not reach the closed group.
+        loop.remove_signal_handler(signal.SIGTERM)
+```
+
+From a plain `signal.signal` handler or another thread, use
+`loop.call_soon_threadsafe(...)` instead: a bare `asyncio.create_task` there
+doesn't wake a loop blocked on I/O, so the shutdown can stall until the next
+network activity. See [`examples/embedded_host_signals.py`](examples/embedded_host_signals.py).
 
-Phoenix Channels uses several reserved event names for internal protocol communication. The client library automatically handles these system events to manage connections, subscriptions, and message routing:
+With the default, handlers are installed only when `run_forever()` runs on the
+main thread; elsewhere it just waits. A handler you registered with
+`loop.add_signal_handler` before calling `run_forever()` still fires for the
+same signal; one registered while it runs replaces the client's.
 
-- `phx_join` - Channel join requests
-- `phx_reply` - Server replies to client messages  
-- `phx_leave` - Channel leave notifications
-- `phx_close` - Channel close events
-- `phx_error` - Channel error events
+## Phoenix System Events
 
-**Important:** You should avoid using these event names when handling custom events in your application, as they are reserved for Phoenix's internal protocol. The library uses these events to determine message routing and connection state management.
+Phoenix reserves `phx_join`, `phx_reply`, `phx_leave`, `phx_close` and
+`phx_error`. Don't use these names for your own events.
 
-If you have a specific use case that requires handling these system events directly, you can do so, but be aware that this may interfere with the library's automatic connection management.
+- The client sends `phx_join` and `phx_leave` and consumes their `phx_reply`.
+- A server `phx_close` or `phx_error` reaches your message handler like any
+  other message; the client does not rejoin or unsubscribe on its own.
+- For an event-specific handler on these, register `PHXEvent.close` or
+  `PHXEvent.error` from `phoenix_channels_python_client.phx_messages`; the
+  plain strings don't match.
 
 ## Protocol Versions
 
@@ -130,7 +163,7 @@ async with PHXChannelsClient(
     api_key="your-api-key"
     # protocol_version defaults to v2.0
 ) as client:
-    # Your code here
+    ...  # your code here
 ```
 
 ### Protocol v1.0
@@ -142,9 +175,11 @@ async with PHXChannelsClient(
     api_key="your-api-key",
     protocol_version=PhoenixChannelsProtocolVersion.V1
 ) as client:
-    # Your code here
+    ...  # your code here
 ```
 
+The client adds `vsn=2.0.0` (V2) or `vsn=1.0.0` (V1) to the socket URL.
+
 ## Usage Examples
 
 ### Basic Topic Subscription
@@ -186,7 +221,7 @@ The library provides two complementary ways to handle incoming messages:
 1. **Message handler runs first** (if set) - receives the full message
 2. **Event-specific handler runs second** (if matching event) - receives just the payload
 
-You can add, remove, or change either type of handler at any time during your connection.
+All handlers must be `async def`. You can add, remove, or change either type of handler at any time during your connection.
 
 ### Event-Specific Handlers
 
@@ -225,10 +260,13 @@ You can unsubscribe from topics to stop receiving messages and clean up resource
 import asyncio
 from phoenix_channels_python_client import PHXChannelsClient
 
+async def on_message(msg):
+    print(f"Message: {msg.payload}")
+
 async def main():
     async with PHXChannelsClient("ws://localhost:4000/socket/websocket", "api-key") as client:
         # Subscribe to a topic
-        await client.subscribe_to_topic("room:lobby", lambda msg: print(f"Message: {msg.payload}"))
+        await client.subscribe_to_topic("room:lobby", on_message)
         
         # Do some work...
         await asyncio.sleep(5)
@@ -245,13 +283,73 @@ asyncio.run(main())
 
 **Notes on unsubscription:**
 - Removes all handlers (both message and event-specific) for that topic
-- Sends a leave message to the Phoenix server
+- Sends `phx_leave` and waits for the reply (`leave_timeout_s`, default 5 s)
+- Raises `PHXTopicError` if the topic isn't subscribed or the leave times out, and `PHXConnectionError` while disconnected
+
+## Configuration
+
+Everything after `api_key` is keyword-only:
+
+| Option | Default | Meaning |
+|---|---|---|
+| `protocol_version` | `V2` | Phoenix Channels protocol version |
+| `auto_reconnect` | `True` | Reconnect and rejoin topics after a disconnect |
+| `reconnect_policy` | `ReconnectPolicy()` | Backoff and close-code handling (see below) |
+| `heartbeat_interval_s` | `30.0` | Heartbeat period; `None` disables heartbeats |
+| `join_timeout_s` | `10.0` | Wait for a join reply |
+| `leave_timeout_s` | `5.0` | Wait for a leave reply |
+| `max_topic_queue_size` | `1000` | Per-topic buffer; the oldest message is dropped when full |
+| `callback_drain_timeout_s` | `2.0` | How long a running callback may finish before a rejoin cancels it |
+| `on_reconnect` | `None` | `async () -> None`, called after topics are rejoined |
+| `on_disconnect` | `None` | `async (error: Exception \| None) -> None`; `None` on a clean close |
+| `on_heartbeat_ack` | `None` | Synchronous `() -> None`; runs on the message path, so keep it fast |
+| `additional_headers` | `None` | Extra handshake headers sent on every (re)connect |
+
+Exceptions raised in callbacks are logged, not raised.
+
+## Connection Lifecycle and Errors
+
+- `async with` waits for the first connection. With `auto_reconnect=True` it keeps retrying; with `auto_reconnect=False` a failed first connection raises `PHXConnectionError`.
+- `run_forever()` returns `None` after `shutdown()`, a signal, or a close that doesn't reconnect. It raises `PHXConnectionError` on a terminal close, after repeated rapid disconnects, or when the client has never entered `async with`.
+- `subscribe_to_topic()` raises `PHXTopicError` on a rejected join, a join timeout or a duplicate subscription.
+- `await client.close_connection(reason)` force-closes the current connection; the client then reconnects if `auto_reconnect` is on.
+- Exceptions live in `phoenix_channels_python_client.exceptions`.
+
+### Reconnects
+
+| Close code | Behaviour (defaults) |
+|---|---|
+| 1000, 1001 | Stop, unless `reconnect_on_normal_close=True` |
+| 1008 | Stop with `PHXConnectionError` (`policy_violation_is_terminal=True`) |
+| 1012 | Reconnect after at least a random 1–5 s |
+| 1013 | Reconnect after at least a random 30–60 s |
+| Anything else, or no close frame | Reconnect with jittered backoff: 0.5 s × 2ⁿ, capped at 30 s, reset after 60 s of uptime |
+
+Disconnects within 5 s of connecting count as rapid and get longer minimum delays; ten within 60 s stop the client with `PHXConnectionError`. Tune all of this with `ReconnectPolicy`.
+
+### Heartbeats
+
+The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. A missed reply only logs a warning; to act on it, combine `on_heartbeat_ack` with `close_connection()`.
+
+## Logging
+
+```python
+import logging
+from phoenix_channels_python_client import setup_logging
+
+setup_logging(logging.DEBUG)  # loggers live under "phoenix_channels_python_client"
+```
+
+## Examples
+
+- [`examples/minimal_phx_events_client.py`](examples/minimal_phx_events_client.py): subscribe to a topic and log messages until Ctrl+C or SIGTERM.
+- [`examples/embedded_host_signals.py`](examples/embedded_host_signals.py): run the client in a host that owns its process signals.
 
 ---
 
 ## Security Considerations
 
-**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). While the connection uses WSS (encrypted in transit), the API key may be logged by:
+**API Key in URL**: This client passes the API key as a URL query parameter when connecting to the WebSocket (e.g., `wss://server.com/socket?api_key=xxx`). Even over WSS (encrypted in transit), the API key may be logged by:
 
 - Server access logs
 - Reverse proxies and load balancers
@@ -262,7 +360,7 @@ asyncio.run(main())
 - Use short-lived, rotatable tokens rather than long-lived API keys
 - Consider this limitation when evaluating this client for sensitive environments
 
-**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This Python client currently uses the older `params` style for broad compatibility.
+**Note:** The official Phoenix JS client (v1.8+) supports header-based authentication via the `authToken` option, which avoids URL logging. This client always sends `api_key` in the URL (logged URLs show `api_key=***`). Pass `additional_headers={"x-api-key": key}` to also send it as a handshake header on every (re)connect, e.g. for a proxy that reads it from there.
 
 ---
 

phoenix_channels_python_client-0.2.5.dist-info/RECORD

@@ -0,0 +1,18 @@
+phoenix_channels_python_client/__init__.py,sha256=zTn4s0MP1HYlkmyBOsW5PtwRn88lgTn6f-dsk5awbMU,791
+phoenix_channels_python_client/client.py,sha256=e3omXmnJnB8rr8YCEyg86kskut0tHRUkMo-z1vitJ6M,10310
+phoenix_channels_python_client/client_state_machine.py,sha256=Exr5wjYB0VXpCq1-tGHN4VraNman1M1vWN073rRFZFo,1124
+phoenix_channels_python_client/client_types.py,sha256=Gyyf72zDpAZtGcnbXJMW6Xj6PksdOM6bh-BXjlN6U5Y,3889
+phoenix_channels_python_client/exceptions.py,sha256=1cpnD_SO3En-yZKS47QSlLjLnK-29gOBcBVHoBQVMkg,227
+phoenix_channels_python_client/phx_messages.py,sha256=lvtyECL_CwUlP_yom57f0U_OpGJsOqETy7KEtdu_yf4,1214
+phoenix_channels_python_client/protocol_handler.py,sha256=ohnZN0Z3GmM0xiRAhLD5n4XtbL37A_HvEgs5b_uBmg8,8141
+phoenix_channels_python_client/reconnect_controller.py,sha256=R924_f59fQN7jvQXFfQxKb6LDBYxheSPszOFETpZ5iI,11025
+phoenix_channels_python_client/shutdown_signals.py,sha256=2BBHZZbIPA6CXX1CP6sRZ50nK2mA3WU0lJECk6FQgEs,4053
+phoenix_channels_python_client/supervisor.py,sha256=UHYw19BEBIIEP9L2o5iAYHMFVd9Hotfft3TSvMB-sTw,18583
+phoenix_channels_python_client/topic_runtime.py,sha256=GAkJQwpeXG-_3wgH3s5GWdTvlBJ7Xz2SX8AlrDNig6E,21580
+phoenix_channels_python_client/topic_subscription.py,sha256=J0wcCsfP9laQ7DxT-6e7OdhQrK_t1zu3n3gcnuedvFI,1916
+phoenix_channels_python_client/utils.py,sha256=h8AhBOM-o7gx0sXh507iRIcL-xka9rLmzvypLeCI--4,2254
+phoenix_channels_python_client-0.2.5.dist-info/licenses/LICENSE,sha256=zwqkIClV_fMWOC0Auvd0DYqZMLL0-hIqeKd6tygE39g,1064
+phoenix_channels_python_client-0.2.5.dist-info/METADATA,sha256=VZLjeABZ30_Cro_TNdsmFhINzpt6w7c7O_QyzjIUZq0,13955
+phoenix_channels_python_client-0.2.5.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+phoenix_channels_python_client-0.2.5.dist-info/top_level.txt,sha256=ZYXMGCOeev4cyNU9XvNGHKt1wOgVkFHaS9TlwDa4eDU,31
+phoenix_channels_python_client-0.2.5.dist-info/RECORD,,

phoenix_channels_python_client-0.2.4.dist-info/RECORD

@@ -1,17 +0,0 @@
-phoenix_channels_python_client/__init__.py,sha256=EVdevvtteX6B9wQewjgbn_f_S3H-w4YkIRpeXK0oKZE,791
-phoenix_channels_python_client/client.py,sha256=EAy1vVC3JInfNk6RYvbE6d8ZC5YmPNho1q474IrptHQ,9546
-phoenix_channels_python_client/client_state_machine.py,sha256=Exr5wjYB0VXpCq1-tGHN4VraNman1M1vWN073rRFZFo,1124
-phoenix_channels_python_client/client_types.py,sha256=Gyyf72zDpAZtGcnbXJMW6Xj6PksdOM6bh-BXjlN6U5Y,3889
-phoenix_channels_python_client/exceptions.py,sha256=1cpnD_SO3En-yZKS47QSlLjLnK-29gOBcBVHoBQVMkg,227
-phoenix_channels_python_client/phx_messages.py,sha256=lvtyECL_CwUlP_yom57f0U_OpGJsOqETy7KEtdu_yf4,1214
-phoenix_channels_python_client/protocol_handler.py,sha256=ohnZN0Z3GmM0xiRAhLD5n4XtbL37A_HvEgs5b_uBmg8,8141
-phoenix_channels_python_client/reconnect_controller.py,sha256=R924_f59fQN7jvQXFfQxKb6LDBYxheSPszOFETpZ5iI,11025
-phoenix_channels_python_client/supervisor.py,sha256=OU1ywX1dAAvw1cNNtFaO6CqdI_G_J7oRevx-rzpQrUI,18133
-phoenix_channels_python_client/topic_runtime.py,sha256=IkZ6tXxRP5Svc8vkuAUo-ic5K_pfsHmYHmabRAHmYnQ,21829
-phoenix_channels_python_client/topic_subscription.py,sha256=J0wcCsfP9laQ7DxT-6e7OdhQrK_t1zu3n3gcnuedvFI,1916
-phoenix_channels_python_client/utils.py,sha256=MdxW2tq5MTCE7RQhhajwChMipSHXJyopBwq5ORo0Vao,1616
-phoenix_channels_python_client-0.2.4.dist-info/licenses/LICENSE,sha256=zwqkIClV_fMWOC0Auvd0DYqZMLL0-hIqeKd6tygE39g,1064
-phoenix_channels_python_client-0.2.4.dist-info/METADATA,sha256=gPYMjC6UbmF8CSHUh7U5VV6WZ7sJZe1GS_ZbsC5nUTM,9157
-phoenix_channels_python_client-0.2.4.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-phoenix_channels_python_client-0.2.4.dist-info/top_level.txt,sha256=ZYXMGCOeev4cyNU9XvNGHKt1wOgVkFHaS9TlwDa4eDU,31
-phoenix_channels_python_client-0.2.4.dist-info/RECORD,,