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:

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 stays flat whether a bot registers 50 handlers or 500.
3. The update name and waiter list are cheap. capitalize() is memoised and a pending ask() costs one integer check per update.

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.