# darkob

> darkob is a fast, stable async Python library for the Rubika and Shad
> messaging platforms. It provides a Bot API client (`Bot`), a userbot
> client (`Messenger`), and a Shad facade, plus routers, conversational
> state, keyboards for every documented button type, and the reliability
> primitives most bots hand-roll: retry policy, rate limiting, a circuit
> breaker, an offline send queue and resumable downloads.

Python 3.9–3.14 · MIT. Latest version: https://pypi.org/project/darkob/

## Hard rules for generated code

- Install with `pip install darkob`; import from `darkob`.
- Handlers are `async def handler(bot, event)` and are registered with
  decorators on a `Bot` instance.
- The second argument is `event`, never `message`. Use `event.chat_id`,
  `event.text`, `event.message_id`, `event.reply(...)`.
- Filters live in `darkob.bot.filters` and are **instantiated**:
  `IsGroup()`, not `IsGroup`. They compose with `&`, `|`, `~`.
- There is no `Dispatcher`, no `message_handler`, and no aiogram, Pyrogram
  or Telegram types. A `Bot` registers and dispatches.
- Do not invent methods. Anything not listed in the API section below does
  not exist on this version.
- Every public method exists in both sync and async form.

## Start here

- [Quickstart](https://manitheferfri.github.io/darkob/get-started/quickstart.md): install, first bot, polling vs webhook
- [Installation](https://manitheferfri.github.io/darkob/get-started/installation.md): requirements, extras, dev setup
- [Migrating from maxrubika](https://manitheferfri.github.io/darkob/get-started/migrating-from-maxrubika.md): package rename, behavioural changes, session migration caveat
- [Your first bot in 10 minutes](https://manitheferfri.github.io/darkob/tutorials/first-bot.md): a guided build from an empty file
- [Testing without a token](https://manitheferfri.github.io/darkob/tutorials/testing-without-a-token.md): `FakeBot`, `make_message`, offline tests

## How-to guides

- [Resumable downloads](https://manitheferfri.github.io/darkob/how-to/resumable-downloads.md): streaming to disk and resuming by byte range
- [Rate-limit safely](https://manitheferfri.github.io/darkob/how-to/rate-limit-safely.md): `RateLimiter` and the adaptive AIMD limiter
- [Observe in production](https://manitheferfri.github.io/darkob/how-to/observe-in-production.md): `darkob.metrics`, Prometheus exposition
- [Health checks](https://manitheferfri.github.io/darkob/how-to/health-checks.md): liveness and readiness endpoints
- [Write a plugin](https://manitheferfri.github.io/darkob/how-to/write-a-plugin.md): `Plugin`, the four hooks, `PluginTester`

## Explanation

- [Architecture](https://manitheferfri.github.io/darkob/explanation/architecture.md): the request pipeline and dispatch
- [Bot vs Messenger vs Shad](https://manitheferfri.github.io/darkob/explanation/bot-vs-messenger-vs-shad.md): which client, and why
- [Concurrency](https://manitheferfri.github.io/darkob/explanation/concurrency.md): one loop per client, `TaskGroup`, free-threaded caveats
- [Reliability](https://manitheferfri.github.io/darkob/explanation/reliability.md): retries, breakers, flood ceiling, outbox

## Guides

- [Handlers](https://manitheferfri.github.io/darkob/guides/handlers.md): every decorator, middleware, ordering, `on_error`
- [Filters](https://manitheferfri.github.io/darkob/guides/filters.md): all 42 constraints, composition, custom filters
- [Routers](https://manitheferfri.github.io/darkob/guides/routers.md): feature modules, nesting, router-scoped middleware
- [Conversations (FSM)](https://manitheferfri.github.io/darkob/guides/fsm.md): 4 storage backends, `FSMContext`, `StateFilter`
- [Keyboards](https://manitheferfri.github.io/darkob/guides/keyboards.md): all 19 button types and the enums
- [Composing messages](https://manitheferfri.github.io/darkob/guides/composing-messages.md): `MessageBuilder` plus formatting helpers
- [Errors](https://manitheferfri.github.io/darkob/guides/errors.md): exception hierarchy, `Retry`, circuit breaker, rate limiting, `SendQueue`
- [Sync and async](https://manitheferfri.github.io/darkob/guides/sync-and-async.md): both styles and when each applies
- [Testing bots](https://manitheferfri.github.io/darkob/guides/testing.md): `darkob.testing` (`FakeBot`, `FakeEvent`, `make_message`)
- [Project layout](https://manitheferfri.github.io/darkob/guides/project-layout.md): module map and design rules

## Reliability primitives

- `Retry(attempts, backoff, jitter, max_delay)`: honoured by both surfaces; presets `Retry.none()`, `.aggressive()`, `.patient()`.
- `RateLimiter(rate, burst, per_chat_rate)`: token buckets, global and per chat, applied to every attempt including retries.
- `AdaptiveRateLimiter(...)`: same, plus AIMD control — halves on a `429`/`TOO_REQUESTS`, climbs back additively, honours `Retry-After`. The client reports throttles automatically.
- `CircuitBreaker(threshold, reset_timeout)`: per endpoint; opens after consecutive failures, half-opens to probe.
- `SendQueue(bot, path=)`: `put()` sends or queues; transient failures only; `flush()`, `start()`, `stop()`.
- `ProtocolTracker(path=)`: snapshots the discovered endpoints, socket URL and app version, and reports drift.
- `Bot.download_file(..., resume=True)`: streams to disk and resumes by byte range.

## Observability and plugins

- `darkob.metrics`: `enable_metrics()`, then `metrics.snapshot()` or `metrics.render_prometheus()`. Off by default; the instrumentation is a single boolean check when disabled.
- `darkob.health`: `HealthRegistry()` with `tcp_check()` and `queue_backlog_check()`; `asgi_app()` for FastAPI/Starlette, `aiohttp_handler()` for aiohttp.
- `darkob.plugin`: `Plugin` + `PluginMeta`, hooks `on_update`, `before_request`, `after_response`, `on_error`; `PluginTester` for tests.
- `darkob.utils.concurrency`: `TaskGroup`, `timeout_after`, `LazyLock` — version-independent structured concurrency.

## API reference

- [Bot](https://manitheferfri.github.io/darkob/api/bot.md): every method, generated from the package
- [Messenger](https://manitheferfri.github.io/darkob/api/messenger.md): every method, generated from the package
- [Shad](https://manitheferfri.github.io/darkob/api/shad.md): mirrors Messenger against Shad hosts

## Machine-readable

- [api.json](https://manitheferfri.github.io/darkob/api.json): every method as JSON (name, signature, module, full docstring)
- [llms-full.txt](https://manitheferfri.github.io/darkob/llms-full.txt): the entire corpus in one file, in teaching order
- Raw Markdown for every page: append `.md` to any URL

## Project

- [Roadmap](https://manitheferfri.github.io/darkob/roadmap.md): what is proven, what is impossible, and why
- [Source](https://github.com/ManiTheFerfri/darkob): repository and issues
- [Persian quickstart](https://manitheferfri.github.io/darkob/fa/quickstart.md): شروع سریع