UB-Core

A fully modular and pluggable Telegram bot base. Comes with a lot of built in goodies and fixes.

Example Project:

Plain-UB is based on and made using ub-core. it expands on core's initial features and transforms them into usable modules like these and many more.

Table of Contents

• Installation

• Standalone Usage

• Core:

  • Client
  • Database
  • Message
  • Conversation
  • Handlers
  • UnifiedMessageHandler
  • Dispatcher
  • Logging

• Default Plugins

• Updater

• Utils:

  • Download
  • AioHttp utils
  • Media Helper
  • Shell

Documentation

Installation

• Single Client:

    pip install git+https://github.com/thedragonsinn/ub-core

• Dual Client:

    pip install git+https://github.com/thedragonsinn/ub-core@dual_mode

Difference between Single and Dual clients: here

Client

A custom Client with a few Extra methods and Decorators.

• send_message: automatically sends text as document when it goes above 4096 chars (TG limit).

• channel_logger: Logs texts/message to your log channel, StdOut/StdError and log file. The type argument can be used to log at different logging levels like info, error warning etc.

• @add_cmd: Uses a custom command manager instead of pyrogram's. Useful when you wanna add sudo or multi user mode or run dual_mode. This decorator will negate the need to add handlers for each type of user/clients.

• @on_message: adds back edited support as a keyword argument "filters_edited" and uses a custom dispatcher.

• @on_edited_message: use a custom dispatcher.

    # import the instance that was created on core initialisation.
    # use this instance only.
    from ub_core import bot

Database

Core relies on a MongoDB database and uses a Custom Collection class.

Optional for main branch, Required for dual_mode

    from ub_core import CustomDB
    
    # Create a CustomDB instance instead of DB_CLIENT["collection_name"]
    coll = CustomDB("test_collection")
    
    # Now you can use the extra methods as well as the original mongo db methods available in the original collection class.

Conversation

A custom Conversation module to programitcally interact with incoming and outgoing messages.

    from ub_core import bot, Convo
    from pyrogram import filters
    
    async with Convo(
            client=bot, 
            chat_id=1234, 
            filters=filters.text, 
            timeout=10,
        ) as convo:
            await convo.get_response(timeout=10)
            await convo.send_message(text="abc", get_response=True, timeout=8)
            # and so on
    
    
    # Bound Method for quick single usage.
    response = await Convo.get_resp(
            client=bot, chat_id=1234, filters=filters, timeout=timeout
    )
        # Will return First text it receives in chat.

Handlers

By default core registers some handlers automatically on groups 0 and 1.

It is strongly recommended to not register your handlers in groups 0 and 1.

• Group 0:

  Group 0 is for background workers that want to receive all incoming messages. they all call update.continue_propagation() to ensure they're not blocking any incoming updates.

  Conversation relies on this to wait for incoming messages, so make sure to not block this handler group.

• Group 1:

  Group 1 is used for handling incoming commands and is responsible for @add_cmd to work. it WILL call update.stop_propagation() when a command is received and executed so command messages won't trigger the rest of the handlers and create duplicate triggers.(Conversation being in group 0 is exempt from this.)

  Command Handler A Single Handler to handle owner and optional Sudo/ Super [sudo but with same level of access as owner] users relies on this.

UnifiedMessageHandler

UnifiedMessageHandler combines the MessageHandler and EditedMessageHandler classes using inheritance to bring back Pyro v1 filters.edited functionality.

import and use this handler class in your bot.add_handler() to register a single handler for normal and edited messages.

Dispatcher

The Dispatcher

• automatically wraps functions or commands into a asyncio.Task to allow cancellation of a command.
• creates a custom message object and passes that into your functions instead of pyrogram's message class.
• checks for reactions to prevent false triggers if instructed
• gracefully catches and logs errors that might occur while your function is running and logs them to log channel.
• deletes command message if it's from owner
• calls stop_propagation if the current call is a command.

Logging

Ub-core comes with a logging handler that automatically logs any errors to the log channel that occur in the background so you won't miss out on any potential app breaking errors.

It also automatically restarts your python interpreter when it detects network issues happening in pyrogram.

Both of these start automatically and work in background, you don't have to manage them.

Message

A custom Message class to expand on pyrogram's class to add extra goodies.

Check the class for in depth details.

DefaultPlugins

Core comes with a few basic quality of life plugins already added to it.

py, sh, shell, ish, load commands are only accessible by the owner/super users and are only available when DEV_MODE is set to 1 in env.

Utils

• Download class with optional live progress on TG.

  You can use this built in downloader to download large files.

  from ub_core.utils import Download 

• Aio class with a few useful methods and a static website hosting to pass hosts like koyeb, render etc's health checks. (site only runs when a port is provided in env using API_PORT var)

  # import the instance of Aio that was created on initialisation of core.
  from ub_core.utils import aio

Updater

The built in Updater is made to work directly with the bot repo that integrates the core as well as updating the core.

So running .update will check updates for the current workdir's .git repository i.e your integrated bot's working dir.

To update core run .update -c

Comparing_Branches

The default main branch only has a single client and can be run either as an User or a Bot at a time.

The dual_mode branch on the other hand has a DualClient that can run both an User and a Bot at the same time.

It also unlocks the possibility of running some commands inline for sudo/supers in their saved messages or DMs where the bot/user is not present to respond on normal text based commands.

Note: unlike main branch, dual_mode requires database access to save mode data.

Standalone_Usage

Core can be ran as standalone bot with only the inbuilt modules on owner's access.

Core accepts either a BOT_TOKEN or a SESSION_STRING.

if you pass in both, only one will be used if the installed branch is main.

For required variables check sample-config.env

Create a config.env or export those vars to environment along with ENV_VARS set as 1 to instruct core to fetch vars from environment.

type run-ub-core command to start core.

script is automatically installed when you install core using pip