darkob

Fast, stable async Python for the Rubika & Shad platforms.
Build bots and userbots that stay up, without the boilerplate.

darkob (دارکوب, woodpecker) is a fork of maxrubika by MEHRAB Farahmand, rebuilt around foundations you can trust. Same protocol, same power, far less guesswork when something goes wrong.

from darkob import Bot

bot = Bot(token="YOUR_BOT_TOKEN")

@bot.on_command("start")
async def start(bot, event):
    await event.reply("Welcome 👋")

bot.run()

✨ Why darkob

The upstream library is feature-complete, but its foundations were never hardened. Speed and new features are only worth having on a base that does not quietly fail, so darkob starts there.

🚀 Install

pip install darkob

Latest development version:

pip install git+https://github.com/ManiTheFerfri/darkob.git

📦 What's inside

• Two surfaces, one library. Bot talks to the official Bot API; Messenger drives a real user account, including channels, groups, voice chats and stickers. Shad is the same Messenger protocol against the Shad platform.
• Async first, sync friendly. Every method works with await or without it — darkob runs one background loop and hops onto it for you.
• Decorator handlers. on_message, on_command, on_callback, on_edit_message, and friends, with a composable filter system (&, |, ~).
• Routers. Split a bot into feature modules and include them in one line.
• Finite state machines. Multi-step conversations with pluggable storage that can survive a restart.
• Polling or webhook. bot.run() polls; bot.run(webhook_url=...) serves a webhook instead.

🔀 Routers

Handlers can live in their own modules and be registered from one place:

from darkob import Bot, Router

bot = Bot(token="YOUR_BOT_TOKEN")
admin = Router("admin")

@admin.command("ban")
async def ban(bot, event):
    await bot.ban_member(event.chat_id, event.author_id)
    await event.reply("Banned.")

bot.include_router(admin)
bot.run()

Routers nest, so a larger bot can keep one root router per feature area.

🧠 Conversations (FSM)

Track which step a user is on and remember what they told you:

from darkob import Bot, FSMContext, JsonFileStorage, StateFilter

bot = Bot(token="YOUR_BOT_TOKEN")
storage = JsonFileStorage("fsm.json")   # survives restarts

@bot.on_command("order")
async def order(bot, event):
    ctx = FSMContext(storage, key=event.chat_id)
    await ctx.set_state("address")
    await event.reply("What is your delivery address?")

@bot.on_new_message(StateFilter(storage, "address"))
async def address(bot, event):
    ctx = FSMContext(storage, key=event.chat_id)
    await ctx.update_data(address=event.text)
    await ctx.clear()
    await event.reply("Order received ✅")

Swap JsonFileStorage for MemoryStorage in tests, or implement the Storage interface to back it with Redis or SQL.

👤 Userbots

from darkob import Messenger

app = Messenger(auth="...", private_key="...")

Authentication, session strings, platforms (web, pwa, android, rubx, rubino, …) and the full method surface are covered in the documentation.

📚 Documentation

The full site lives at manitheferfri.github.io/darkob.

Built for AI-assisted development

Most darkob bots are written by an AI assistant, so the docs are designed to be read by a model:

• llms.txt — curated map in the llms.txt format
• llms-full.txt — the entire documentation in one file
• pi.json — every public method as structured 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

See the AI workflow and prompt pack.

Every public method also ships a full docstring:

from darkob import Bot
import inspect

for name in dir(Bot):
    if not name.startswith("_"):
        print(f"{name}: {inspect.getdoc(getattr(Bot, name))}\n")

🗂 Project layout

darkob/
├── bot/          # Bot API surface: endpoint mixins, filters, registry, plugins
├── client/       # Messenger API: chats, groups, channels, messages, settings
├── types/        # Event and update models
├── router.py     # Composable routers
├── fsm.py        # Conversation state + pluggable storage
├── hybrid.py     # Sync/async bridge
└── data.py       # Attribute/item-accessible response wrapper

🛠 Development

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

pytest                    # 121 tests, no network required
ruff check .              # lint
pytest --cov=darkob       # coverage

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

🗺 Roadmap

The full, evidence-based roadmap lives in docs/roadmap.md. It covers the ecosystem data, three strategic bets, four horizons, explicit non-goals, success metrics and risks.

Shipped so far:

• Foundation: packaging, TLS, logging, test suite, CI
• Performance: indexed dispatch, bounded retries, pooled sessions
• Routers, FSM with pluggable storage
• AI-first docs: llms.txt, api.json, generated API reference
• MCP server, typed public API, pagination, Redis storage, CLI

🤝 Contributing

Issues and pull requests are welcome. Please run pytest and ruff check . before opening a PR; CI runs both on every push.

📄 License & credits

MIT. darkob is derived from maxrubika, copyright MEHRAB Farahmand, and keeps the original MIT notice. See LICENSE.

Maintained by Mani Keikhosravi.

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