xtr-slack-notifier 5.0.0__tar.gz

xtr_slack_notifier-5.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 xterr
+Copyright (c) 2019-present Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xtr_slack_notifier-5.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: xtr-slack-notifier
+Version: 5.0.0
+Summary: Slack for xtr-notifier — chat messages posted, scheduled and updated in a channel, with Block Kit blocks, configured by DSN.
+Keywords: notifier,notification,slack,chat,block-kit,dsn,asyncio
+Author: Xterr
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: typing-extensions>=4.4
+Requires-Dist: xtr-notifier>=5.0,<6
+Requires-Dist: xtr-http-client-contracts>=5.0,<6
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# xtr-slack-notifier
+
+**Slack for xtr-notifier — chat messages posted, scheduled and updated in a channel, with Block Kit blocks, configured by DSN.**
+
+</div>
+
+---
+
+## Why?
+
+[xtr-notifier](../xtr-notifier) sends chat messages through whatever provider a DSN names. This
+library is the Slack provider: installed beside it, a `slack://` DSN is served with no wiring, a
+notification is rendered as Block Kit sections, and a message can be laid out with blocks,
+scheduled for later, or updated once posted.
+
+## Install
+
+```sh
+uv add xtr-slack-notifier
+```
+
+It needs an HTTP client implementing
+[xtr-http-client-contracts](../xtr-http-client-contracts) — usually
+[xtr-http-client](../xtr-http-client).
+
+## Quick start
+
+```python
+from xtr_http_client import HttpClient
+from xtr_notifier import Chatter, Transport
+from xtr_notifier.message import ChatMessage
+from xtr_notifier.transport import TransportFactoryDiscovery
+
+discovery = TransportFactoryDiscovery(
+    TransportFactoryDiscovery.CHATTER_GROUP, http_client=HttpClient.create()
+)
+transport = Transport(discovery=discovery).from_string("slack://xoxb-1234@default?channel=ops")
+
+sent = await Chatter(transport).send(ChatMessage("Deploy finished."))
+```
+
+## The DSN
+
+```
+slack://TOKEN@default?channel=CHANNEL
+```
+
+- `TOKEN` — a bot (`xoxb-`), user (`xoxp-`) or app (`xoxa-2`) token; a DSN without one is refused
+  with `User is not set.`, and a token of another kind with
+  `A valid Slack token needs to start with "xoxb-", "xoxp-" or "xoxa-2". ...` when the transport
+  is built — on first use, since the notifier builds its transports lazily.
+- `default` — `slack.com`; name another host (and port) for a test server.
+- `channel` — the channel a message naming none is posted to.
+- `ssl=false` — reach the host over plain HTTP.
+
+The transport's string form — what errors, events and `debug:config` show — is
+`slack://slack.com?channel=CHANNEL`: never the token. The token is sent as a bearer credential.
+
+## Options and blocks
+
+`SlackOptions` builds what a message carries beyond its text; `to_options()` renders it for the
+message:
+
+```python
+from xtr_notifier.message import ChatMessage
+from xtr_slack_notifier import SlackOptions
+from xtr_slack_notifier.block import SlackActionsBlock, SlackHeaderBlock, SlackSectionBlock
+
+options = (
+    SlackOptions()
+    .recipient("C0123456789")
+    .block(SlackHeaderBlock("Deploy 42"))
+    .block(SlackSectionBlock().text("*Finished* in 42s.").field("*Env*").field("production"))
+    .block(SlackActionsBlock().button("Open", "https://example.com/deploys/42", "primary"))
+)
+await chatter.send(ChatMessage("Deploy 42 finished.", options.to_options()))
+```
+
+The setters are `recipient`, `as_user`, `icon_emoji`, `icon_url`, `link_names`, `mrkdwn`, `parse`,
+`unfurl_links`, `unfurl_media`, `username`, `thread_ts` (reply in a thread), `post_at` (schedule
+through `chat.scheduleMessage`) and `block`. A message takes up to 50 blocks.
+
+The blocks, under `xtr_slack_notifier.block`: `SlackSectionBlock` (text, up to 10 fields, an
+accessory), `SlackHeaderBlock`, `SlackContextBlock` (up to 10 texts and images),
+`SlackActionsBlock` (up to 25 buttons), `SlackDividerBlock`, `SlackImageBlock` and
+`SlackPlainTextInputBlock`; the elements `SlackButtonBlockElement` and `SlackImageBlockElement`.
+Anything else implements `SlackBlockInterface`.
+
+A message made from a notification and carrying no options is rendered with
+`SlackOptions.from_notification(summary)`: the emoji as the icon, a section for the subject, one
+for the content, and the exception's traceback after a divider.
+
+Fields left empty — `None`, `""`, an empty list or mapping — are not sent; `False` and `0` are.
+
+## Updating a message
+
+The transport returns a `SlackSentMessage`, carrying the channel (`channel_id`) and the message's
+`ts` (`message_id`). `get_update_message(subject, options)` makes the message replacing it, sent
+through `chat.update`:
+
+```python
+sent = await chatter.send(ChatMessage("Deploying..."))
+await chatter.send(sent.get_update_message("Deployed."))
+```
+
+Its options are `UpdateMessageSlackOptions(channel_id, ts, options)`, which render with the kind
+`slack.update` — the transport accepts both kinds, and tells them apart by it after the message
+crossed a message bus.
+
+## Errors
+
+| Error | When |
+|---|---|
+| `IncompleteDsnError` | The DSN carries no token (`User is not set.`) |
+| `InvalidArgumentError` | The token does not start with `xoxb-`, `xoxp-` or `xoxa-2` |
+| `UnsupportedSchemeError` | The factory was handed a DSN that is not `slack://` |
+| `UnsupportedMessageTypeError` | The transport was handed a message that is not a `ChatMessage` |
+| `LogicError` | More than 50 blocks, 25 buttons, or 10 fields or context elements |
+| `LengthError` | A header over 150 characters, an input label or placeholder over 150, an id over 255 |
+| `TransportError` | `Unable to post the Slack message: "<error>" (<errors>).` when Slack answers `ok: false`, `Unable to post the Slack message: "<body>".` on another status, or `Could not reach the remote Slack server.` |
+
+Every one of them is xtr-notifier's; `TransportError` is what failover moves on from.
+
+## Use in an application
+
+Everything adding this package to an application takes — and, read backwards, what removing it
+undoes. It ships no bundle: the notifier's bundle finds its factory by the DSN scheme.
+
+- **Install** — `uv add xtr-slack-notifier`, beside `xtr-notifier` set up as its
+  [*Use in an application*](../xtr-notifier/README.md#use-in-an-application) says.
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Environment* step below: it writes
+  `SLACK_DSN` in `.env`. It prints the step adding the transport to
+  `<app>/config/notifier.py`, which a recipe cannot make for you.
+- **Configure** — add `slack=env("SLACK_DSN")` to `chatter_transports` in
+  `<app>/config/notifier.py`.
+- **Environment** — `SLACK_DSN`, `slack://TOKEN@default?channel=CHANNEL` with the app's token and
+  the channel; read when a message is first sent.
+- **Remove** — drop the `chatter_transports` entry and `SLACK_DSN`, then
+  `uv remove xtr-slack-notifier`.
+- **Check** — `debug:config notifier` lists `slack` under `chatter_transports`.
+
+Everything else — the bundle, the channel policy, queuing through the message bus — is
+xtr-notifier's.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+uv run basedpyright
+uv run ty check
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_slack_notifier-5.0.0/README.md

@@ -0,0 +1,159 @@
+<div align="center">
+
+# xtr-slack-notifier
+
+**Slack for xtr-notifier — chat messages posted, scheduled and updated in a channel, with Block Kit blocks, configured by DSN.**
+
+</div>
+
+---
+
+## Why?
+
+[xtr-notifier](../xtr-notifier) sends chat messages through whatever provider a DSN names. This
+library is the Slack provider: installed beside it, a `slack://` DSN is served with no wiring, a
+notification is rendered as Block Kit sections, and a message can be laid out with blocks,
+scheduled for later, or updated once posted.
+
+## Install
+
+```sh
+uv add xtr-slack-notifier
+```
+
+It needs an HTTP client implementing
+[xtr-http-client-contracts](../xtr-http-client-contracts) — usually
+[xtr-http-client](../xtr-http-client).
+
+## Quick start
+
+```python
+from xtr_http_client import HttpClient
+from xtr_notifier import Chatter, Transport
+from xtr_notifier.message import ChatMessage
+from xtr_notifier.transport import TransportFactoryDiscovery
+
+discovery = TransportFactoryDiscovery(
+    TransportFactoryDiscovery.CHATTER_GROUP, http_client=HttpClient.create()
+)
+transport = Transport(discovery=discovery).from_string("slack://xoxb-1234@default?channel=ops")
+
+sent = await Chatter(transport).send(ChatMessage("Deploy finished."))
+```
+
+## The DSN
+
+```
+slack://TOKEN@default?channel=CHANNEL
+```
+
+- `TOKEN` — a bot (`xoxb-`), user (`xoxp-`) or app (`xoxa-2`) token; a DSN without one is refused
+  with `User is not set.`, and a token of another kind with
+  `A valid Slack token needs to start with "xoxb-", "xoxp-" or "xoxa-2". ...` when the transport
+  is built — on first use, since the notifier builds its transports lazily.
+- `default` — `slack.com`; name another host (and port) for a test server.
+- `channel` — the channel a message naming none is posted to.
+- `ssl=false` — reach the host over plain HTTP.
+
+The transport's string form — what errors, events and `debug:config` show — is
+`slack://slack.com?channel=CHANNEL`: never the token. The token is sent as a bearer credential.
+
+## Options and blocks
+
+`SlackOptions` builds what a message carries beyond its text; `to_options()` renders it for the
+message:
+
+```python
+from xtr_notifier.message import ChatMessage
+from xtr_slack_notifier import SlackOptions
+from xtr_slack_notifier.block import SlackActionsBlock, SlackHeaderBlock, SlackSectionBlock
+
+options = (
+    SlackOptions()
+    .recipient("C0123456789")
+    .block(SlackHeaderBlock("Deploy 42"))
+    .block(SlackSectionBlock().text("*Finished* in 42s.").field("*Env*").field("production"))
+    .block(SlackActionsBlock().button("Open", "https://example.com/deploys/42", "primary"))
+)
+await chatter.send(ChatMessage("Deploy 42 finished.", options.to_options()))
+```
+
+The setters are `recipient`, `as_user`, `icon_emoji`, `icon_url`, `link_names`, `mrkdwn`, `parse`,
+`unfurl_links`, `unfurl_media`, `username`, `thread_ts` (reply in a thread), `post_at` (schedule
+through `chat.scheduleMessage`) and `block`. A message takes up to 50 blocks.
+
+The blocks, under `xtr_slack_notifier.block`: `SlackSectionBlock` (text, up to 10 fields, an
+accessory), `SlackHeaderBlock`, `SlackContextBlock` (up to 10 texts and images),
+`SlackActionsBlock` (up to 25 buttons), `SlackDividerBlock`, `SlackImageBlock` and
+`SlackPlainTextInputBlock`; the elements `SlackButtonBlockElement` and `SlackImageBlockElement`.
+Anything else implements `SlackBlockInterface`.
+
+A message made from a notification and carrying no options is rendered with
+`SlackOptions.from_notification(summary)`: the emoji as the icon, a section for the subject, one
+for the content, and the exception's traceback after a divider.
+
+Fields left empty — `None`, `""`, an empty list or mapping — are not sent; `False` and `0` are.
+
+## Updating a message
+
+The transport returns a `SlackSentMessage`, carrying the channel (`channel_id`) and the message's
+`ts` (`message_id`). `get_update_message(subject, options)` makes the message replacing it, sent
+through `chat.update`:
+
+```python
+sent = await chatter.send(ChatMessage("Deploying..."))
+await chatter.send(sent.get_update_message("Deployed."))
+```
+
+Its options are `UpdateMessageSlackOptions(channel_id, ts, options)`, which render with the kind
+`slack.update` — the transport accepts both kinds, and tells them apart by it after the message
+crossed a message bus.
+
+## Errors
+
+| Error | When |
+|---|---|
+| `IncompleteDsnError` | The DSN carries no token (`User is not set.`) |
+| `InvalidArgumentError` | The token does not start with `xoxb-`, `xoxp-` or `xoxa-2` |
+| `UnsupportedSchemeError` | The factory was handed a DSN that is not `slack://` |
+| `UnsupportedMessageTypeError` | The transport was handed a message that is not a `ChatMessage` |
+| `LogicError` | More than 50 blocks, 25 buttons, or 10 fields or context elements |
+| `LengthError` | A header over 150 characters, an input label or placeholder over 150, an id over 255 |
+| `TransportError` | `Unable to post the Slack message: "<error>" (<errors>).` when Slack answers `ok: false`, `Unable to post the Slack message: "<body>".` on another status, or `Could not reach the remote Slack server.` |
+
+Every one of them is xtr-notifier's; `TransportError` is what failover moves on from.
+
+## Use in an application
+
+Everything adding this package to an application takes — and, read backwards, what removing it
+undoes. It ships no bundle: the notifier's bundle finds its factory by the DSN scheme.
+
+- **Install** — `uv add xtr-slack-notifier`, beside `xtr-notifier` set up as its
+  [*Use in an application*](../xtr-notifier/README.md#use-in-an-application) says.
+- **Recipe** — `uv run xtr-recipes recipes:sync` does the *Environment* step below: it writes
+  `SLACK_DSN` in `.env`. It prints the step adding the transport to
+  `<app>/config/notifier.py`, which a recipe cannot make for you.
+- **Configure** — add `slack=env("SLACK_DSN")` to `chatter_transports` in
+  `<app>/config/notifier.py`.
+- **Environment** — `SLACK_DSN`, `slack://TOKEN@default?channel=CHANNEL` with the app's token and
+  the channel; read when a message is first sent.
+- **Remove** — drop the `chatter_transports` entry and `SLACK_DSN`, then
+  `uv remove xtr-slack-notifier`.
+- **Check** — `debug:config notifier` lists `slack` under `chatter_transports`.
+
+Everything else — the bundle, the channel policy, queuing through the message bus — is
+xtr-notifier's.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check
+uv run ruff format --check
+uv run basedpyright
+uv run ty check
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

xtr_slack_notifier-5.0.0/pyproject.toml

@@ -0,0 +1,163 @@
+[project]
+name = "xtr-slack-notifier"
+version = "5.0.0"
+description = "Slack for xtr-notifier — chat messages posted, scheduled and updated in a channel, with Block Kit blocks, configured by DSN."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "notifier",
+    "notification",
+    "slack",
+    "chat",
+    "block-kit",
+    "dsn",
+    "asyncio",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typing-extensions>=4.4",
+    "xtr-notifier>=5.0,<6",
+    "xtr-http-client-contracts>=5.0,<6",
+]
+
+[[project.authors]]
+name = "Xterr"
+email = "me@xterr.dev"
+
+[project.entry-points."xtr_notifier.chatter_transport_factories"]
+slack = "xtr_slack_notifier:SlackTransportFactory"
+
+[project.entry-points.xtr_recipes]
+slack = "xtr_slack_notifier.recipe"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "anyio>=4.0",
+    "ty>=0.0.83",
+    "xtr-http-client>=5.0,<6",
+    "xtr-recipes>=5.0,<6",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.11"
+pythonPlatform = "All"
+include = [
+    "src",
+    "tests",
+]
+exclude = [
+    "**/__pycache__",
+    "**/.venv",
+    "**/build",
+    "**/dist",
+    ".tmp",
+]
+reportUnusedCallResult = "warning"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedVariable = "error"
+reportMissingParameterType = "error"
+reportPrivateUsage = "error"
+reportImplicitStringConcatenation = "none"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+extraPaths = ["."]
+reportPrivateUsage = "none"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "ISC001",
+    "D203",
+    "D213",
+    "CPY001",
+    "FBT001",
+    "FBT002",
+    "TD002",
+    "TD003",
+    "FIX002",
+    "TRY003",
+    "EM101",
+    "EM102",
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",
+    "ARG",
+    "PLR2004",
+    "SLF001",
+    "D",
+    "FBT003",
+    "S105",
+    "S106",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-config",
+    "--strict-markers",
+]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    '^\s*\.\.\.$',
+]

xtr_slack_notifier-5.0.0/pyproject.toml.orig

@@ -0,0 +1,165 @@
+[project]
+name = "xtr-slack-notifier"
+version = "5.0.0"
+description = "Slack for xtr-notifier — chat messages posted, scheduled and updated in a channel, with Block Kit blocks, configured by DSN."
+readme = "README.md"
+authors = [
+    { name = "Xterr", email = "me@xterr.dev" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["notifier", "notification", "slack", "chat", "block-kit", "dsn", "asyncio"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "typing-extensions>=4.4",
+    "xtr-notifier>=5.0,<6",
+    # The Web API is reached through the application's client.
+    "xtr-http-client-contracts>=5.0,<6",
+]
+
+# Found by the chatter when a DSN's scheme is slack, with no wiring.
+[project.entry-points."xtr_notifier.chatter_transport_factories"]
+slack = "xtr_slack_notifier:SlackTransportFactory"
+
+# Advertises the recipe — what *Use in an application* takes — for recipes:sync.
+[project.entry-points."xtr_recipes"]
+slack = "xtr_slack_notifier.recipe"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "anyio>=4.0",
+    "ty>=0.0.83",
+    # MockHttpClient stands in for the Slack Web API in transport tests.
+    "xtr-http-client>=5.0,<6",
+    # Read the shipped recipe with the parser recipes:sync uses.
+    "xtr-recipes>=5.0,<6",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+# ─────────────────────────────────────────────────────────────────
+# basedpyright — typeCheckingMode = "all" sets every report flag to error
+# ─────────────────────────────────────────────────────────────────
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.11"
+pythonPlatform = "All"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/.venv", "**/build", "**/dist", ".tmp"]
+
+reportUnusedCallResult = "warning"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedVariable = "error"
+reportMissingParameterType = "error"
+reportPrivateUsage = "error"
+
+# An error message long enough to be useful has to wrap, and a 100-column
+# limit puts the break inside the string.
+reportImplicitStringConcatenation = "none"
+
+# Tests check state a class keeps to itself, for the same reason ruff's
+# SLF001 is off for tests.
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+extraPaths = ["."]
+reportPrivateUsage = "none"
+
+# ─────────────────────────────────────────────────────────────────
+# ruff — select = ["ALL"], minimal justified ignores
+# ─────────────────────────────────────────────────────────────────
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    # Formatter conflicts (ruff documents these)
+    "COM812",
+    "ISC001",
+    # Mutually-exclusive docstring conventions; keep the modern one
+    "D203",
+    "D213",
+    # Project-specific noise
+    "CPY001",
+    "FBT001",
+    "FBT002",
+    "TD002",
+    "TD003",
+    "FIX002",
+    # Errors compose their own messages from typed fields; the string at a
+    # raise site is a `reason` data field.
+    "TRY003",
+    "EM101",
+    "EM102",
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",    # assert is the point of pytest
+    "ARG",     # fixtures look unused
+    "PLR2004", # magic numbers in test data
+    "SLF001",  # tests reach into privates
+    "D",       # test names are the docs
+    "FBT003",  # a flag passed to a builder is a value
+    "S105",    # fake secret literals are test data
+    "S106",    # fake secret literals are test data
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+# ─────────────────────────────────────────────────────────────────
+# ty — a second opinion on the source
+# ─────────────────────────────────────────────────────────────────
+[tool.ty.src]
+include = ["src", "tests"]
+
+# ─────────────────────────────────────────────────────────────────
+# pytest
+# ─────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+# CI runs the tests with --cov; a change taking coverage below this fails there.
+fail_under = 95
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    # A Protocol body states a contract; there is nothing there to run.
+    "^\\s*\\.\\.\\.$",
+]