add package: pyproject + src (DPYWebhooks, store protocol, cap + self-heal, fail-loud)

Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
2026-07-02 20:04:01 -04:00
parent 4518cbf30e
commit 74fd1bc4a5
4 changed files with 375 additions and 0 deletions
+19
View File
@@ -27,6 +27,21 @@ With a persistence store so webhooks survive a restart:
hooks = DPYWebhooks(bot, store=my_store)
```
Work with **all** of a channel's existing webhooks (read live, no store, no create) — for
discovery, load-spreading, or rotation:
```python
await hooks.list(channel) # every live webhook on the channel
await hooks.pick(channel, strategy="round_robin") # select one existing (None if none)
await hooks.send_any(channel, strategy="round_robin", content="hi") # send via a picked one
```
`pick` strategies are `"first"` (oldest by id), `"random"`, and `"round_robin"` (per-channel
in-process index that wraps on the live count and rebuilds if the count changed); an unknown
strategy raises `ValueError`. `send_any` sends through a picked existing webhook, **falling
back to `get_or_create`** when the channel has none, and reuses the same dead-webhook
self-heal. None of these three create or touch the store — they read live from the channel.
## What you inject
- **`client`** — your `discord.Client` / `commands.Bot`. Used to rebuild persisted webhooks
@@ -57,6 +72,10 @@ The module docstring (`help(dpy_webhooks)` / IDE hover) is the source of truth.
self-heal
- `clear(channel) -> None` — delete server-side + store record (idempotent)
- `count(channel) -> int` — webhooks currently on the channel
- `list(channel) -> list[discord.Webhook]` — all live webhooks on the channel (no create)
- `pick(channel, *, strategy="first") -> discord.Webhook | None` — select an existing one
- `send_any(channel, *, strategy="round_robin", **kwargs) -> discord.WebhookMessage` — send
via a picked existing webhook, falling back to `get_or_create`
**Self-heal.** If `send` hits a dead webhook (deleted server-side / invalid token), the lib
clears the record, recreates the webhook, and retries the send **once**; a second failure