python-twitchchat 1.0.0__py3-none-any.whl

python_twitchchat-1.0.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: python-twitchchat
+Version: 1.0.0
+Summary: Asyncio client for Twitch chat (IRC): typed events, callbacks and async iteration.
+Project-URL: Homepage, https://github.com/shughes-uk/python-twitchchat
+Author: shughes-uk
+Keywords: asyncio,chat,irc,twitch
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Communications :: Chat :: Internet Relay Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.15
+Description-Content-Type: text/markdown
+
+# python-twitchchat
+
+An asyncio client for [Twitch chat over IRC](https://dev.twitch.tv/docs/chat/irc/).
+It has no runtime dependencies and gives you typed events, an async iterator,
+callback registration, rate-limited sending, automatic PING/PONG and automatic
+reconnects.
+
+- **Requirements:** Python 3.15 or newer, standard library only.
+- **Install:** `pip install python-twitchchat` or `uv add python-twitchchat`. The import name is `twitchchat`.
+- Connects to `irc.chat.twitch.tv:6697` over TLS.
+
+## Usage
+
+### Reading chat anonymously
+
+If you don't pass a token, the client logs in as `justinfanNNNNN`. That's
+enough to read chat, but not to send.
+
+```python
+import asyncio
+
+from twitchchat import ChatMessage, TwitchChat, UserNotice
+
+
+async def main() -> None:
+    async with TwitchChat(["somechannel", "#another"]) as chat:
+        async for event in chat:  # every event; or chat.events(ChatMessage, UserNotice)
+            match event:
+                case ChatMessage():
+                    print(f"[#{event.channel}] <{event.display_name}> {event.text}")
+                case UserNotice():  # sub, resub, subgift, raid, announcement, ...
+                    print(f"[#{event.channel}] {event.msg_id}: {event.system_msg}")
+
+
+asyncio.run(main())
+```
+
+### Callbacks and sending messages
+
+```python
+import asyncio
+
+from twitchchat import ChatMessage, TwitchChat, UserNotice
+
+
+async def main() -> None:
+    chat = TwitchChat(["mychannel"], nick="mybot", token="oauth-token-with-chat:read-chat:edit")
+
+    @chat.on(ChatMessage)
+    async def on_message(msg: ChatMessage) -> None:
+        if msg.text == "!ping":
+            await chat.reply(msg, "pong")  # threaded reply
+
+    @chat.on(UserNotice)
+    def on_sub(notice: UserNotice) -> None:  # plain functions work too
+        if notice.msg_id in {"sub", "resub"}:
+            print(notice.login, notice.params.get("cumulative-months"))
+
+    async with chat:
+        await chat.send("mychannel", "hello chat")
+        await chat.wait_closed()  # run until closed or a fatal error
+
+
+asyncio.run(main())
+```
+
+### API overview
+
+`TwitchChat(channels, *, nick=None, token=None, reconnect=True, message_rate=(20, 30.0), join_rate=(20, 10.0), ...)`
+
+| Member | Purpose |
+| --- | --- |
+| `async with chat` / `await chat.connect()` / `await chat.close()` | Connect and authenticate, then join the configured channels. A bad token raises `AuthenticationError`. |
+| `async for event in chat` / `chat.events(*types, maxsize=10_000)` | Async iterator of events, optionally filtered by type. It buffers from the moment it is created (up to `maxsize` events; the oldest are dropped if you fall behind) and ends when the client closes or you `aclose()` it. |
+| `chat.on(EventType)` / `add_listener` / `remove_listener` | Register sync or async callbacks. They also match subclasses, so `chat.on(Event)` receives everything. |
+| `await chat.send(channel, text, reply_to=None)` / `await chat.reply(msg, text)` | Send a message, rate limited client-side. Anonymous sessions raise `TwitchChatError`. |
+| `await chat.join(channel)` / `await chat.part(channel)` | Change channels at runtime. Joined channels are rejoined after a reconnect. |
+| `await chat.send_raw(line)` | Send a raw IRC line. |
+| `await chat.wait_closed()` | Wait for the client to close, re-raising any fatal error. |
+
+**Events** are frozen dataclasses. Each one has `.raw` (the parsed `IrcMessage`) and `.tags`:
+
+| Event | IRC message |
+| --- | --- |
+| `ChatMessage` | `PRIVMSG` |
+| `UserNotice` | `USERNOTICE`: subs, raids, announcements and similar |
+| `Join`, `Part` | `JOIN`, `PART` |
+| `Notice` | `NOTICE` |
+| `ClearChat`, `ClearMsg` | `CLEARCHAT`, `CLEARMSG` |
+| `RoomState`, `UserState`, `GlobalUserState` | `ROOMSTATE`, `USERSTATE`, `GLOBALUSERSTATE` |
+| `Whisper` | `WHISPER` |
+| `Reconnect` | `RECONNECT` (the client reconnects on its own) |
+| `Connected` | `001`, emitted on every (re)connect |
+| `RawEvent` | Anything else |
+
+The low-level parser is public: `twitchchat.parse_line()` and `format_line()`
+handle IRCv3 tags, including escaped values such as `\s`, `\:` and `\\`.
+
+### Migrating from 0.1
+
+The old thread-based `twitch_chat(user, oauth, channels, client_id)` class has
+been replaced:
+
+| Old | New |
+| --- | --- |
+| `subscribeChatMessage(cb)` | `chat.on(ChatMessage)(cb)` |
+| `subscribeUsernotice(cb)` | `chat.on(UserNotice)(cb)` |
+| `send_message(channel, msg)` | `await chat.send(channel, msg)` |
+| `start()` / `join()` / `stop()` | `async with` / `wait_closed()` / `close()` |
+
+Callbacks now get typed dataclasses instead of dicts of raw tags; raw tags are
+still available as `event.tags`. The unused `client_id` argument has been
+dropped, because the library makes no HTTP API calls.
+
+## Twitch platform notes (checked October 2026)
+
+- **IRC still works, but Twitch recommends EventSub.** The product lifecycle
+  page lists Chat (IRC) as active, and no shutdown date has been announced.
+  Twitch's [IRC migration guide](https://dev.twitch.tv/docs/chat/irc-migration/)
+  recommends that new bots read chat through EventSub (`channel.chat.message`)
+  and send through the Helix *Send Chat Message* API. Some newer features only
+  exist there.
+- **Endpoints:** use `irc.chat.twitch.tv:6697` (TLS) or `wss://irc-ws.chat.twitch.tv:443`.
+  Non-TLS WebSocket connections were decommissioned on 2025-08-15. The old code
+  used plaintext port 6667; this version uses TLS by default.
+- **Auth:** `PASS oauth:<user access token>` followed by `NICK <login>`. Reading
+  needs the `chat:read` scope and sending needs `chat:edit`. You can get a token
+  through any OAuth flow, for example the
+  [device code flow](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#device-code-grant-flow).
+  Anonymous `justinfan` logins aren't documented, but they still work for
+  reading; this was verified live.
+- **Rate limits:** normal accounts get 20 messages per 30 seconds, plus 1 message
+  per second per channel. Where you are mod, VIP or broadcaster the limit is 100
+  per 30 seconds, so pass `message_rate=(100, 30.0)`. Joins are limited to 20 per
+  10 seconds. Going over the message limit can get your messages ignored for an
+  hour. The client limits itself to the normal-user defaults.
+- **Kraken (v5) is gone:** it was shut down in February 2023. This library never
+  needed it, and the old `client_id` parameter did nothing, so it was removed.
+  Channel hosting (`HOSTTARGET`) was also removed by Twitch.
+
+## Example
+
+[`examples/watch_chat.py`](examples/watch_chat.py) watches channels anonymously
+and prints parsed events. It exits non-zero if no chat message arrives within
+the time limit.
+
+```sh
+uv run examples/watch_chat.py --seconds 60 somebigchannel anotherone
+```
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/). `.python-version` pins
+Python 3.15, which uv downloads automatically.
+
+```sh
+uv sync                  # create .venv with dev tools (ruff, ty, pytest, pytest-asyncio)
+uv run ruff check        # lint
+uv run ruff format       # format (use --check in CI)
+uv run ty check          # type check
+uv run pytest            # unit tests (parser + client against a local fake IRC server)
+```
+
+CI (`.github/workflows/ci.yml`) runs all four checks on every push and pull
+request. Tests run on Linux, Windows and macOS.
+
+## Releasing
+
+The version comes from the git tag through `hatch-vcs`, so there is no version
+number to edit by hand.
+
+1. One-time setup on PyPI: go to *Your projects → Publishing → Add a new pending
+   publisher* (or the project's *Settings → Publishing* once it exists). Choose
+   GitHub and fill in:
+   - owner `shughes-uk`
+   - repository `python-twitchchat`
+   - workflow `release.yml`
+   - environment `pypi`
+
+   Then create an environment named `pypi` in the GitHub repository settings.
+   You can add required reviewers to it if you want manual approval before each
+   publish.
+2. Tag and push:
+   ```sh
+   git tag v2.0.0
+   git push origin v2.0.0
+   ```
+3. `.github/workflows/release.yml` then:
+   - runs CI
+   - runs `uv build` and checks the built version matches the tag
+   - publishes to PyPI with trusted publishing (no API token needed)
+   - creates a GitHub Release with generated notes and the sdist and wheel attached
+
+   Tags such as `v2.1.0rc1` are marked as pre-releases.
+
+Note that the distribution name is **`python-twitchchat`**, because `twitchchat`
+is already taken on PyPI by an unrelated project.

python_twitchchat-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+twitchchat/__init__.py,sha256=KCL-EtxGzmRyXLwmvXwXNW57Cm_zJmui0hZsqMnaVz4,1214
+twitchchat/client.py,sha256=75GqTx34AFZ6bGC65kNf4AmG86EWzXv2Z2OKDSCiM0s,21886
+twitchchat/events.py,sha256=2WQYCNhgaOnz1Gw19uVqKxTlzoN8piQnGkai-FAJkTU,8747
+twitchchat/irc.py,sha256=IUXQb7wi5qEJIC86Ozfkrcidtb_TQ7j9l8h5cEuvHKI,5025
+twitchchat/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+python_twitchchat-1.0.0.dist-info/METADATA,sha256=hkjLKtwuX9ul8pjOkY1NGkPFz171n4NitwCOwesyiA0,9124
+python_twitchchat-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_twitchchat-1.0.0.dist-info/RECORD,,

python_twitchchat-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

twitchchat/__init__.py

@@ -0,0 +1,68 @@
+"""Asyncio client for Twitch chat over IRC."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .client import (
+    DEFAULT_HOST,
+    DEFAULT_PORT,
+    AuthenticationError,
+    EventStream,
+    Listener,
+    RateLimiter,
+    TwitchChat,
+    TwitchChatError,
+)
+from .events import (
+    ChatMessage,
+    ClearChat,
+    ClearMsg,
+    Connected,
+    Event,
+    GlobalUserState,
+    Join,
+    Notice,
+    Part,
+    RawEvent,
+    Reconnect,
+    RoomState,
+    UserNotice,
+    UserState,
+    Whisper,
+)
+from .irc import IrcMessage, Prefix, format_line, parse_line
+
+try:
+    __version__ = version("python-twitchchat")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "0.0.0"
+
+__all__ = [
+    "DEFAULT_HOST",
+    "DEFAULT_PORT",
+    "AuthenticationError",
+    "ChatMessage",
+    "ClearChat",
+    "ClearMsg",
+    "Connected",
+    "Event",
+    "EventStream",
+    "GlobalUserState",
+    "IrcMessage",
+    "Join",
+    "Listener",
+    "Notice",
+    "Part",
+    "Prefix",
+    "RateLimiter",
+    "RawEvent",
+    "Reconnect",
+    "RoomState",
+    "TwitchChat",
+    "TwitchChatError",
+    "UserNotice",
+    "UserState",
+    "Whisper",
+    "__version__",
+    "format_line",
+    "parse_line",
+]

twitchchat/client.py

@@ -0,0 +1,564 @@
+"""asyncio Twitch chat client."""
+
+import asyncio
+import contextlib
+import inspect
+import logging
+import secrets
+import weakref
+from collections import deque
+from collections.abc import AsyncIterator, Awaitable, Callable, Iterable
+from typing import Protocol, Self, overload
+lazy import ssl
+
+from .events import ChatMessage, Connected, Event, Notice, Reconnect, event_from_irc
+from .irc import format_line, parse_line
+
+__all__ = [
+    "DEFAULT_HOST",
+    "DEFAULT_PORT",
+    "AuthenticationError",
+    "EventStream",
+    "Listener",
+    "RateLimiter",
+    "TwitchChat",
+    "TwitchChatError",
+]
+
+logger = logging.getLogger("twitchchat")
+
+DEFAULT_HOST = "irc.chat.twitch.tv"
+DEFAULT_PORT = 6697
+DEFAULT_CAPABILITIES = ("twitch.tv/tags", "twitch.tv/commands", "twitch.tv/membership")
+_AUTH_FAILURES = ("Login authentication failed", "Improperly formatted auth")
+_RECONNECT_REQUESTED = "server requested reconnect"
+_STABLE_AFTER = 30.0  # seconds a connection must last before reconnect backoff resets
+
+type Listener[E: Event] = Callable[[E], Awaitable[None] | None]
+
+
+class TwitchChatError(Exception):
+    """Base error for this library."""
+
+
+class AuthenticationError(TwitchChatError):
+    """Twitch rejected the nick/token."""
+
+
+class RateLimiter:
+    """Sliding-window limiter: at most ``limit`` acquisitions per ``period`` seconds."""
+
+    def __init__(self, limit: int, period: float) -> None:
+        if limit < 1 or period <= 0:
+            msg = "limit must be >= 1 and period > 0"
+            raise ValueError(msg)
+        self.limit = limit
+        self.period = period
+        self._stamps: deque[float] = deque()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        async with self._lock:
+            loop = asyncio.get_running_loop()
+            while True:
+                now = loop.time()
+                while self._stamps and now - self._stamps[0] >= self.period:
+                    self._stamps.popleft()
+                if len(self._stamps) < self.limit:
+                    self._stamps.append(now)
+                    return
+                await asyncio.sleep(self.period - (now - self._stamps[0]))
+
+
+class _Sink(Protocol):
+    def _offer(self, event: Event) -> None: ...
+    def _finish(self) -> None: ...
+
+
+class _Closed:
+    pass
+
+
+_CLOSED = _Closed()
+
+
+class EventStream[E: Event]:
+    """Async iterator over events, created by :meth:`TwitchChat.events`.
+
+    Buffers from the moment it is created until it is closed (``aclose()``,
+    ``async with``, the client closing, or the stream being garbage collected).
+    At most ``maxsize`` events are buffered; when the consumer falls behind, the
+    oldest events are dropped (with a warning).
+    """
+
+    def __init__(self, chat: TwitchChat, types: tuple[type[E], ...], maxsize: int = 10_000) -> None:
+        if maxsize < 1:
+            msg = "maxsize must be >= 1"
+            raise ValueError(msg)
+        self._chat = chat
+        self._types = types
+        self._maxsize = maxsize
+        self._queue: asyncio.Queue[E | _Closed] = asyncio.Queue()
+        self._done = False
+        self.dropped = 0
+        chat._streams.add(self)  # noqa: SLF001
+        if chat.closed:
+            self._finish()
+
+    def _offer(self, event: Event) -> None:
+        if self._done or (self._types and not isinstance(event, self._types)):
+            return
+        if self._queue.qsize() >= self._maxsize:
+            self._queue.get_nowait()
+            if not self.dropped:
+                logger.warning("event stream full (%d); dropping oldest events", self._maxsize)
+            self.dropped += 1
+        self._queue.put_nowait(event)  # ty: ignore[invalid-argument-type]
+
+    def _finish(self) -> None:
+        if not self._done:
+            self._done = True
+            # The queue itself is unbounded, so the sentinel always fits.
+            self._queue.put_nowait(_CLOSED)
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __anext__(self) -> E:
+        item = await self._queue.get()
+        if isinstance(item, _Closed):
+            # Put the sentinel back so later and concurrent __anext__ calls also end.
+            self._queue.put_nowait(item)
+            self._chat._streams.discard(self)  # noqa: SLF001
+            if self._chat.exception is not None:
+                raise self._chat.exception
+            raise StopAsyncIteration
+        return item
+
+    async def aclose(self) -> None:
+        self._chat._streams.discard(self)  # noqa: SLF001
+        self._finish()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+
+def _normalize_channel(channel: str) -> str:
+    name = channel.strip().lstrip("#").lower()
+    # Space/comma would turn into extra parameters or a multi-channel JOIN.
+    if not name or any(c in name for c in " ,\r\n\0"):
+        msg = f"invalid channel name: {channel!r}"
+        raise ValueError(msg)
+    return name
+
+
+class TwitchChat:
+    """An asyncio Twitch chat (IRC) client.
+
+    With no ``token`` it logs in anonymously (``justinfanNNNNN``), which can read
+    but not send. Use as an async context manager::
+
+        async with TwitchChat(["somechannel"]) as chat:
+            async for event in chat:
+                ...
+
+    Args:
+        channels: channels to join once connected (with or without ``#``).
+        nick: login name of the token's account (required with ``token``).
+        token: OAuth user access token with ``chat:read`` (and ``chat:edit`` to
+            send); the ``oauth:`` prefix is optional.
+        host, port: IRC server (TLS by default).
+        tls: ``True`` for default TLS, ``False`` for plaintext, or an SSLContext.
+        reconnect: reconnect automatically on disconnects / ``RECONNECT``.
+        message_rate: ``(limit, period)`` for outgoing PRIVMSGs. Twitch allows 20
+            per 30s for normal users, 100 per 30s where you are mod/VIP/broadcaster.
+        join_rate: ``(limit, period)`` for JOINs (Twitch: 20 per 10s).
+        capabilities: IRCv3 capabilities to request.
+        read_timeout: seconds without any data before the connection is
+            considered dead (Twitch PINGs about every 5 minutes).
+    """
+
+    def __init__(  # noqa: PLR0913
+        self,
+        channels: Iterable[str] = (),
+        *,
+        nick: str | None = None,
+        token: str | None = None,
+        host: str = DEFAULT_HOST,
+        port: int = DEFAULT_PORT,
+        tls: bool | ssl.SSLContext = True,
+        reconnect: bool = True,
+        message_rate: tuple[int, float] = (20, 30.0),
+        join_rate: tuple[int, float] = (20, 10.0),
+        capabilities: Iterable[str] = DEFAULT_CAPABILITIES,
+        connect_timeout: float = 15.0,
+        read_timeout: float = 360.0,
+    ) -> None:
+        if token is not None and not nick:
+            msg = "nick is required when a token is given"
+            raise ValueError(msg)
+        self.anonymous = token is None
+        self.nick = (nick or f"justinfan{secrets.randbelow(90000) + 10000}").lower()
+        self._token = None if token is None else "oauth:" + token.removeprefix("oauth:")
+        self.host = host
+        self.port = port
+        self._tls = tls
+        self.reconnect = reconnect
+        self.capabilities = tuple(capabilities)
+        self.connect_timeout = connect_timeout
+        self.read_timeout = read_timeout
+        self._message_limiter = RateLimiter(*message_rate)
+        self._join_limiter = RateLimiter(*join_rate)
+
+        self.channels: set[str] = {_normalize_channel(c) for c in channels}
+        self._listeners: dict[type[Event], list[Listener[Event]]] = {}
+        # Weak, so streams abandoned without aclose() (e.g. ``break`` out of
+        # ``async for event in chat``) are collected instead of buffering forever.
+        self._streams: weakref.WeakSet[_Sink] = weakref.WeakSet()
+        self._reader: asyncio.StreamReader | None = None
+        self._writer: asyncio.StreamWriter | None = None
+        self._ready = asyncio.Event()
+        self._welcome: asyncio.Future[None] | None = None
+        self._task: asyncio.Task[None] | None = None
+        self._closed = False
+        self._closed_event = asyncio.Event()
+        self._reconnect_requested = False
+        self._background: set[asyncio.Task[None]] = set()
+        self._started = False
+        self.exception: BaseException | None = None
+
+    # -- lifecycle -----------------------------------------------------------------
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    @property
+    def connected(self) -> bool:
+        return self._ready.is_set()
+
+    async def connect(self) -> None:
+        """Connect, authenticate and join the configured channels.
+
+        Raises:
+            AuthenticationError: if Twitch rejects the credentials.
+            TimeoutError: if the server does not welcome us in time.
+            OSError: on network errors.
+        """
+        if self._started:
+            msg = "connect() may only be called once"
+            raise TwitchChatError(msg)
+        self._started = True
+        try:
+            await self._open()
+        except BaseException:
+            await self._shutdown(None)
+            raise
+        self._task = asyncio.create_task(self._run(), name=f"twitchchat-{self.nick}")
+
+    async def close(self) -> None:
+        """Close the connection and end all event streams."""
+        if self._task is not None and self._task is not asyncio.current_task():
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+        await self._shutdown(None)
+
+    async def wait_closed(self) -> None:
+        """Wait until the client closes; re-raise the error that closed it, if any."""
+        if self._task is not None:
+            with contextlib.suppress(asyncio.CancelledError):
+                await asyncio.shield(self._task)
+        if self.exception is not None:
+            raise self.exception
+
+    async def __aenter__(self) -> Self:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    # -- listeners & streams ---------------------------------------------------------
+
+    def add_listener[E: Event](self, event_type: type[E], callback: Listener[E]) -> None:
+        """Call ``callback(event)`` for every event of ``event_type`` (or a subclass).
+
+        Callbacks may be plain functions or coroutine functions; they run in order
+        on the reader task, so long-running work should be offloaded.
+        """
+        self._listeners.setdefault(event_type, []).append(callback)  # ty: ignore[invalid-argument-type]
+
+    def remove_listener[E: Event](self, event_type: type[E], callback: Listener[E]) -> None:
+        with contextlib.suppress(KeyError, ValueError):
+            self._listeners[event_type].remove(callback)  # ty: ignore[invalid-argument-type]
+
+    def on[E: Event](self, event_type: type[E]) -> Callable[[Listener[E]], Listener[E]]:
+        """Decorator form of :meth:`add_listener`."""
+
+        def decorator(callback: Listener[E]) -> Listener[E]:
+            self.add_listener(event_type, callback)
+            return callback
+
+        return decorator
+
+    @overload
+    def events(self, *, maxsize: int = ...) -> EventStream[Event]: ...
+    @overload
+    def events[E: Event](self, *types: type[E], maxsize: int = ...) -> EventStream[E]: ...
+    def events(self, *types: type[Event], maxsize: int = 10_000) -> EventStream[Event]:
+        """Return an async iterator of events, optionally filtered by type.
+
+        At most ``maxsize`` unconsumed events are buffered (oldest dropped first).
+        """
+        return EventStream(self, types, maxsize)
+
+    def __aiter__(self) -> AsyncIterator[Event]:
+        return self.events()
+
+    # -- commands --------------------------------------------------------------------
+
+    async def send(self, channel: str, text: str, *, reply_to: str | None = None) -> None:
+        """Send a chat message (rate limited). ``reply_to`` is a message id to reply to.
+
+        Raises:
+            TwitchChatError: when anonymous or closed.
+        """
+        if self.anonymous:
+            msg = "anonymous connections cannot send messages; pass nick and token"
+            raise TwitchChatError(msg)
+        tags = {"reply-parent-msg-id": reply_to} if reply_to else None
+        line = format_line("PRIVMSG", "#" + _normalize_channel(channel), text, tags=tags)
+        await self._message_limiter.acquire()
+        await self._send_line(line)
+
+    async def reply(self, message: ChatMessage, text: str) -> None:
+        """Reply to a chat message in its channel (threaded reply)."""
+        await self.send(message.channel, text, reply_to=message.id)
+
+    async def join(self, channel: str) -> None:
+        """Join a channel (and rejoin it after reconnects)."""
+        name = _normalize_channel(channel)
+        self.channels.add(name)
+        if self.connected:
+            await self._join_limiter.acquire()
+            await self._send_line(format_line("JOIN", "#" + name))
+
+    async def part(self, channel: str) -> None:
+        """Leave a channel."""
+        name = _normalize_channel(channel)
+        self.channels.discard(name)
+        if self.connected:
+            await self._send_line(format_line("PART", "#" + name))
+
+    async def send_raw(self, line: str) -> None:
+        """Send one raw IRC line (CRLF is appended if missing). Not rate limited.
+
+        Raises:
+            ValueError: if the line contains CR, LF or NUL other than a final CRLF.
+        """
+        body = line.removesuffix("\r\n")
+        if "\r" in body or "\n" in body or "\0" in body:
+            msg = "raw line must be a single IRC line (no embedded CR, LF or NUL)"
+            raise ValueError(msg)
+        await self._send_line(body + "\r\n")
+
+    # -- internals -------------------------------------------------------------------
+
+    async def _send_line(self, line: str) -> None:
+        if self._closed:
+            msg = "client is closed"
+            raise TwitchChatError(msg)
+        if not self._ready.is_set():
+            waiters = [
+                asyncio.ensure_future(self._ready.wait()),
+                asyncio.ensure_future(self._closed_event.wait()),
+            ]
+            try:
+                await asyncio.wait(waiters, return_when=asyncio.FIRST_COMPLETED)
+            finally:
+                for w in waiters:
+                    w.cancel()
+        writer = self._writer
+        if writer is None:
+            msg = "not connected"
+            raise TwitchChatError(msg)
+        logger.debug("> %s", line.rstrip())
+        writer.write(line.encode())
+        await writer.drain()
+
+    def _write_now(self, line: str) -> None:
+        if self._writer is not None:
+            if not line.startswith("PASS"):
+                logger.debug("> %s", line.rstrip())
+            self._writer.write(line.encode())
+
+    async def _open(self) -> None:
+        ssl_arg: ssl.SSLContext | bool | None = self._tls or None
+        self._reader, self._writer = await asyncio.wait_for(
+            asyncio.open_connection(self.host, self.port, ssl=ssl_arg),
+            self.connect_timeout,
+        )
+        self._welcome = asyncio.get_running_loop().create_future()
+        if self.capabilities:
+            self._write_now(format_line("CAP", "REQ", " ".join(self.capabilities)))
+        self._write_now(format_line("PASS", self._token or "SCHMOOPIIE"))
+        self._write_now(format_line("NICK", self.nick))
+        await self._writer.drain()
+        # Read until welcomed (or rejected) without the main loop running yet.
+        async with asyncio.timeout(self.connect_timeout):
+            while not self._welcome.done():
+                if not await self._read_one():
+                    msg = "connection closed during login"
+                    raise ConnectionError(msg)
+        self._welcome.result()
+
+    async def _read_one(self) -> bool:
+        """Read and handle one line. Returns False on EOF."""
+        assert self._reader is not None  # noqa: S101
+        data = await self._reader.readline()
+        if not data:
+            return False
+        line = data.decode("utf-8", errors="replace").rstrip("\r\n")
+        if not line:
+            return True
+        logger.debug("< %s", line)
+        # A malformed line from the server must never kill the reader.
+        try:
+            msg = parse_line(line)
+            if msg.command == "PING":
+                self._write_now(format_line("PONG", msg.trailing or "tmi.twitch.tv"))
+                return True
+            event = event_from_irc(msg)
+        except Exception:
+            logger.warning("unparseable line: %r", line, exc_info=True)
+            return True
+        await self._handle(event)
+        return True
+
+    async def _handle(self, event: Event) -> None:
+        if isinstance(event, Connected):
+            self._on_welcome()
+        elif isinstance(event, Reconnect):
+            self._reconnect_requested = True
+        elif (
+            isinstance(event, Notice)
+            and event.text.startswith(_AUTH_FAILURES)
+            and self._welcome is not None
+            and not self._welcome.done()
+        ):
+            self._welcome.set_exception(AuthenticationError(event.text))
+        await self._dispatch(event)
+
+    def _on_welcome(self) -> None:
+        self._ready.set()
+        if self._welcome is not None and not self._welcome.done():
+            self._welcome.set_result(None)
+        # Each channel counts as a join attempt; join in the background, rate limited.
+        if self.channels:
+            task = asyncio.create_task(self._join_all(sorted(self.channels)))
+            self._background.add(task)
+            task.add_done_callback(self._background.discard)
+
+    async def _join_all(self, channels: list[str]) -> None:
+        for name in channels:
+            await self._join_limiter.acquire()
+            if name in self.channels and self._ready.is_set():
+                with contextlib.suppress(OSError, TwitchChatError):
+                    await self._send_line(format_line("JOIN", "#" + name))
+
+    async def _dispatch(self, event: Event) -> None:
+        for stream in list(self._streams):
+            stream._offer(event)  # noqa: SLF001
+        for event_type, callbacks in list(self._listeners.items()):
+            if not isinstance(event, event_type):
+                continue
+            for callback in list(callbacks):
+                try:
+                    result = callback(event)
+                    if inspect.isawaitable(result):
+                        await result
+                except Exception:
+                    logger.exception("error in listener %r", callback)
+
+    async def _run(self) -> None:
+        error: BaseException | None = None
+        backoff = 1.0
+        loop = asyncio.get_running_loop()
+        try:
+            while True:
+                connected_at = loop.time()
+                reason = await self._read_loop()
+                self._drop_connection()
+                if not self.reconnect or self._closed:
+                    break
+                logger.info("disconnected (%s); reconnecting", reason)
+                if reason == _RECONNECT_REQUESTED or loop.time() - connected_at > _STABLE_AFTER:
+                    backoff = 1.0
+                else:
+                    # Dropped soon after connecting: back off instead of hammering.
+                    await asyncio.sleep(backoff)
+                    backoff = min(backoff * 2, 60.0)
+                while True:
+                    try:
+                        await self._open()
+                        break
+                    except AuthenticationError:
+                        raise
+                    except (OSError, TimeoutError, ConnectionError) as e:
+                        logger.warning("reconnect failed: %s; retrying in %.0fs", e, backoff)
+                        self._drop_connection()
+                        await asyncio.sleep(backoff)
+                        backoff = min(backoff * 2, 60.0)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # noqa: BLE001
+            error = e
+        finally:
+            await self._shutdown(error)
+
+    async def _read_loop(self) -> str:
+        while True:
+            if self._closed:  # close() was called from a listener on this task
+                return "closed"
+            try:
+                async with asyncio.timeout(self.read_timeout):
+                    alive = await self._read_one()
+            except TimeoutError:
+                return "read timeout"
+            except OSError as e:
+                return f"error: {e}"
+            if not alive:
+                return "connection closed by server"
+            if self._reconnect_requested:
+                self._reconnect_requested = False
+                return _RECONNECT_REQUESTED
+
+    def _drop_connection(self) -> None:
+        self._ready.clear()
+        # Pending rate-limited joins belong to the old connection; the next
+        # welcome schedules a fresh join of every channel.
+        for task in list(self._background):
+            task.cancel()
+        if self._writer is not None:
+            self._writer.close()
+        self._reader = self._writer = None
+
+    async def _shutdown(self, error: BaseException | None) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._closed_event.set()
+        self.exception = error
+        for task in list(self._background):
+            task.cancel()
+        writer = self._writer
+        self._drop_connection()
+        if writer is not None:
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(writer.wait_closed(), 2)
+        for stream in list(self._streams):
+            stream._finish()  # noqa: SLF001

twitchchat/events.py

@@ -0,0 +1,303 @@
+"""Typed event dataclasses built from Twitch IRC messages."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+lazy from .irc import IrcMessage
+
+__all__ = [
+    "ChatMessage",
+    "ClearChat",
+    "ClearMsg",
+    "Connected",
+    "Event",
+    "GlobalUserState",
+    "Join",
+    "Notice",
+    "Part",
+    "RawEvent",
+    "Reconnect",
+    "RoomState",
+    "UserNotice",
+    "UserState",
+    "Whisper",
+    "event_from_irc",
+    "parse_badges",
+]
+
+_ACTION_PREFIX = "\x01ACTION "
+
+
+def parse_badges(value: str | None) -> dict[str, str]:
+    """Parse a ``badges``/``badge-info`` tag (``subscriber/12,premium/1``)."""
+    if not value:
+        return {}
+    badges: dict[str, str] = {}
+    for item in value.split(","):
+        name, _, version = item.partition("/")
+        if name:
+            badges[name] = version
+    return badges
+
+
+def _timestamp(tags: dict[str, str]) -> datetime | None:
+    ts = tags.get("tmi-sent-ts")
+    if ts and ts.isascii() and ts.isdigit():
+        try:
+            return datetime.fromtimestamp(int(ts) / 1000, tz=UTC)
+        except OverflowError, OSError, ValueError:
+            return None
+    return None
+
+
+def _int(value: str | None) -> int | None:
+    digits = "" if value is None else value.removeprefix("-")
+    if value is None or not (digits.isascii() and digits.isdigit()):
+        return None
+    try:
+        return int(value)
+    except ValueError:  # non-numeric, or longer than int's max string digits
+        return None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Event:
+    """Base class for every event. ``raw`` is the underlying parsed IRC line."""
+
+    raw: IrcMessage = field(repr=False)
+
+    @property
+    def tags(self) -> dict[str, str]:
+        return self.raw.tags
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Connected(Event):
+    """Successfully authenticated (``001`` welcome). Emitted on every (re)connect."""
+
+    nick: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ChatMessage(Event):
+    """A chat message in a channel (``PRIVMSG``)."""
+
+    channel: str
+    login: str
+    text: str
+    display_name: str
+    id: str | None = None
+    user_id: str | None = None
+    room_id: str | None = None
+    color: str | None = None
+    badges: dict[str, str] = field(default_factory=dict)
+    is_action: bool = False
+    bits: int | None = None
+    timestamp: datetime | None = None
+
+    @property
+    def is_mod(self) -> bool:
+        return self.tags.get("mod") == "1" or "broadcaster" in self.badges
+
+    @property
+    def is_subscriber(self) -> bool:
+        return self.tags.get("subscriber") == "1"
+
+    @property
+    def is_first_message(self) -> bool:
+        return self.tags.get("first-msg") == "1"
+
+    @property
+    def reply_parent_id(self) -> str | None:
+        return self.tags.get("reply-parent-msg-id")
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserNotice(Event):
+    """Subs, resubs, gift subs, raids, announcements ... (``USERNOTICE``).
+
+    ``msg_id`` is the kind (``sub``, ``resub``, ``subgift``, ``raid``,
+    ``announcement`` ...), ``params`` holds the ``msg-param-*`` tags with the
+    prefix stripped, and ``text`` is the optional user-supplied message.
+    """
+
+    channel: str
+    msg_id: str
+    login: str | None
+    display_name: str | None
+    system_msg: str
+    text: str | None = None
+    params: dict[str, str] = field(default_factory=dict)
+    timestamp: datetime | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Join(Event):
+    """A user joined a channel (requires the ``twitch.tv/membership`` capability)."""
+
+    channel: str
+    login: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Part(Event):
+    """A user left a channel."""
+
+    channel: str
+    login: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Notice(Event):
+    """A server notice. ``channel`` is ``None`` for global notices."""
+
+    channel: str | None
+    msg_id: str | None
+    text: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClearChat(Event):
+    """Chat cleared (``login`` is ``None``) or a user banned/timed out."""
+
+    channel: str
+    login: str | None
+    ban_duration: int | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClearMsg(Event):
+    """A single message was deleted."""
+
+    channel: str
+    login: str | None
+    target_msg_id: str | None
+    text: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RoomState(Event):
+    """Channel chat settings (emote-only, slow mode, ...). Inspect ``tags``."""
+
+    channel: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UserState(Event):
+    """Your own state in a channel (sent on join and after you send a message)."""
+
+    channel: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class GlobalUserState(Event):
+    """Your own global state, sent after authenticating with a real token."""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Whisper(Event):
+    """A whisper (private message) to the authenticated user."""
+
+    login: str
+    text: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Reconnect(Event):
+    """Twitch is about to drop the connection; the client reconnects automatically."""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RawEvent(Event):
+    """Any other IRC message (numerics, CAP ACK, ...) not mapped to a typed event."""
+
+
+def _nick(msg: IrcMessage) -> str:
+    return msg.prefix.nick if msg.prefix else ""
+
+
+def _chat_message(msg: IrcMessage) -> ChatMessage:
+    tags = msg.tags
+    text = msg.trailing or ""
+    is_action = text.startswith(_ACTION_PREFIX) and text.endswith("\x01")
+    if is_action:
+        text = text[len(_ACTION_PREFIX) : -1]
+    login = _nick(msg)
+    return ChatMessage(
+        raw=msg,
+        channel=msg.channel or "",
+        login=login,
+        text=text,
+        display_name=tags.get("display-name") or login,
+        id=tags.get("id"),
+        user_id=tags.get("user-id"),
+        room_id=tags.get("room-id"),
+        color=tags.get("color") or None,
+        badges=parse_badges(tags.get("badges")),
+        is_action=is_action,
+        bits=_int(tags.get("bits")),
+        timestamp=_timestamp(tags),
+    )
+
+
+def _user_notice(msg: IrcMessage) -> UserNotice:
+    tags = msg.tags
+    prefix = "msg-param-"
+    return UserNotice(
+        raw=msg,
+        channel=msg.channel or "",
+        msg_id=tags.get("msg-id", ""),
+        login=tags.get("login"),
+        display_name=tags.get("display-name"),
+        system_msg=tags.get("system-msg", ""),
+        text=msg.params[1] if len(msg.params) > 1 else None,
+        params={k.removeprefix(prefix): v for k, v in tags.items() if k.startswith(prefix)},
+        timestamp=_timestamp(tags),
+    )
+
+
+def event_from_irc(msg: IrcMessage) -> Event:  # noqa: PLR0911, PLR0912
+    """Convert a parsed IRC message into the most specific :class:`Event`."""
+    channel = msg.channel
+    match msg.command:
+        case "PRIVMSG" if channel is not None:
+            return _chat_message(msg)
+        case "USERNOTICE" if channel is not None:
+            return _user_notice(msg)
+        case "JOIN" if channel is not None:
+            return Join(raw=msg, channel=channel, login=_nick(msg))
+        case "PART" if channel is not None:
+            return Part(raw=msg, channel=channel, login=_nick(msg))
+        case "NOTICE":
+            return Notice(
+                raw=msg, channel=channel, msg_id=msg.tags.get("msg-id"), text=msg.trailing or ""
+            )
+        case "CLEARCHAT" if channel is not None:
+            return ClearChat(
+                raw=msg,
+                channel=channel,
+                login=msg.params[1] if len(msg.params) > 1 else None,
+                ban_duration=_int(msg.tags.get("ban-duration")),
+            )
+        case "CLEARMSG" if channel is not None:
+            return ClearMsg(
+                raw=msg,
+                channel=channel,
+                login=msg.tags.get("login"),
+                target_msg_id=msg.tags.get("target-msg-id"),
+                text=msg.params[1] if len(msg.params) > 1 else "",
+            )
+        case "ROOMSTATE" if channel is not None:
+            return RoomState(raw=msg, channel=channel)
+        case "USERSTATE" if channel is not None:
+            return UserState(raw=msg, channel=channel)
+        case "GLOBALUSERSTATE":
+            return GlobalUserState(raw=msg)
+        case "WHISPER":
+            return Whisper(raw=msg, login=_nick(msg), text=msg.trailing or "")
+        case "RECONNECT":
+            return Reconnect(raw=msg)
+        case "001":
+            return Connected(raw=msg, nick=msg.params[0] if msg.params else "")
+        case _:
+            return RawEvent(raw=msg)

twitchchat/irc.py

@@ -0,0 +1,165 @@
+"""Low-level parsing and formatting of Twitch IRC (IRCv3 with tags) lines."""
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "IrcMessage",
+    "Prefix",
+    "escape_tag_value",
+    "format_line",
+    "parse_line",
+    "parse_tags",
+    "unescape_tag_value",
+]
+
+_UNESCAPES = {":": ";", "s": " ", "\\": "\\", "r": "\r", "n": "\n"}
+_ESCAPES = {";": "\\:", " ": "\\s", "\\": "\\\\", "\r": "\\r", "\n": "\\n"}
+
+
+def unescape_tag_value(value: str) -> str:
+    r"""Unescape an IRCv3 tag value (``\s`` -> space, ``\:`` -> ``;`` ...).
+
+    Unknown escapes drop the backslash; a trailing lone backslash is removed,
+    as required by the IRCv3 message-tags specification.
+    """
+    if "\\" not in value:
+        return value
+    out: list[str] = []
+    chars = iter(value)
+    for ch in chars:
+        if ch != "\\":
+            out.append(ch)
+            continue
+        nxt = next(chars, None)
+        if nxt is None:
+            break
+        out.append(_UNESCAPES.get(nxt, nxt))
+    return "".join(out)
+
+
+def escape_tag_value(value: str) -> str:
+    """Escape a string for use as an IRCv3 tag value."""
+    return "".join(_ESCAPES.get(ch, ch) for ch in value)
+
+
+def parse_tags(raw: str) -> dict[str, str]:
+    """Parse the tag section of a line (without the leading ``@``)."""
+    tags: dict[str, str] = {}
+    for item in raw.split(";"):
+        if not item:
+            continue
+        key, _, value = item.partition("=")
+        tags[key] = unescape_tag_value(value)
+    return tags
+
+
+@dataclass(frozen=True, slots=True)
+class Prefix:
+    """The source of an IRC message: ``nick!user@host`` or a bare server name."""
+
+    nick: str
+    user: str | None = None
+    host: str | None = None
+
+    @classmethod
+    def parse(cls, raw: str) -> Prefix:
+        nick, _, rest = raw.partition("!")
+        if rest:
+            user, _, host = rest.partition("@")
+            return cls(nick, user, host or None)
+        nick, _, host = nick.partition("@")
+        return cls(nick, None, host or None)
+
+    def __str__(self) -> str:
+        s = self.nick
+        if self.user is not None:
+            s += f"!{self.user}"
+        if self.host is not None:
+            s += f"@{self.host}"
+        return s
+
+
+@dataclass(frozen=True, slots=True)
+class IrcMessage:
+    """A single parsed IRC line."""
+
+    command: str
+    params: tuple[str, ...] = ()
+    tags: dict[str, str] = field(default_factory=dict)
+    prefix: Prefix | None = None
+    raw: str = ""
+
+    @property
+    def channel(self) -> str | None:
+        """The channel (without ``#``) if the first parameter is a channel."""
+        if self.params and self.params[0].startswith("#"):
+            return self.params[0][1:]
+        return None
+
+    @property
+    def trailing(self) -> str | None:
+        """The last parameter, which for most commands is the message text."""
+        return self.params[-1] if self.params else None
+
+
+def parse_line(line: str) -> IrcMessage:
+    """Parse one IRC line (with or without the trailing CRLF).
+
+    Raises:
+        ValueError: if the line contains no command.
+    """
+    raw = line.rstrip("\r\n")
+    rest = raw
+    tags: dict[str, str] = {}
+    prefix: Prefix | None = None
+
+    if rest.startswith("@"):
+        tag_part, _, rest = rest[1:].partition(" ")
+        tags = parse_tags(tag_part)
+        rest = rest.lstrip(" ")
+    if rest.startswith(":"):
+        prefix_part, _, rest = rest[1:].partition(" ")
+        prefix = Prefix.parse(prefix_part)
+        rest = rest.lstrip(" ")
+
+    trailing: str | None = None
+    if " :" in rest:
+        rest, _, trailing = rest.partition(" :")
+    elif rest.startswith(":"):
+        trailing = rest[1:]
+        rest = ""
+    parts = [p for p in rest.split(" ") if p]
+    if not parts:
+        msg = f"no command in IRC line: {raw!r}"
+        raise ValueError(msg)
+    command, *params = parts
+    if trailing is not None:
+        params.append(trailing)
+    return IrcMessage(command.upper(), tuple(params), tags, prefix, raw)
+
+
+def format_line(command: str, *params: str, tags: dict[str, str] | None = None) -> str:
+    """Build an IRC line (with CRLF). The last param is sent as trailing if needed.
+
+    Raises:
+        ValueError: if any part contains CR, LF or NUL (which would allow injection).
+    """
+    for part in (command, *params):
+        if "\r" in part or "\n" in part or "\0" in part:
+            msg = "IRC parameters must not contain CR or LF (or NUL)"
+            raise ValueError(msg)
+    pieces: list[str] = []
+    if tags:
+        pieces.append("@" + ";".join(f"{k}={escape_tag_value(v)}" for k, v in tags.items()))
+    pieces.append(command)
+    if params:
+        *middle, last = params
+        for p in middle:
+            if not p or " " in p or p.startswith(":"):
+                msg = f"invalid middle IRC parameter: {p!r}"
+                raise ValueError(msg)
+        pieces.extend(middle)
+        if not last or " " in last or last.startswith(":"):
+            last = ":" + last
+        pieces.append(last)
+    return " ".join(pieces) + "\r\n"