phoenix-channels-python-client 0.5.0__tar.gz → 0.5.2__tar.gz

{phoenix_channels_python_client-0.5.0/phoenix_channels_python_client.egg-info → phoenix_channels_python_client-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.5.0
+Version: 0.5.2
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -181,10 +181,12 @@ async with asyncio.TaskGroup() as tasks:
         loop.remove_signal_handler(signal.SIGTERM)
 ```
 
+See [`examples/embedded_host_signals.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/embedded_host_signals.py) for a complete program.
+
 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).
+network activity.
 
 With the default, handlers are installed only when `run_forever()` runs on the
 main thread; elsewhere it just waits. A handler you registered with
@@ -237,7 +239,7 @@ string values `"1.0"` and `"2.0"`. Other values raise `ValueError`. It adds
 
 ## Usage Examples
 
-### Basic Topic Subscription
+### Joining a channel
 
 Use `on_any` when you need the complete `Message`:
 
@@ -254,7 +256,7 @@ async def main() -> None:
         async def message_handler(message: Message) -> None:
             print(f"Topic: {message.topic}")
             print(f"Event: {message.event}")
-            print(f"Payload: {message.payload}")
+            print(f"Payload: {message.payload!r}")
 
         async with room:
             await client.run_forever()
@@ -262,7 +264,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Message Handlers vs Event-Specific Handlers
+## Catch-all vs event handlers
 
 A channel supports one catch-all handler and one handler per event:
 
@@ -315,7 +317,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Unsubscribing from Topics
+## Leaving a channel
 
 Leaving a channel stops delivery and cleans up its membership. Prefer a context
 manager so exceptions and cancellation also trigger cleanup:
@@ -331,7 +333,7 @@ async def main() -> None:
 
         @room.on_any
         async def on_message(message: Message) -> None:
-            print(f"Message: {message.payload}")
+            print(f"Message: {message.payload!r}")
 
         async with room:
             await asyncio.sleep(5)
@@ -376,6 +378,47 @@ frame. Providers must be nonblocking and return a JSON-serializable dict;
 provider/encoding failure raises `ChannelError` with its cause. A provider failure
 during recovery permanently loses only that channel instead of retrying forever.
 
+### Ordered join responses
+
+Pass `on_join_response` when creating a channel to install a snapshot from every
+initial join, socket rejoin and same-socket recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+room = client.channel("room:123", on_join_response=install_snapshot)
+room.on_any(on_message)
+async with room:
+    await client.run_forever()
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives decoded
+successful `payload.response`; a missing response is `None`. It runs synchronously
+before the channel becomes joined, the join completes, or later events are
+delivered. The client adds no application schema or empty snapshot. Join and leave
+replies are handled separately from the bounded application-event queue.
+
+Hooks must be short, nonblocking and return `None`. Async callables, awaitables
+and other non-`None` results fail installation with `ChannelError`, as do hook
+exceptions (including a directly raised `CancelledError`); the original cause is
+preserved. Arbitrary prior hook effects are not rolled back. Do not wait on locks,
+perform I/O, defer installation or change client lifecycle inside the hook. An
+asyncio deadline cannot preempt synchronous code that blocks the loop.
+
+Initial failure retires the admitted handle. Installation failure on an established
+channel is reported once through `on_topic_lost`. Queue overflow and recovery can
+still discard application events, so applications needing durable state must
+resynchronize rather than assume replay.
+
+Join replies match request refs on both protocols. V2 additionally checks a
+present `join_ref`; a missing join_ref is accepted, including for broadcasts.
+Membership controls use their available refs for correlation. V1 cannot provide
+V2 isolation for arbitrary unsolicited events from old memberships.
+
 ## Pushing Events
 
 Use `await channel.push(event, payload, timeout_s=10.0)` to send an application
@@ -396,7 +439,7 @@ async def main() -> None:
             if reply.status == "ok":
                 print(reply.response)
             else:
-                print(f"Server replied {reply.status}: {reply.response}")
+                print(f"Server replied {reply.status}: {reply.response!r}")
 
 asyncio.run(main())
 ```
@@ -506,7 +549,7 @@ Only `websocket_url` may be positional; all other constructor options are keywor
 | `join_timeout_s` | `10.0` | Finite positive join-operation deadline |
 | `leave_timeout_s` | `5.0` | Finite positive leave-operation deadline |
 | `max_topic_queue_size` | `1000` | Per-topic buffer; the oldest message is dropped when full |
-| `callback_drain_timeout_s` | `2.0` | How long the message being handled (its message handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
+| `callback_drain_timeout_s` | `2.0` | How long the message being handled (its catch-all handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
 | `on_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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 |
@@ -597,6 +640,26 @@ or rejoining. `await room.leave()` also works during recovery and stops future
 rejoin attempts. Client lifecycle callbacks stay constructor options; `shutdown()`
 cancels them, including a callback that itself called `shutdown()`.
 
+### Optional reconnect participation
+
+`client.channel(topic, *, params=None, on_join_response=None,
+blocks_reconnect=True)` creates a channel that blocks the reconnect barrier by
+default. Required channels reconcile their first socket-rejoin attempt sequentially
+before `on_reconnect`; transient failures continue through recovery/backoff. The
+barrier does not wait for eventual success of every required channel.
+
+Set `blocks_reconnect=False` when creating an optional channel. Its owned recovery
+task attempts an immediate join after required first attempts and retries transient
+failures with the same backoff. Required delivery and `on_reconnect` do not wait for
+optional replies, callback drains or retries. Explicit `await room.join()` still
+waits for that channel's reply and installation.
+
+`on_reconnect` does not promise optional readiness. Check each handle's `joined`
+property and use `on_topic_lost` to replace permanent losses. Do not blindly create
+replacement channels on every reconnect. Leave, shutdown and another socket
+disconnect stop or hand over recovery; obsolete attempts cannot revive a left
+handle.
+
 ### Heartbeats
 
 The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. By default, missed replies log warnings and sending continues with a new reference each interval.
@@ -618,7 +681,9 @@ Expiry or heartbeat send failure force-closes that socket; the supervisor handle
 ## Logging
 
 The library uses loggers under `phoenix_channels_python_client`. Configure
-logging in your application; importing the package does not configure it:
+logging in your application; importing the package does not configure it.
+Connection log lines show `<omitted>` in place of values that may carry personal
+data (see [Authentication and diagnostic safety](#authentication-and-diagnostic-safety)):
 
 ```python
 import logging
@@ -629,8 +694,8 @@ logging.getLogger("phoenix_channels_python_client").setLevel(logging.DEBUG)
 
 ## 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.
+- [`examples/minimal_phx_events_client.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/minimal_phx_events_client.py): join a channel and log messages until Ctrl+C or SIGTERM.
+- [`examples/embedded_host_signals.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/embedded_host_signals.py): run the client in a host that owns its process signals.
 
 ---
 
@@ -659,10 +724,6 @@ async with Client(
     ...
 ```
 
----
-
-**Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
-
 ### Authentication and diagnostic safety
 
 A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
@@ -677,69 +738,14 @@ exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
 the credential policy to transport errors a caller needs to retain. Caller-visible
 errors may still contain personal data and should not be logged outside this policy.
 
-Connection diagnostics omit dynamic strings and transport payloads, including URLs,
-headers, frame bodies, user/topic identities, and untrusted server error details.
-Logs retain static lifecycle descriptions, native connection states,
-and exception types. Application data and caller-visible errors are not changed;
+Connection diagnostics omit dynamic values and transport payloads, including URLs,
+headers, frame bodies, user/topic identities, numbers, and untrusted server error
+details. Each omitted value appears as `<omitted>`, for example
+`No handler found for event <omitted> on topic <omitted>`. Logs retain static
+lifecycle descriptions, enum values such as connection states, booleans, and
+exception types. Application data and caller-visible errors are not changed;
 applications remain responsible for logs outside this connection-owned boundary.
 
-### Ordered join responses
-
-Pass `on_join_response` when creating a channel to install a snapshot from every
-initial join, socket rejoin and same-socket recovery:
-
-```python
-state = None
-
-def install_snapshot(response):
-    global state
-    state = validate_snapshot(response)
-
-room = client.channel("room:123", on_join_response=install_snapshot)
-room.on_any(on_message)
-async with room:
-    await client.run_forever()
-```
-
-`JoinResponseCallback` is exported from the package. The hook receives decoded
-successful `payload.response`; a missing response is `None`. It runs synchronously
-before the channel becomes joined, the join completes, or later events are
-delivered. The client adds no application schema or empty snapshot. Join and leave
-replies are handled separately from the bounded application-event queue.
-
-Hooks must be short, nonblocking and return `None`. Async callables, awaitables
-and other non-`None` results fail installation with `ChannelError`, as do hook
-exceptions (including a directly raised `CancelledError`); the original cause is
-preserved. Arbitrary prior hook effects are not rolled back. Do not wait on locks,
-perform I/O, defer installation or change client lifecycle inside the hook. An
-asyncio deadline cannot preempt synchronous code that blocks the loop.
-
-Initial failure retires the admitted handle. Installation failure on an established
-channel is reported once through `on_topic_lost`. Queue overflow and recovery can
-still discard application events, so applications needing durable state must
-resynchronize rather than assume replay.
-
-Join replies match request refs on both protocols. V2 additionally checks a
-present `join_ref`; a missing join_ref is accepted, including for broadcasts.
-Membership controls use their available refs for correlation. V1 cannot provide
-V2 isolation for arbitrary unsolicited events from old memberships.
-
-### Optional reconnect participation
-
-`client.channel(topic, *, params=None, on_join_response=None,
-blocks_reconnect=True)` creates a channel that blocks the reconnect barrier by
-default. Required channels reconcile their first socket-rejoin attempt sequentially
-before `on_reconnect`; transient failures continue through recovery/backoff. The
-barrier does not wait for eventual success of every required channel.
-
-Set `blocks_reconnect=False` when creating an optional channel. Its owned recovery
-task attempts an immediate join after required first attempts and retries transient
-failures with the same backoff. Required delivery and `on_reconnect` do not wait for
-optional replies, callback drains or retries. Explicit `await room.join()` still
-waits for that channel's reply and installation.
+---
 
-`on_reconnect` does not promise optional readiness. Check each handle's `joined`
-property and use `on_topic_lost` to replace permanent losses. Do not blindly create
-replacement channels on every reconnect. Leave, shutdown and another socket
-disconnect stop or hand over recovery; obsolete attempts cannot revive a left
-handle.
+**Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/README.md

@@ -148,10 +148,12 @@ async with asyncio.TaskGroup() as tasks:
         loop.remove_signal_handler(signal.SIGTERM)
 ```
 
+See [`examples/embedded_host_signals.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/embedded_host_signals.py) for a complete program.
+
 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).
+network activity.
 
 With the default, handlers are installed only when `run_forever()` runs on the
 main thread; elsewhere it just waits. A handler you registered with
@@ -204,7 +206,7 @@ string values `"1.0"` and `"2.0"`. Other values raise `ValueError`. It adds
 
 ## Usage Examples
 
-### Basic Topic Subscription
+### Joining a channel
 
 Use `on_any` when you need the complete `Message`:
 
@@ -221,7 +223,7 @@ async def main() -> None:
         async def message_handler(message: Message) -> None:
             print(f"Topic: {message.topic}")
             print(f"Event: {message.event}")
-            print(f"Payload: {message.payload}")
+            print(f"Payload: {message.payload!r}")
 
         async with room:
             await client.run_forever()
@@ -229,7 +231,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Message Handlers vs Event-Specific Handlers
+## Catch-all vs event handlers
 
 A channel supports one catch-all handler and one handler per event:
 
@@ -282,7 +284,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Unsubscribing from Topics
+## Leaving a channel
 
 Leaving a channel stops delivery and cleans up its membership. Prefer a context
 manager so exceptions and cancellation also trigger cleanup:
@@ -298,7 +300,7 @@ async def main() -> None:
 
         @room.on_any
         async def on_message(message: Message) -> None:
-            print(f"Message: {message.payload}")
+            print(f"Message: {message.payload!r}")
 
         async with room:
             await asyncio.sleep(5)
@@ -343,6 +345,47 @@ frame. Providers must be nonblocking and return a JSON-serializable dict;
 provider/encoding failure raises `ChannelError` with its cause. A provider failure
 during recovery permanently loses only that channel instead of retrying forever.
 
+### Ordered join responses
+
+Pass `on_join_response` when creating a channel to install a snapshot from every
+initial join, socket rejoin and same-socket recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+room = client.channel("room:123", on_join_response=install_snapshot)
+room.on_any(on_message)
+async with room:
+    await client.run_forever()
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives decoded
+successful `payload.response`; a missing response is `None`. It runs synchronously
+before the channel becomes joined, the join completes, or later events are
+delivered. The client adds no application schema or empty snapshot. Join and leave
+replies are handled separately from the bounded application-event queue.
+
+Hooks must be short, nonblocking and return `None`. Async callables, awaitables
+and other non-`None` results fail installation with `ChannelError`, as do hook
+exceptions (including a directly raised `CancelledError`); the original cause is
+preserved. Arbitrary prior hook effects are not rolled back. Do not wait on locks,
+perform I/O, defer installation or change client lifecycle inside the hook. An
+asyncio deadline cannot preempt synchronous code that blocks the loop.
+
+Initial failure retires the admitted handle. Installation failure on an established
+channel is reported once through `on_topic_lost`. Queue overflow and recovery can
+still discard application events, so applications needing durable state must
+resynchronize rather than assume replay.
+
+Join replies match request refs on both protocols. V2 additionally checks a
+present `join_ref`; a missing join_ref is accepted, including for broadcasts.
+Membership controls use their available refs for correlation. V1 cannot provide
+V2 isolation for arbitrary unsolicited events from old memberships.
+
 ## Pushing Events
 
 Use `await channel.push(event, payload, timeout_s=10.0)` to send an application
@@ -363,7 +406,7 @@ async def main() -> None:
             if reply.status == "ok":
                 print(reply.response)
             else:
-                print(f"Server replied {reply.status}: {reply.response}")
+                print(f"Server replied {reply.status}: {reply.response!r}")
 
 asyncio.run(main())
 ```
@@ -473,7 +516,7 @@ Only `websocket_url` may be positional; all other constructor options are keywor
 | `join_timeout_s` | `10.0` | Finite positive join-operation deadline |
 | `leave_timeout_s` | `5.0` | Finite positive leave-operation deadline |
 | `max_topic_queue_size` | `1000` | Per-topic buffer; the oldest message is dropped when full |
-| `callback_drain_timeout_s` | `2.0` | How long the message being handled (its message handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
+| `callback_drain_timeout_s` | `2.0` | How long the message being handled (its catch-all handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
 | `on_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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 |
@@ -564,6 +607,26 @@ or rejoining. `await room.leave()` also works during recovery and stops future
 rejoin attempts. Client lifecycle callbacks stay constructor options; `shutdown()`
 cancels them, including a callback that itself called `shutdown()`.
 
+### Optional reconnect participation
+
+`client.channel(topic, *, params=None, on_join_response=None,
+blocks_reconnect=True)` creates a channel that blocks the reconnect barrier by
+default. Required channels reconcile their first socket-rejoin attempt sequentially
+before `on_reconnect`; transient failures continue through recovery/backoff. The
+barrier does not wait for eventual success of every required channel.
+
+Set `blocks_reconnect=False` when creating an optional channel. Its owned recovery
+task attempts an immediate join after required first attempts and retries transient
+failures with the same backoff. Required delivery and `on_reconnect` do not wait for
+optional replies, callback drains or retries. Explicit `await room.join()` still
+waits for that channel's reply and installation.
+
+`on_reconnect` does not promise optional readiness. Check each handle's `joined`
+property and use `on_topic_lost` to replace permanent losses. Do not blindly create
+replacement channels on every reconnect. Leave, shutdown and another socket
+disconnect stop or hand over recovery; obsolete attempts cannot revive a left
+handle.
+
 ### Heartbeats
 
 The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. By default, missed replies log warnings and sending continues with a new reference each interval.
@@ -585,7 +648,9 @@ Expiry or heartbeat send failure force-closes that socket; the supervisor handle
 ## Logging
 
 The library uses loggers under `phoenix_channels_python_client`. Configure
-logging in your application; importing the package does not configure it:
+logging in your application; importing the package does not configure it.
+Connection log lines show `<omitted>` in place of values that may carry personal
+data (see [Authentication and diagnostic safety](#authentication-and-diagnostic-safety)):
 
 ```python
 import logging
@@ -596,8 +661,8 @@ logging.getLogger("phoenix_channels_python_client").setLevel(logging.DEBUG)
 
 ## 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.
+- [`examples/minimal_phx_events_client.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/minimal_phx_events_client.py): join a channel and log messages until Ctrl+C or SIGTERM.
+- [`examples/embedded_host_signals.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/embedded_host_signals.py): run the client in a host that owns its process signals.
 
 ---
 
@@ -626,10 +691,6 @@ async with Client(
     ...
 ```
 
----
-
-**Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
-
 ### Authentication and diagnostic safety
 
 A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
@@ -644,69 +705,14 @@ exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
 the credential policy to transport errors a caller needs to retain. Caller-visible
 errors may still contain personal data and should not be logged outside this policy.
 
-Connection diagnostics omit dynamic strings and transport payloads, including URLs,
-headers, frame bodies, user/topic identities, and untrusted server error details.
-Logs retain static lifecycle descriptions, native connection states,
-and exception types. Application data and caller-visible errors are not changed;
+Connection diagnostics omit dynamic values and transport payloads, including URLs,
+headers, frame bodies, user/topic identities, numbers, and untrusted server error
+details. Each omitted value appears as `<omitted>`, for example
+`No handler found for event <omitted> on topic <omitted>`. Logs retain static
+lifecycle descriptions, enum values such as connection states, booleans, and
+exception types. Application data and caller-visible errors are not changed;
 applications remain responsible for logs outside this connection-owned boundary.
 
-### Ordered join responses
-
-Pass `on_join_response` when creating a channel to install a snapshot from every
-initial join, socket rejoin and same-socket recovery:
-
-```python
-state = None
-
-def install_snapshot(response):
-    global state
-    state = validate_snapshot(response)
-
-room = client.channel("room:123", on_join_response=install_snapshot)
-room.on_any(on_message)
-async with room:
-    await client.run_forever()
-```
-
-`JoinResponseCallback` is exported from the package. The hook receives decoded
-successful `payload.response`; a missing response is `None`. It runs synchronously
-before the channel becomes joined, the join completes, or later events are
-delivered. The client adds no application schema or empty snapshot. Join and leave
-replies are handled separately from the bounded application-event queue.
-
-Hooks must be short, nonblocking and return `None`. Async callables, awaitables
-and other non-`None` results fail installation with `ChannelError`, as do hook
-exceptions (including a directly raised `CancelledError`); the original cause is
-preserved. Arbitrary prior hook effects are not rolled back. Do not wait on locks,
-perform I/O, defer installation or change client lifecycle inside the hook. An
-asyncio deadline cannot preempt synchronous code that blocks the loop.
-
-Initial failure retires the admitted handle. Installation failure on an established
-channel is reported once through `on_topic_lost`. Queue overflow and recovery can
-still discard application events, so applications needing durable state must
-resynchronize rather than assume replay.
-
-Join replies match request refs on both protocols. V2 additionally checks a
-present `join_ref`; a missing join_ref is accepted, including for broadcasts.
-Membership controls use their available refs for correlation. V1 cannot provide
-V2 isolation for arbitrary unsolicited events from old memberships.
-
-### Optional reconnect participation
-
-`client.channel(topic, *, params=None, on_join_response=None,
-blocks_reconnect=True)` creates a channel that blocks the reconnect barrier by
-default. Required channels reconcile their first socket-rejoin attempt sequentially
-before `on_reconnect`; transient failures continue through recovery/backoff. The
-barrier does not wait for eventual success of every required channel.
-
-Set `blocks_reconnect=False` when creating an optional channel. Its owned recovery
-task attempts an immediate join after required first attempts and retries transient
-failures with the same backoff. Required delivery and `on_reconnect` do not wait for
-optional replies, callback drains or retries. Explicit `await room.join()` still
-waits for that channel's reply and installation.
+---
 
-`on_reconnect` does not promise optional readiness. Check each handle's `joined`
-property and use `on_topic_lost` to replace permanent losses. Do not blindly create
-replacement channels on every reconnect. Leave, shutdown and another socket
-disconnect stop or hand over recovery; obsolete attempts cannot revive a left
-handle.
+**Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/__init__.py

@@ -27,7 +27,7 @@ from phoenix_channels_python_client.messages import Message, Payload, SystemEven
 from phoenix_channels_python_client.protocol import ProtocolVersion
 from phoenix_channels_python_client.replies import Reply
 
-__version__ = "0.5.0"
+__version__ = "0.5.2"
 
 __all__ = [
     "Channel",

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/codec.py

@@ -120,7 +120,9 @@ def _decode_binary(raw: bytes) -> DecodedMessage:
         raise ValueError("Empty binary frame")
     kind = BinaryKind(raw[0])
     fields, payload = _binary_fields(raw, SERVER_HEADER_FIELDS[kind])
-    status = None
+    join_ref: str | None
+    ref: str | None
+    status: str | None = None
     match kind:
         case BinaryKind.PUSH:
             join_ref, topic, event = fields

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/diagnostics.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import json
 import logging
 import re
+from enum import Enum
 from urllib.parse import parse_qsl, quote, quote_plus, urlsplit
 
 from websockets.protocol import State
@@ -14,7 +15,34 @@ from phoenix_channels_python_client.authentication import (
 )
 
 REDACTED = "[REDACTED]"
+OMITTED = "<omitted>"
 PERCENT_ESCAPE = re.compile(r"%[0-9a-fA-F]{2}")
+# A printf-style conversion, as logging applies to a record's msg and args.
+PLACEHOLDER = re.compile(
+    r"%(?:\([^)]*\))?[#0 +-]*(?:\*|\d+)?(?:\.(?:\*|\d+))?[hlL]?[diouxXeEfFgGcrsa%]"
+)
+WEBSOCKET_STATE_MESSAGE = "= connection is %s"
+
+
+def render_value(value: object) -> str:
+    # Enum members and booleans are code-defined; any other value, numbers
+    # included, may carry personal data.
+    return str(value) if isinstance(value, Enum | bool) else OMITTED
+
+
+def render_message(record: logging.LogRecord) -> str:
+    """Fill a record's placeholders without exposing its arguments."""
+    message = str(record.msg)
+    if not record.args:
+        return message
+    args = record.args if isinstance(record.args, tuple) else ()
+    if message == WEBSOCKET_STATE_MESSAGE and args and args[0] in State.__members__:
+        return message % args[0]
+    values = iter(args)
+    return PLACEHOLDER.sub(
+        lambda match: "%" if match[0] == "%%" else render_value(next(values, None)),
+        message,
+    )
 
 
 AUTHENTICATION_NAMES = frozenset(
@@ -86,15 +114,7 @@ class ConnectionLogger(logging.Logger):
     def handle(self, record: logging.LogRecord) -> None:
         if self.target.disabled:
             return
-        message = str(record.msg)
-        if (
-            record.msg == "= connection is %s"
-            and isinstance(record.args, tuple)
-            and len(record.args) == 1
-            and isinstance(record.args[0], str)
-            and record.args[0] in State.__members__
-        ):
-            message = record.msg % record.args
+        message = render_message(record)
         if record.exc_info and record.exc_info[0]:
             message += " [" + record.exc_info[0].__name__ + "]"
         safe_record = logging.LogRecord(

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/messages.py

@@ -14,7 +14,7 @@ class SystemEvent(StrEnum):
     close = "phx_close"
     error = "phx_error"
     # The protocol event intentionally shadows str.join.
-    join = "phx_join"  # type: ignore[bad-override]
+    join = "phx_join"  # type: ignore[bad-override, assignment]
     reply = "phx_reply"
     leave = "phx_leave"
 

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/replies.py

@@ -20,13 +20,11 @@ def reply_from_message(message: Message, *, binary_status: str | None = None) ->
     if binary_status is not None:
         if type(message.payload) is not bytes:
             raise TypeError("Binary reply requires a bytes payload")
-        status, response = binary_status, message.payload
-    else:
-        payload = message.payload
-        if not isinstance(payload, dict):
-            raise TypeError("Text reply requires a response envelope")
-        status = payload.get("status")
-        response = payload.get("response")
-        if not isinstance(status, str) or not isinstance(response, dict):
-            raise TypeError("Reply must contain a string status and a response map")
+        return Reply(status=binary_status, response=message.payload)
+    payload = message.payload
+    if not isinstance(payload, dict):
+        raise TypeError("Text reply requires a response envelope")
+    status, response = payload.get("status"), payload.get("response")
+    if not isinstance(status, str) or not isinstance(response, dict):
+        raise TypeError("Reply must contain a string status and a response map")
     return Reply(status=status, response=response)

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/supervisor.py

@@ -27,6 +27,7 @@ from phoenix_channels_python_client.messages import (
     Message,
 )
 from phoenix_channels_python_client.protocol_handler import PHXProtocolHandler
+from phoenix_channels_python_client.send_session import SessionSends
 from phoenix_channels_python_client.shutdown_signals import handle_shutdown_signals
 from phoenix_channels_python_client.topic_subscription import (
     ChannelState,
@@ -102,6 +103,7 @@ class SupervisorMixin:
     heartbeat_interval_s: float | None
     heartbeat_task: asyncio.Task[None] | None
     pending_heartbeat_ref: str | None
+    send_session: SessionSends | None
     on_reconnect: Callable[[], Awaitable[None]] | None
     on_disconnect: Callable[[Exception | None], Awaitable[None]] | None
     on_heartbeat_ack: Callable[[], None] | None

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/phoenix_channels_python_client/topic_runtime.py

@@ -838,8 +838,9 @@ class TopicRuntimeMixin:
 
     def _validate_join_hook(self, topic: TopicSubscription) -> None:
         hook = topic.on_join_response
-        if inspect.iscoroutinefunction(hook) or inspect.iscoroutinefunction(
-            hook.__call__ if callable(hook) else None
+        if hook is not None and (
+            inspect.iscoroutinefunction(hook)
+            or inspect.iscoroutinefunction(type(hook).__call__)
         ):
             raise ChannelError("on_join_response must be synchronous")
 

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2/phoenix_channels_python_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phoenix-channels-python-client
-Version: 0.5.0
+Version: 0.5.2
 Summary: A Python client library for connecting to Phoenix Channels
 Author: Phoenix Channels Python Client
 License-Expression: MIT
@@ -181,10 +181,12 @@ async with asyncio.TaskGroup() as tasks:
         loop.remove_signal_handler(signal.SIGTERM)
 ```
 
+See [`examples/embedded_host_signals.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/embedded_host_signals.py) for a complete program.
+
 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).
+network activity.
 
 With the default, handlers are installed only when `run_forever()` runs on the
 main thread; elsewhere it just waits. A handler you registered with
@@ -237,7 +239,7 @@ string values `"1.0"` and `"2.0"`. Other values raise `ValueError`. It adds
 
 ## Usage Examples
 
-### Basic Topic Subscription
+### Joining a channel
 
 Use `on_any` when you need the complete `Message`:
 
@@ -254,7 +256,7 @@ async def main() -> None:
         async def message_handler(message: Message) -> None:
             print(f"Topic: {message.topic}")
             print(f"Event: {message.event}")
-            print(f"Payload: {message.payload}")
+            print(f"Payload: {message.payload!r}")
 
         async with room:
             await client.run_forever()
@@ -262,7 +264,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Message Handlers vs Event-Specific Handlers
+## Catch-all vs event handlers
 
 A channel supports one catch-all handler and one handler per event:
 
@@ -315,7 +317,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-## Unsubscribing from Topics
+## Leaving a channel
 
 Leaving a channel stops delivery and cleans up its membership. Prefer a context
 manager so exceptions and cancellation also trigger cleanup:
@@ -331,7 +333,7 @@ async def main() -> None:
 
         @room.on_any
         async def on_message(message: Message) -> None:
-            print(f"Message: {message.payload}")
+            print(f"Message: {message.payload!r}")
 
         async with room:
             await asyncio.sleep(5)
@@ -376,6 +378,47 @@ frame. Providers must be nonblocking and return a JSON-serializable dict;
 provider/encoding failure raises `ChannelError` with its cause. A provider failure
 during recovery permanently loses only that channel instead of retrying forever.
 
+### Ordered join responses
+
+Pass `on_join_response` when creating a channel to install a snapshot from every
+initial join, socket rejoin and same-socket recovery:
+
+```python
+state = None
+
+def install_snapshot(response):
+    global state
+    state = validate_snapshot(response)
+
+room = client.channel("room:123", on_join_response=install_snapshot)
+room.on_any(on_message)
+async with room:
+    await client.run_forever()
+```
+
+`JoinResponseCallback` is exported from the package. The hook receives decoded
+successful `payload.response`; a missing response is `None`. It runs synchronously
+before the channel becomes joined, the join completes, or later events are
+delivered. The client adds no application schema or empty snapshot. Join and leave
+replies are handled separately from the bounded application-event queue.
+
+Hooks must be short, nonblocking and return `None`. Async callables, awaitables
+and other non-`None` results fail installation with `ChannelError`, as do hook
+exceptions (including a directly raised `CancelledError`); the original cause is
+preserved. Arbitrary prior hook effects are not rolled back. Do not wait on locks,
+perform I/O, defer installation or change client lifecycle inside the hook. An
+asyncio deadline cannot preempt synchronous code that blocks the loop.
+
+Initial failure retires the admitted handle. Installation failure on an established
+channel is reported once through `on_topic_lost`. Queue overflow and recovery can
+still discard application events, so applications needing durable state must
+resynchronize rather than assume replay.
+
+Join replies match request refs on both protocols. V2 additionally checks a
+present `join_ref`; a missing join_ref is accepted, including for broadcasts.
+Membership controls use their available refs for correlation. V1 cannot provide
+V2 isolation for arbitrary unsolicited events from old memberships.
+
 ## Pushing Events
 
 Use `await channel.push(event, payload, timeout_s=10.0)` to send an application
@@ -396,7 +439,7 @@ async def main() -> None:
             if reply.status == "ok":
                 print(reply.response)
             else:
-                print(f"Server replied {reply.status}: {reply.response}")
+                print(f"Server replied {reply.status}: {reply.response!r}")
 
 asyncio.run(main())
 ```
@@ -506,7 +549,7 @@ Only `websocket_url` may be positional; all other constructor options are keywor
 | `join_timeout_s` | `10.0` | Finite positive join-operation deadline |
 | `leave_timeout_s` | `5.0` | Finite positive leave-operation deadline |
 | `max_topic_queue_size` | `1000` | Per-topic buffer; the oldest message is dropped when full |
-| `callback_drain_timeout_s` | `2.0` | How long the message being handled (its message handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
+| `callback_drain_timeout_s` | `2.0` | How long the message being handled (its catch-all handler, then its event handler) may finish before a rejoin cancels it; queued messages are dropped |
 | `on_reconnect` | `None` | `async () -> None`, called after required first-attempt reconciliation |
 | `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 |
@@ -597,6 +640,26 @@ or rejoining. `await room.leave()` also works during recovery and stops future
 rejoin attempts. Client lifecycle callbacks stay constructor options; `shutdown()`
 cancels them, including a callback that itself called `shutdown()`.
 
+### Optional reconnect participation
+
+`client.channel(topic, *, params=None, on_join_response=None,
+blocks_reconnect=True)` creates a channel that blocks the reconnect barrier by
+default. Required channels reconcile their first socket-rejoin attempt sequentially
+before `on_reconnect`; transient failures continue through recovery/backoff. The
+barrier does not wait for eventual success of every required channel.
+
+Set `blocks_reconnect=False` when creating an optional channel. Its owned recovery
+task attempts an immediate join after required first attempts and retries transient
+failures with the same backoff. Required delivery and `on_reconnect` do not wait for
+optional replies, callback drains or retries. Explicit `await room.join()` still
+waits for that channel's reply and installation.
+
+`on_reconnect` does not promise optional readiness. Check each handle's `joined`
+property and use `on_topic_lost` to replace permanent losses. Do not blindly create
+replacement channels on every reconnect. Leave, shutdown and another socket
+disconnect stop or hand over recovery; obsolete attempts cannot revive a left
+handle.
+
 ### Heartbeats
 
 The client sends a `heartbeat` on the `phoenix` topic every `heartbeat_interval_s`. By default, missed replies log warnings and sending continues with a new reference each interval.
@@ -618,7 +681,9 @@ Expiry or heartbeat send failure force-closes that socket; the supervisor handle
 ## Logging
 
 The library uses loggers under `phoenix_channels_python_client`. Configure
-logging in your application; importing the package does not configure it:
+logging in your application; importing the package does not configure it.
+Connection log lines show `<omitted>` in place of values that may carry personal
+data (see [Authentication and diagnostic safety](#authentication-and-diagnostic-safety)):
 
 ```python
 import logging
@@ -629,8 +694,8 @@ logging.getLogger("phoenix_channels_python_client").setLevel(logging.DEBUG)
 
 ## 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.
+- [`examples/minimal_phx_events_client.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/minimal_phx_events_client.py): join a channel and log messages until Ctrl+C or SIGTERM.
+- [`examples/embedded_host_signals.py`](https://github.com/band-ai/phoenix-channels-python-client/blob/main/examples/embedded_host_signals.py): run the client in a host that owns its process signals.
 
 ---
 
@@ -659,10 +724,6 @@ async with Client(
     ...
 ```
 
----
-
-**Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.
-
 ### Authentication and diagnostic safety
 
 A nonempty `x-api-key` or `x-auth-token` handshake header selects header-only authentication on
@@ -677,69 +738,14 @@ exception objects, or socket metadata. `client.redact_diagnostic(text)` applies
 the credential policy to transport errors a caller needs to retain. Caller-visible
 errors may still contain personal data and should not be logged outside this policy.
 
-Connection diagnostics omit dynamic strings and transport payloads, including URLs,
-headers, frame bodies, user/topic identities, and untrusted server error details.
-Logs retain static lifecycle descriptions, native connection states,
-and exception types. Application data and caller-visible errors are not changed;
+Connection diagnostics omit dynamic values and transport payloads, including URLs,
+headers, frame bodies, user/topic identities, numbers, and untrusted server error
+details. Each omitted value appears as `<omitted>`, for example
+`No handler found for event <omitted> on topic <omitted>`. Logs retain static
+lifecycle descriptions, enum values such as connection states, booleans, and
+exception types. Application data and caller-visible errors are not changed;
 applications remain responsible for logs outside this connection-owned boundary.
 
-### Ordered join responses
-
-Pass `on_join_response` when creating a channel to install a snapshot from every
-initial join, socket rejoin and same-socket recovery:
-
-```python
-state = None
-
-def install_snapshot(response):
-    global state
-    state = validate_snapshot(response)
-
-room = client.channel("room:123", on_join_response=install_snapshot)
-room.on_any(on_message)
-async with room:
-    await client.run_forever()
-```
-
-`JoinResponseCallback` is exported from the package. The hook receives decoded
-successful `payload.response`; a missing response is `None`. It runs synchronously
-before the channel becomes joined, the join completes, or later events are
-delivered. The client adds no application schema or empty snapshot. Join and leave
-replies are handled separately from the bounded application-event queue.
-
-Hooks must be short, nonblocking and return `None`. Async callables, awaitables
-and other non-`None` results fail installation with `ChannelError`, as do hook
-exceptions (including a directly raised `CancelledError`); the original cause is
-preserved. Arbitrary prior hook effects are not rolled back. Do not wait on locks,
-perform I/O, defer installation or change client lifecycle inside the hook. An
-asyncio deadline cannot preempt synchronous code that blocks the loop.
-
-Initial failure retires the admitted handle. Installation failure on an established
-channel is reported once through `on_topic_lost`. Queue overflow and recovery can
-still discard application events, so applications needing durable state must
-resynchronize rather than assume replay.
-
-Join replies match request refs on both protocols. V2 additionally checks a
-present `join_ref`; a missing join_ref is accepted, including for broadcasts.
-Membership controls use their available refs for correlation. V1 cannot provide
-V2 isolation for arbitrary unsolicited events from old memberships.
-
-### Optional reconnect participation
-
-`client.channel(topic, *, params=None, on_join_response=None,
-blocks_reconnect=True)` creates a channel that blocks the reconnect barrier by
-default. Required channels reconcile their first socket-rejoin attempt sequentially
-before `on_reconnect`; transient failures continue through recovery/backoff. The
-barrier does not wait for eventual success of every required channel.
-
-Set `blocks_reconnect=False` when creating an optional channel. Its owned recovery
-task attempts an immediate join after required first attempts and retries transient
-failures with the same backoff. Required delivery and `on_reconnect` do not wait for
-optional replies, callback drains or retries. Explicit `await room.join()` still
-waits for that channel's reply and installation.
+---
 
-`on_reconnect` does not promise optional readiness. Check each handle's `joined`
-property and use `on_topic_lost` to replace permanent losses. Do not blindly create
-replacement channels on every reconnect. Leave, shutdown and another socket
-disconnect stop or hand over recovery; obsolete attempts cannot revive a left
-handle.
+**Need help?** Open an issue on GitHub or check the [Phoenix Channels documentation](https://hexdocs.pm/phoenix/channels.html) for more information about the Phoenix Channels protocol.

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phoenix-channels-python-client"
-version = "0.5.0"
+version = "0.5.2"
 description = "A Python client library for connecting to Phoenix Channels"
 readme = "README.md"
 license = "MIT"

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/tests/test_channel_recovery.py

@@ -91,7 +91,7 @@ async def test_a_crashed_channel_rejoins_on_the_live_socket(
         assert (await expect_message(received)).event == EVENT
         assert reconnects.count == 0
 
-    assert "Recovered channel for topic %s" in caplog.text
+    assert "Recovered channel for topic <omitted>" in caplog.text
 
 
 @each_protocol
@@ -178,7 +178,7 @@ async def test_a_rejected_channel_rejoin_loses_the_topic(
         lost.only_error()
         assert TOPIC not in client.topic_subscriptions.copy()
         assert joins(phoenix_server) == REJOINED_ONCE
-    assert "Lost topic %s" in caplog.text
+    assert "Lost topic <omitted>" in caplog.text
 
 
 @each_protocol

{phoenix_channels_python_client-0.5.0 → phoenix_channels_python_client-0.5.2}/tests/test_security.py

@@ -15,6 +15,7 @@ from phoenix_channels_python_client import Client
 from phoenix_channels_python_client.client_types import ReconnectPolicy
 from phoenix_channels_python_client.diagnostics import ConnectionLogger
 from phoenix_channels_python_client.exceptions import SocketError
+from phoenix_channels_python_client.messages import SystemEvent
 from tests.fake_server import FakePhoenixServer
 
 URL_CREDENTIAL = "url/private+ credential?x=1&z=#[]"
@@ -199,6 +200,45 @@ class TestConnectionSecurity:
             target.disabled = previous_disabled
             target.removeFilter(reject)
 
+    @pytest.mark.parametrize(
+        ("message", "args", "rendered"),
+        [
+            (
+                "No handler found for event %s on topic %s",
+                ("user_join", "room:42"),
+                "No handler found for event <omitted> on topic <omitted>",
+            ),
+            (
+                "Channel %s is %s after %d attempts",
+                (SystemEvent.join, True, 3),
+                "Channel phx_join is True after <omitted> attempts",
+            ),
+            ("100%% of %s", ("room:42",), "100% of <omitted>"),
+            ("%s and %s", ("only-one",), "<omitted> and <omitted>"),
+            ("%d with text", ("not-a-number",), "<omitted> with text"),
+            ("%(topic)s by name", ({"topic": "room:42"},), "<omitted> by name"),
+        ],
+        ids=[
+            "strings",
+            "enum-bool-number",
+            "escape",
+            "too-few",
+            "type-mismatch",
+            "mapping",
+        ],
+    )
+    def test_placeholders_render_without_exposing_arguments(
+        self, message: str, args: tuple[object, ...], rendered: str
+    ) -> None:
+        client = Client("ws://127.0.0.1:1/socket", api_key="synthetic-key")
+        collector = BufferingHandler(10)
+        client.logger.addHandler(collector)
+        client.logger.setLevel(logging.WARNING)
+
+        client.logger.warning(message, *args)
+
+        assert [record.getMessage() for record in collector.buffer] == [rendered]
+
     @pytest.mark.parametrize(
         "header_names",
         [
@@ -395,6 +435,9 @@ class TestConnectionSecurity:
             "Parsing raw message:" in record.getMessage() for record in collector.buffer
         )
         assert any("OPEN" in record.getMessage() for record in collector.buffer)
+        messages = [record.getMessage() for record in collector.buffer]
+        assert "Connection callback failed: <omitted> [RuntimeError]" in messages
+        assert "Untrusted numeric identity: <omitted> <omitted> <omitted>" in messages
         for record in collector.buffer:
             assert identity not in repr(record.__dict__)
             assert session not in repr(record.__dict__)