Metadata-Version: 2.5
Name: shoal
Version: 0.1.0a2
Summary: A fully typed Discord API library for Python, built to scale from one guild to millions.
Project-URL: Documentation, https://shoal.readthedocs.io/
Project-URL: Repository, https://github.com/relateful/shoal
Project-URL: Issues, https://github.com/relateful/shoal/issues
Author: Shoal contributors
License-Expression: MIT
License-File: LICENSE
Keywords: asyncio,bot,discord,discord-api,gateway,sharding
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiohttp>=3.13
Requires-Dist: msgspec>=0.20
Provides-Extra: all
Requires-Dist: cryptography>=50.0.2; extra == 'all'
Requires-Dist: davey>=0.1.7; extra == 'all'
Requires-Dist: prometheus-client>=0.21; extra == 'all'
Requires-Dist: redis>=5.2; extra == 'all'
Requires-Dist: zstandard>=0.23; (python_version < '3.14') and extra == 'all'
Provides-Extra: interactions
Requires-Dist: cryptography>=50.0.2; extra == 'interactions'
Provides-Extra: prometheus
Requires-Dist: prometheus-client>=0.21; extra == 'prometheus'
Provides-Extra: redis
Requires-Dist: redis>=5.2; extra == 'redis'
Provides-Extra: voice
Requires-Dist: cryptography>=50.0.2; extra == 'voice'
Requires-Dist: davey>=0.1.7; extra == 'voice'
Provides-Extra: zstd
Requires-Dist: zstandard>=0.23; (python_version < '3.14') and extra == 'zstd'
Description-Content-Type: text/markdown

# Shoal

A fully typed Discord API library for Python, built for bots that grow. It keeps the names you know
from discord.py (`commands.Bot`, `interaction.response.send_message`, `ui.View`, `tree.sync()`) and
fixes what makes discord.py painful once a bot gets big.

> **Status: pre-release.** Everything below is built and tested, but names can still change before
> 1.0. Install the pre-release with `pip install --pre shoal`. See the [roadmap](https://github.com/relateful/shoal/blob/main/docs/roadmap.md).

## Why not discord.py?

discord.py is a good library for a bot in a few servers. Shoal is for bots that keep growing, and it
is just as easy for the small ones.

### It starts fast, however many shards you run

discord.py identifies its shards one after another, about five seconds apart, and ignores the
`max_concurrency` Discord gives large bots. Shoal identifies `max_concurrency` shards at a time, as
Discord documents. At 512 shards with a concurrency of 16, that is under three minutes instead of
about 43.

### Restarts and deploys don't cost you the gateway

- **Sessions survive restarts.** discord.py keeps the session only in memory, so every restart
  identifies every shard again, and Discord sends every guild again. Shoal saves sessions (to files,
  or Redis) and resumes them on the next start.
- **The cache survives restarts.** Shoal restores the cache from a snapshot, marked stale until
  Discord confirms each entry, so the bot answers from a warm cache from the first second.
- **A failed resume still resumes.** discord.py falls back to the main gateway only when the resume
  URL answers with a 5xx, and then starts a new session. Shoal falls back on any failure (a timeout,
  a 5xx, an early close) and resumes there, as Discord recommends.
- **Change shard counts without downtime.** `bot.reshard(new_count)` connects the new shards beside
  the running ones and switches over once they are all ready. discord.py has no way to do this short
  of a restart.

### More than one process is built in

discord.py leaves IPC to you. Shoal includes it:

- **Gateway and workers.** One process holds the shards and streams events (`shoal.ipc`, over TCP
  or a Unix socket, or through a Redis stream). Workers run your commands and can restart as often
  as you deploy.
- **Clusters.** Several processes or hosts run one bot through Redis. They share one identify
  limiter, the REST rate limits, sessions, a directory of every shard, a command router (join a
  voice channel from any cluster) and the cache.
- **A REST proxy.** One process holds the token and the rate limits for all the others.

### It protects the bot from bans

- Discord bans an IP for 10,000 invalid requests in 10 minutes. discord.py does not count them.
  Shoal counts the 401, 403 and 429 responses Discord counts, and holds requests back before the
  limit.
- After a 401 (a revoked token), discord.py keeps sending requests that fail. Shoal stops at the
  first one.

### You can see what it is doing

- **Prometheus metrics** for gateway events and latency per shard, REST requests and rate limits by
  route, the cache, IPC, voice and event loop health. discord.py has none.
- **A blocked event loop is caught as it happens.** discord.py warns once the heartbeat has been
  stuck for 10 seconds, and again every 10 seconds after. Shoal's watchdog
  (`async with LoopMonitor():`) reports blocks over 0.25 seconds (configurable), names the line of
  your code that is blocking while it blocks, logs how long it lasted, and records it in metrics.
- **Late events are noticed.** Shoal measures how long each message and interaction took to arrive,
  and warns when they arrive more than five seconds late: the sign that events queue up before your
  code sees them.

### Typed, and true to Discord's docs

- Strict pyright and mypy over the library and its tests, with `Any` banned.
- Every type and endpoint links to its section of Discord's docs, and CI checks the links. Every
  HTTP endpoint Discord documents and every gateway event is covered, as the
  [coverage page](https://github.com/relateful/shoal/blob/main/docs/coverage.md), generated from Discord's docs, shows.
- A field that is absent and a field that is `null` stay different (`UNSET` and `None`), so an edit
  can tell "leave it" from "clear it". discord.py turns most of them into `None`.
- When Discord adds an enum value, Shoal decodes it as a real member of the enum, with its value
  kept. discord.py makes an `unknown_<value>` stand-in that is not a member.
- REST is public and standalone: `RestClient` covers every endpoint as `rest.<resource>.<verb>`, with
  bot or OAuth2 bearer tokens, for workers and dashboards. discord.py's `Client.http` is internal and
  undocumented.

### And what a bot needs today

- Slash, prefix and hybrid commands, cogs and extensions, views, modals and Components V2 layouts.
- Interactions over the gateway, or over HTTP with no gateway at all (signed, verified endpoint).
  discord.py only has the gateway.
- Voice: play and **listen**, end-to-end encrypted (DAVE), as Opus packets or decoded PCM per user
  (decoding needs libopus). discord.py can play, but receiving audio takes a third-party extension.
- Voice messages, polls, the application's own emojis synced from a folder, and member chunking as
  guilds arrive (`chunk_guilds_at_startup`).
- A cache with a policy per entity (size, TTL, whether to snapshot, which fields to keep), instead
  of one fixed cache.
- Loops (`tasks.loop`) and a scheduler for reminders and cron jobs that survive restarts with
  Redis, without a sleeping task per job.

> **Coming from discord.py?** `import shoal.compat as discord` gives you the old names, so a bot can move
> file by file. See the [compat example](https://github.com/relateful/shoal/tree/main/docs/examples/compat/) and the
> [migration guide](https://github.com/relateful/shoal/blob/main/docs/guide/migrating-from-discord-py.md).

## Install

Shoal needs Python 3.12 or newer. While it is in pre-release, pip needs `--pre`:

```bash
pip install --pre shoal                   # the core
pip install --pre "shoal[voice]"          # join voice channels, play and listen
pip install --pre "shoal[redis]"          # share limits, sessions, cache, events and shards across processes
pip install --pre "shoal[prometheus]"     # Prometheus metrics
pip install --pre "shoal[interactions]"   # receive interactions over HTTP, without a gateway
pip install --pre "shoal[zstd]"           # zstd gateway compression on Python 3.12 and 3.13
pip install --pre "shoal[all]"            # everything above
```

To work on Shoal itself, install it from a clone with `pip install -e ".[all]"`.

Each extra adds a dependency only some bots need, so the core install stays small.

## A taste

```python
import os

import shoal
from shoal import commands

bot = commands.Bot("!", intents=shoal.Intents.default().with_flags(message_content=True))


@bot.hybrid_command(description="Say hello")
async def hello(ctx: commands.Context, who: shoal.Member | None = None) -> None:
    await ctx.send(f"Hello {(who or ctx.author).mention}!")


bot.run(os.environ["DISCORD_TOKEN"])
```

`!hello` and `/hello` both work (sync the slash command once with `await bot.tree.sync()`).

## Examples

[29 runnable bots](https://github.com/relateful/shoal/tree/main/docs/examples/), each with its own README and each run against Discord, from
the [smallest bot](https://github.com/relateful/shoal/tree/main/docs/examples/hello/) to [role menus](https://github.com/relateful/shoal/tree/main/docs/examples/roles/buttons/),
[tickets](https://github.com/relateful/shoal/tree/main/docs/examples/tickets/), [music](https://github.com/relateful/shoal/tree/main/docs/examples/voice/music/) and
[a big bot](https://github.com/relateful/shoal/tree/main/docs/examples/bigbot/) with Prometheus, Grafana, warm restarts and resharding, plus
[clusters](https://github.com/relateful/shoal/tree/main/docs/examples/clusters/) and [workers](https://github.com/relateful/shoal/tree/main/docs/examples/workers/).

## Documentation

- Guides: [writing a bot](https://github.com/relateful/shoal/blob/main/docs/guide/bot.md), [commands and interactions](https://github.com/relateful/shoal/blob/main/docs/guide/interactions.md),
  [caching and restarts](https://github.com/relateful/shoal/blob/main/docs/guide/caching.md), [scaling, sharding and IPC](https://github.com/relateful/shoal/blob/main/docs/guide/scaling.md),
  [voice](https://github.com/relateful/shoal/blob/main/docs/guide/voice.md), [loops and scheduled jobs](https://github.com/relateful/shoal/blob/main/docs/guide/tasks.md),
  [dashboards and REST](https://github.com/relateful/shoal/blob/main/docs/guide/dashboards.md),
  [metrics and Grafana](https://github.com/relateful/shoal/blob/main/docs/guide/metrics.md), [diagnosing a slow bot](https://github.com/relateful/shoal/blob/main/docs/guide/diagnostics.md),
  [architecture](https://github.com/relateful/shoal/blob/main/docs/guide/architecture.md),
  [migrating from discord.py](https://github.com/relateful/shoal/blob/main/docs/guide/migrating-from-discord-py.md).
- The API reference is generated from the docstrings: `uv run --group docs mkdocs serve`.
- [Discord API coverage](https://github.com/relateful/shoal/blob/main/docs/coverage.md) lists every endpoint Discord documents and the Shoal method
  for it, generated from Discord's docs and checked weekly.

## Quality

- Every module with behaviour has a test module, and coverage is held above 95%.
- `tests/conventions.py` enforces the project's rules across the whole tree: docs links, ordering,
  constants defined once, slots, exports, test layout.
- CI runs on Python 3.12, 3.13 and 3.14, on Linux, Windows and macOS.

## Contributing

See [CONTRIBUTING.md](https://github.com/relateful/shoal/blob/main/CONTRIBUTING.md) for the rules, the layout and every check CI runs.

## License

[MIT](https://github.com/relateful/shoal/blob/main/LICENSE)
