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 exhaustive, method-by-method reference lives in docs/:

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

• Foundation: packaging, TLS, logging, test suite, CI
• Performance: indexed dispatch, bounded retries, pooled sessions
• Routers and FSM
• Middleware chain on routers
• Pagination helpers (async for over messages and members)
• Redis storage backend
• CLI (darkob new, darkob run)
• Type-complete public API and mypy in CI

🤝 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.