# dpy_commons

Shared discord.py utilities — the discord-side sibling of `commons`. A module of functions
grouped by concern: message/embed parsing, embed sanitizing + limit-fitting, link extraction,
text chunking, timestamp helpers, interactive await-prompts, and a limit-safe send.

## Install

```
dpy_commons @ git+ssh://git@git.rethinkstudios.io/rethink-public/dpy_commons.git@v0.1.0
```

## Usage

```python
import dpy_commons as dc

# structured parse of a rich message (async — it reads attachments from the CDN)
payload = await dc.parse_message(message)
payload["mentions"]["users"]        # [123, ...]
payload["poll"]                     # {"question": ..., "options": [...]} or None

# sanitize an embed to be safe-to-send (links wrapped, color normalized, within limits)
safe = dc.sanitize_embed(raw_embed)

# send that never trips a Discord limit: chunks content, fits + splits embeds
await dc.safe_send(channel, content=long_text, embeds=many_embeds)

# split a 5000-char blob into <=2000 pieces on clean boundaries
for piece in dc.chunk_text(blob):
    await channel.send(piece)

# a live, timezone-local timestamp rendered by the Discord client
dc.discord_timestamp(dt, "R")       # "<t:1751500000:R>"
```

### Interactive await-prompts

Throw a prompt, `await` it, get the answer back right there — no listener, no view subclass,
no state plumbing:

```python
if await dc.confirm(ctx, "Delete 500 messages?"):
    await purge()

action = await dc.choose(ctx, "Pick:", {
    "✅": "approve",
    "❌": "deny",
    "<:escalate:123456789>": "escalate",
})
# action -> "approve" | "deny" | "escalate" | None (timeout)
```

`confirm` returns `True`/`False`/`None`; `choose` returns the mapped **value** (never the raw
interaction). Both scope to a user (a stranger's click gets an ephemeral "not for you" and the
prompt stays live), disable their components after resolve/timeout, accept custom emojis
anywhere an emoji goes, and take `cleanup=True` to delete the prompt afterward. `choose`
auto-switches to a select dropdown for more than 5 options or long labels.

## What's inside

| Concern | Functions |
|---|---|
| Parsing | `parse_message` (async), `extract_message_links`, `sanitize_mentions` |
| Embeds | `fit_embed`, `sanitize_embed`, `split_embeds` |
| Text | `chunk_text`, `format_table`, `discord_timestamp`, `humanize_delta` |
| Prompts | `confirm`, `choose` |
| Send | `safe_send` |

All Discord hard limits live as module constants (`MSG_LIMIT`, `EMBED_TOTAL`, …) — the single
source of truth; nothing hardcodes a limit.

## Contract

Config-free (functions take the discord objects they act on, never a global). Fail-loud:
`format_table` raises `ValueError` on ragged rows, `discord_timestamp` on a bad style,
`choose` on empty options; `safe_send` and the prompts propagate Discord perms/HTTP errors
(a prompt **timeout** is a normal `None`, not an error). The one tolerated swallow is a single
bad attachment in `parse_message` (warn + skip) — pass `strict=True` to raise instead.

## Notes / deviations

- **`parse_message` is `async`.** The spec wrote it sync, but attachments are read from the
  CDN (network I/O), which cannot be synchronous. Await it.
- Targets **`discord.py>=2.2`** (not `discord.py-self`).

## Versioning

Tagged `vX.Y.Z`; pin a tag in your install line.