Mothership - Python Edition

A minimalist framework for building Telegram bots rapidly with clean abstractions and zero boilerplate.

Features

• Simple Bot Definition: Define bots with minimal code
• Storage Abstraction: Automatic fallback between Firestore and in-memory storage
• Flexible Deployment: Support for local (polling), webhooks, and serverless platforms
• Type-Safe: Full type hints support
• Structured Logging: Built-in colored, leveled logging
• Firebase Integration: Optional Firestore persistence

Installation

# Using uv (recommended)
uv pip install mothership-bot

# Or using pip
pip install mothership-bot

Quick Start

1. Create a bot file (bot.py)

from mothership import BotDefinition, Update, ContextTypes, create_logger

logger = create_logger('my-bot')

async def handle_start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text('Hello! I am your bot.')

bot: BotDefinition = {
    'config': {
        'name': 'my-bot',
        'description': 'My awesome bot'
    },
    'commands': [
        {
            'command': 'start',
            'description': 'Start the bot',
            'handler': handle_start
        }
    ]
}

2. Set your bot token

export BOT_TOKEN=your_token_here

3. Run your bot

# Using the CLI
mothership run bot.py

# Or using Python directly
python -c "from mothership.cli import run_bot; import asyncio; asyncio.run(run_bot('bot.py'))"

CLI Usage

The mothership CLI provides an easy way to run and manage your bots:

# Run a bot from a file
mothership run bot.py

# Run a bot from bots directory (looks for bots/ping_bot/__init__.py)
mothership run ping_bot

# Run on a custom port
mothership run ping_bot --port 8080

# List available bots in bots/ directory
mothership list

# Get help
mothership --help

Requirements

• Python >= 3.8
• Telegram Bot Token (from @BotFather)

Environment Variables

• BOT_TOKEN - Required: Telegram bot token
• FIREBASE_PROJECT_ID - Optional: Enable persistent storage
• LOG_LEVEL - Optional: Logging level (debug|info|warn|error)

Documentation

See the main Mothership repository for full documentation.