darkob

Fast, stable async Python for the Rubika & Shad platforms.
Bots and userbots that stay up — with an API verified against the real server.

Docs · AI context · PyPI · Roadmap

pip install darkob

from darkob import Bot, Keyboard

bot = Bot(token="YOUR_BOT_TOKEN")

@bot.on_command("start")
async def start(bot, event):
    await event.reply(
        "Welcome 👋",
        inline_keypad=Keyboard().row("Docs", "Support"),
    )

bot.run()

Why darkob

A fork of maxrubika, rebuilt so failures are visible, the fast paths are actually fast, and the API surface matches the server.

What's inside

Reliability

Six primitives that most bot libraries leave to the user:

from darkob import Bot, RateLimiter, Retry, SendQueue

bot = Bot(
    token="...",
    retry=Retry(attempts=4, backoff=0.5),
    rate_limiter=RateLimiter(rate=20, per_chat_rate=3),
)

outbox = SendQueue(bot, path="outbox.json")
outbox.start()

Performance

Measured with benchmarks/benchmark_suite.py against maxrubika 1.17.0 on the same machine, each case in a fresh process so neither library inherits the other's warm state:

Under realistic load (benchmarks/scenarios.py, same machine): 17,500 updates/s routing 1,000 updates against 100 registered handlers, and a 4 MiB download resumed from 50% completes in 1.9 ms of library overhead.

Three things carry the difference:

1. Lookups are indexed. Every payload builds a key index on first access, so event.text — which searches text then caption — no longer walks the structure on every read.
2. Dispatch is an index, not a scan. Handlers are grouped by update name once, so routing cost scales with the handlers that match, not with the handlers that exist.
3. The update name and waiter list are cheap. capitalize() is memoised and a pending ask() costs one integer check per update.

Read this before quoting those numbers

The benchmark used to be wrong, and in our favour, which is the worst kind of wrong. Its dispatch cases registered handlers as {handler: MessageUpdates() for _ in range(count)} — a dict keyed by the function object, so 500 identical entries collapsed into one key. Both "50 handlers" and "500 handlers" were measuring a single handler, which is why the two rows previously reported nearly identical times.

With distinct handlers the gap widened rather than narrowed: 1.5× became 2.2×, because an index only helps once there is something to index. README numbers before 0.18.0 should be discarded.

Two more caveats, stated plainly:

• Nothing here measures the network. In a running bot, network latency dominates every row. These numbers describe CPU work per update.
• The dispatch rows measure the client dispatch path — the one both libraries expose identically, which is what makes the comparison fair. darkob.Bot routes through its own handler registry, which is a linear scan rather than an index; it is a different code path and is not what these rows time.
• The micro-benchmarks isolate one code path each. The 5.7× nested lookup is real but applies to a payload shape those properties actually walk; the end-to-end gain is smaller. The dispatch rows are the ones you will notice, because routing runs on every single update.

CI enforces this: benchmarks/check_regression.py fails the build when a head-to-head factor drops by more than 25%, or a calibration-normalised scenario ratio rises by more than 75% (wider, because the committed baseline was recorded on a different platform). See benchmarks/README.md for the methodology, the recording hardware and the exact commands.

Verified against the real API

The Bot API documents 19 endpoints. All are implemented, and 18 were exercised against a live server — including the full file round-trip (requestSendFile → uploadFile → getFile → sendFile → download) and byte-range resume.

That testing caught three things static reading could not:

1. editInlineKeypad — the docs' own cURL — answers INVALID_INPUT: Invalid Method. The working endpoint is editMessageKeypad.
2. A bare Payment button is rejected; Button.payment() now demands its fields instead of failing at send time.
3. Bot.download_file was opening its own HTTP session, paying a fresh TLS handshake per file.

The remaining two gaps are documented rather than guessed: getChatMember needs a group chat to verify, and setCommands has no read-back, so testing it would destroy your command list.

Documentation

Full site: manitheferfri.github.io/darkob

Built for AI-assisted development

Most darkob bots are written by an assistant, so the docs are built to be read by a model.

https://manitheferfri.github.io/darkob/llms-full.txt

One file, one fetch: hard rules, every guide, and the complete API with full docstrings for all 688 methods.

• llms.txt — curated map
• api.json — every method as JSON
• Every page is also served as raw Markdown: append .md to any URL
• The API reference is generated from the installed package, so it cannot drift

Development

git clone https://github.com/ManiTheFerfri/darkob.git
cd darkob
pip install -e ".[dev]"

pytest --cov=darkob     # 463 tests, no network required
ruff check .            # lint
mypy darkob/router.py darkob/retry.py darkob/builders.py \
     darkob/keyboards.py darkob/formatting.py darkob/testing.py

The suite never opens a socket: HTTP goes through fake transports, and a subprocess test asserts that importing darkob cannot reach the network.

Two extra tools live in scripts/:

• benchmark.py — micro-benchmarks for the hot paths, no network.
• conformance.py — exercises every Bot API method against a real token, cleans up after itself, and exits non-zero on failure.

Roadmap

See docs/roadmap.md — milestones 1–3 and P0–P2 are closed. It records what is proven, what is impossible, and why.

License

MIT. Derived from maxrubika, copyright MEHRAB Farahmand; the original MIT notice is preserved in LICENSE.

Maintained by Mani Keikhosravi.

Not affiliated with Rubika or Shad. Use responsibly and in line with the platforms' terms of service.