python-twitchchat 1.0.0__tar.gz

python_twitchchat-1.0.0/.gitignore

@@ -0,0 +1,68 @@
+test.py
+run.bat
+*.DS_Store
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# vim swp files
+.*.swp
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# uv / tooling
+.venv/
+.ruff_cache/
+.pytest_cache/

python_twitchchat-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,197 @@
+# 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/examples/watch_chat.py

@@ -0,0 +1,68 @@
+"""Anonymously watch one or more Twitch channels and print parsed events.
+
+Usage::
+
+    uv run examples/watch_chat.py [--seconds 60] channel [channel ...]
+
+Exits non-zero if no chat message was received within the time limit.
+Read-only: anonymous (justinfan) connections cannot send messages.
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+
+from twitchchat import ChatMessage, Join, Notice, RoomState, TwitchChat, UserNotice
+
+
+async def watch(channels: list[str], seconds: float) -> int:
+    """Print events for ``seconds`` and return the number of chat messages seen."""
+    count = 0
+    async with TwitchChat(channels) as chat:
+        print(f"connected as {chat.nick}, joining {', '.join(channels)}")
+
+        @chat.on(UserNotice)
+        def on_usernotice(event: UserNotice) -> None:
+            print(f"[#{event.channel}] *** {event.msg_id}: {event.system_msg} {event.params}")
+
+        try:
+            async with asyncio.timeout(seconds):
+                async for event in chat.events(ChatMessage, Join, Notice, RoomState):
+                    match event:
+                        case ChatMessage():
+                            count += 1
+                            ts = event.timestamp.strftime("%H:%M:%S") if event.timestamp else "?"
+                            badges = ",".join(event.badges)
+                            print(
+                                f"[#{event.channel} {ts}] <{event.display_name}"
+                                f"{' [' + badges + ']' if badges else ''}> {event.text!r}"
+                            )
+                        case Join(login=login) if login == chat.nick:
+                            print(f"joined #{event.channel}")
+                        case RoomState():
+                            print(f"roomstate #{event.channel}: {event.tags}")
+                        case Notice():
+                            print(f"notice: {event.text}")
+                        case _:
+                            pass
+        except TimeoutError:
+            pass
+    return count
+
+
+def main() -> None:
+    """Command line entry point."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("channels", nargs="+")
+    parser.add_argument("--seconds", type=float, default=60.0)
+    parser.add_argument("--debug", action="store_true")
+    args = parser.parse_args()
+    logging.basicConfig(level=logging.DEBUG if args.debug else logging.INFO)
+    count = asyncio.run(watch(args.channels, args.seconds))
+    print(f"received {count} chat messages in {args.seconds:.0f}s")
+    sys.exit(0 if count else 1)
+
+
+if __name__ == "__main__":
+    main()

python_twitchchat-1.0.0/pyproject.toml

@@ -0,0 +1,89 @@
+[project]
+name = "python-twitchchat"
+dynamic = ["version"]
+description = "Asyncio client for Twitch chat (IRC): typed events, callbacks and async iteration."
+readme = "README.md"
+authors = [{ name = "shughes-uk" }]
+requires-python = ">=3.15"
+dependencies = []
+keywords = ["twitch", "irc", "chat", "asyncio"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.15",
+    "Topic :: Communications :: Chat :: Internet Relay Chat",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/shughes-uk/python-twitchchat"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+fallback_version = "0.0.0"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "examples", "README.md", "pyproject.toml"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/twitchchat"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=1",
+    "ruff>=0.13",
+    "ty>=0.0.1",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-markers"]
+filterwarnings = ["error"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py315"
+src = ["src", "tests", "examples"]
+
+[tool.ruff.lint]
+select = [
+    "F", "E", "W", "I", "N", "UP", "B", "A", "C4", "SIM", "RUF", "PL", "PT", "RET",
+    "ASYNC", "S", "BLE", "FBT", "PIE", "PERF", "TRY", "EM", "G", "LOG", "SLF", "TC",
+    "PTH", "D2", "D3", "D4",
+]
+ignore = [
+    "D203", "D213", "D401", "D413",
+    "TRY003",  # long messages in exception constructors
+    "FBT001", "FBT002",  # boolean params are part of the public API (tls=, reconnect=)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "S105", "S106", "EM101", "PLR2004", "SLF001", "D", "FBT003"]
+"examples/**" = ["T201", "D"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ty.environment]
+python-version = "3.15"
+
+[tool.ty.src]
+include = ["src", "tests", "examples"]
+
+[tool.ty.rules]
+possibly-unresolved-reference = "error"