Developing Modules

Before you start...

Before you start to create your own (hopefully not harmful) modules, you need to know few, yeah actually not few information:

• You need to be familiar with Python. We will not teach you how Python works though basic knowlegde about Python are enough
• Create a new Python script (yourscript.py)
• Read everything below carefully!
• Your new modules do belong to the modules_user (HyperUBot/userbot/modules_user) folder. Do not move them to modules folder!
• Last but not least, you will need patience, specially if it's your first time

Predefined Classes and Functions

HyperUBot does offer own predefined classes and functions. Check them out, as it could save you much time coding your own stuff!

Read the Telethon documentation

Telethon has it's own documentation. If you need anything that may has to get a person's info, your own account settings, understanding the events or anything else that need to send an API request, make sure to read the Telethon docs.

Getting started with the basics

For a Python script to be minimally compatible with the bot, and having the possibility to be run as a command, you will need to import the EventHandler, from userbot.sysutils.event_handler. The EventHandler is capable to catch Telegram events with the help of Telethon such as new messages, edited messages, chat actions (join, leave etc.) and much more. After this, create a new EventHandler object, like the example below:

from userbot.sysutils.event_handler import EventHandler  # The EventHandler object

ehandler = EventHandler()  # The specific handler of our new module

Note: The code example above demonstrate a whole Python script (not just a part of it), same to the following codes. Your are free to copy the examples we made.

You can also pass a logger to EventHandler as parameter to log stuff to terminal and follow error traces easier:

from userbot.sysutils.event_handler import EventHandler  # The EventHandler object
from logging import getLogger  # import getLogger

log = getLogger(__name__)  # pass the current module's name
ehandler = EventHandler(log)  # set logger as parameter to EventHandler

The power of outgoing commands

Nearly used by all commands that are out there, the outgoing commands. There are rarely commands that do not listen to outgoing messages. Anyway let's start with your command now. First of all, due to the fact that almost all prefunctions of Telethon are asynchronous, your bot command functions should be asynchronous too to be able to use these functions with await. This can be done, while declaring a function, by using the keyword async. Before declaring the function, however, you should add a line referencing to the EventHandler you created (meant is @ehandler.on()), specifying the command that triggers that action. An example could be:

from userbot.sysutils.event_handler import EventHandler
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

@ehandler.on(command="example", hasArgs=True, outgoing=True)
async def example(event):
    await event.edit("This is an example!")
    # Your stuff
    return

• command="example" tells the EventHandler to which command it should listen to, to trigger the specific function (your function in this case). As soon as you send .example message in any chat, EventHandler will execute your function, in other words it will edit your .example message to This is an example!.
• hasArgs=True tells the EventHandler whether your command takes more than just .example e.g. .example test. We calling this Arguments (hasArgs -> has Arguments). Some of our commands we made do accept arguments as well for example .ban, .speedtest etc.
• outgoing=True tells the EventHandler to listen to outgoing messages only, so messages you do sent

Note: You should guarantee that your command isn't already used by a different module, specially not by modules we made. We made a list where you can check if our modules use a specific command already.

The bad reputation of incoming commands

What's the opposite of outgoing? You think it's incoming? Well yes, that may be. Incoming commands do as you may thought already listen to incoming messages only. Coding wise it's pretty much similar to outgoing commands:

from userbot.sysutils.event_handler import EventHandler
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

@ehandler.on(command="example", hasArgs=True, incoming=True)  # <--- Look to the left!
async def example(event):
    await event.reply("This is an example response!")
    # Your stuff
    return

The table turns: now your userbot will response to everyone who sent .example in any chat where you're a participant.

Note: This is the start of the misery, people could abuse it to let your userbot spam in a chat. As consequence Telegram may ban your account, temporary or in worst case permanently for spamming! Use incoming feature if you can limit the access to it for certain or specific stuff only.

Freedom for on() listeners! (but only if you're a Hackerman)

The EventHandler offers more than just the on listener (remember: @ehandler.on()) which is limited for certain stuff only like the pattern, prefix, etc. If you want your command to be executed with a different prefix (not to dots) you can simply use a different listener. We called it on_Pattern listener. It offers much more customization for the developer. However we can't explain every detail how it works here. Check out it's wiki instead.

Example usage of on_Pattern:

from userbot.sysutils.event_handler import EventHandler
from telethon.events import NewMessage, MessageEdited
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

@ehandler.on_Pattern(pattern=r"^\!example(?: |$)(.*)",  # regex of example command 
                     events=[NewMessage, MessageEdited],  # used events
                     name="example",  # the name of the command
                     prefix="!",  # prefix of the command
                     hasArgs=True,  # does it take arguments? regex should match too
                     outgoing=True)  # listen to outgoing messages only
async def example(event):
    await event.edit("example confirmed!")
    return

As soon as you send !example in any chat, EventHandler will edit it to example confirmed!. The example code above works the same to on functions we had in our examples before this. The difference is, it will now response to ! and not to . anymore.

You see it's more complex and meant for devs who really want more than just the basics.

Extra configurations needed? No problemo! but not too complicated please

If a specific configuration is required for your module, add your custom configuration to the existing configurations in your config file. HyperUBot loads all configurations independent from config.env, config.ini or config.py automatically, so any special instruction is not required to add custom configurations.

To get a certain configuration you need to import getConfig() from userbot.sysutils.configuration. This prefunction allows you to get any config stored in the global configs of HyperUBot which works as followed:

getConfig(config_name[, default_value])

• config_name: is the name of your custom configuration
• default_value (optional): default value in case config_name doesn't exist

getConfig() returns the value from config_name else from default_value. If config_name does not exist and default_value is not set, None will be returned instead

Example usage:

from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.configuration import getConfig  # import getConfig

ehandler = EventHandler()

@ehandler.on(command="myconfig", hasArgs=True, outgoing=True)
async def example(event):
    myConfig = getConfig("MYCUSTOMCONFIG")  # get your custom config
    await event.edit("This is my custom config: " + myConfig)
    return

It's recommended to read our Configurations wiki to understand how our configuration system works.

Store attributes in a file? Can I do that?

Sure why not. We made a Properties class which allow you to store you module attributes to a file. Pretty useful if you want your module to load them later after a reboot, or after a long pause. To do so, import Properties from userbot.sysutils.properties. Properties have 3 core functions: init_props(), getprop() and setprop()

Example usage:

from userbot.sysutils.properties import Properties  # import Properties

props = Properties("myprops")  # setup file
props.init_props()  # initialize props, checks if prop file isn't used already
props.setprop("testKey", "testValue")  # store key 'testKey' to 'myprops' file
print(props.getprop("testKey"))  # get 'testKey' from 'myprops' file

This is the basic way to use Properties but it's also usable in command functions:

from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.properties import Properties
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

props = Properties("myprops")
props.init_props()

@ehandler.on(command="example", hasArgs=True, outgoing=True)
async def example(event):
    props.setprop("testKey", "testValue")
    my_prop = props.getprop("testKey")
    if my_prop:
        await event.edit("This is my prop: " + my_prop)
    else:
        await event.edit("Seems like my prop is empty :-(")
    return

Tip: Yes, Properties has it's own wiki too

I want to explain how my command works! And become famous!!1!1!!!11

HyperUBot allows you to register your module and command usage(s) with 3 definitely simply functions which need to be imported from userbot.sysutils.registration:

# Register the usage of a command or feature
register_cmd_usage("name of cmd/feature", "it's arguments", "usage")

# Register the description of a module
register_module_desc("description")

# Register the info e.g version, author etc. of a module
register_module_info("name", "author(s)", "version")

As soon as your information are successfully registered, you can view them with the .mods or .lcmds <your cmd> commands

Example usage:

from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.registration import (register_cmd_usage,
                                           register_module_desc,
                                           register_module_info)
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

@ehandler.on(command="example", hasArgs=True, outgoing=True)
async def example(event):
    await event.edit("This is an example!")
    # Your stuff
    return


register_cmd_usage("example",
                   "[optional: <ID>]",
                   "Prints an example response")

register_module_desc("I'm an example module!")
register_module_info(
    name="Example",
    authors="Mr.example",
    version="1.0"
)

Still not famous? Don't worry, we aren't either :)

Note: You won't believe it but there is a Registration wiki!

My module need extra pip packages!

Does it? Yes, our modules too but if your module require pip packages that are not listed in our requirements.txt then you may like our pip_utils script, which will help you to install the required pip packages automatically if needed. To do so, you need to import userbot.include.pip_utils

Example usage with checkPkgByDist() and installPkg():

import userbot.include.pip_utils as pip  # import pip_utils
from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.registration import (register_cmd_usage,
                                           register_module_desc,
                                           register_module_info)
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

# START CHECK PART
# check if requests package does exist
if not pip.checkPkgByDist("requests"):
    # if not, install it
    if not pip.installPkg("requests"):
        # if installation failed:
        # this makes your module to crash but the actual idea is to let
        # the user know it's not possible to use this module
        # without 'requests' package
        raise ModuleNotFoundError("requests package not installed")
# END CHECK PART

import requests  # noqa: E402


@ehandler.on(command="example", outgoing=True)
async def example(event):
    await event.edit("This is an example!")
    # Do stuff with requests
    return


register_cmd_usage("example", None, "Very example, wow.")
register_module_desc("I'm an example module!")
register_module_info(
    name="Example",
    authors="Example",
    version="1.0"
)

Example usage with checkPkgByImport() and installPkg():

import userbot.include.pip_utils as pip
from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.registration import (register_cmd_usage,
                                           register_module_desc,
                                           register_module_info)
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

# START CHECK PART
# if you don't know the distribution name but the
# import name use checkPkgByImport
if not pip.checkPkgByImport("requests"):
    if not pip.installPkg("requests"):
        raise ModuleNotFoundError("requests package not installed")
# END CHECK PART

import requests  # noqa: E402


@ehandler.on(command="example", outgoing=True)
async def example(event):
    await event.edit("This is an example!")
    # Do stuff with requests
    return


register_cmd_usage("example", None, "Very example, wow.")
register_module_desc("I'm an example module!")
register_module_info(
    name="Example",
    authors="Example",
    version="1.0"
)

Check if a proper version of a package is installed:

import userbot.include.pip_utils as pip
from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.registration import (register_cmd_usage,
                                           register_module_desc,
                                           register_module_info)
# to convert string version to tuple
from userbot.sysutils.sys_funcs import verAsTuple
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

# START CHECK PART
if pip.checkPkgByImport("requests"):
    requests_version = pip.getVersionFromDist("requests")
    if verAsTuple(requests_version) < (1, 2, 3):  # requires at least v1.2.3
        # upgrade the package!
        pip.installPkg("requests", upgrade=True)
else:
    # install the package. automatically installs the latest version
    pip.installPkg("requests")
# END CHECK PART

import requests  # noqa: E402


@ehandler.on(command="example", outgoing=True)
async def example(event):
    await event.edit("This is an example!")
    # Do stuff with requests
    return


register_cmd_usage("example", None, "Very example, wow.")
register_module_desc("I'm an example module!")
register_module_info(
    name="Example",
    authors="Example",
    version="1.0"
)

Note: Please don't call installPkg() unnecessarily as it will spam the terminal logger much. Always check first if it's actually required to install/upgrade a pip package (checkPkgByDist() and checkPkgByImport()). By this, it will keep the start of HyperUBot fast as it should be.

I want my commands to support a specific version of HyperUBot only!

There is a cool function which is able to wrap your commands or features, and start them only if it matches a certain version of HyperUBot or if the version of HyperUBot is between 2 given versions. You need to import requiredVersion() from userbot.sysutils.sys_funcs

Example usage:

from userbot.version import VERSION_TUPLE  # import bot version (tuple)
from userbot.sysutils.event_handler import EventHandler
from userbot.sysutils.registration import (register_cmd_usage,
                                           register_module_desc,
                                           register_module_info)
from userbot.sysutils.sys_funcs import (requiredVersion, # import requiredVersion
                                        verAsTuple)  # convert string version to tuple
from logging import getLogger

log = getLogger(__name__)
ehandler = EventHandler(log)

# Add to handler if HyperUBot version is between 4.0.0 and 5.0.0
@ehandler.on(command="example", outgoing=True)
@requiredVersion("4.0.0", "5.0.0")
async def example(event):
    await event.edit("I'm an example function!")
    return


@ehandler.on(command="example2", outgoing=True)
@requiredVersion("5.0.2", "5.0.2")  # version should match exactly v5.0.2
async def example2(event):
    await event.edit("I'm an example2 function!")
    return


# Register usages only if HyperUBot version match required versions
if verAsTuple("4.0.0") >= VERSION_TUPLE and \
   verAsTuple("5.0.0") <= VERSION_TUPLE:
    register_cmd_usage("example", None, "Very example, wow.")
if verAsTuple("5.0.2") == VERSION_TUPLE:
    register_cmd_usage("example2", None, "Very much example, very wow.")

register_module_desc("I'm an example module!")
register_module_info(
    name="Example",
    authors="Example",
    version="1.1"
)

If the version of HyperUBot does not meet the required version you expect then EventHandler won't add them

Can I release my module to finally become famous?

Sure, you can create a community repo and allow people to install your module with Package Manager. Just follow our Community Repo wiki. It shouldn't be a big deal if you follow the steps there carefully.

---

Hopefully, the mechanic of developing own modules is now simple and understandable. Still got some questions? Ask us!

Happy coding!