Package: re-ircbot
re-ircbot, a simple irc bot libraryThis is a simple irc bot library that uses trio for async callback processing and allows you to
use persistent data based on user's nick and channels. The callbacks for commands are defined by regular expressions.It even features hot reloading for the best development experience! You might want to take a look on the examples folder.How to installpip3 install re-ircbotThen take one of the examples and start modifying!Basic usageDefine regex commandsCommands are defines with regexps using a decorator around the callback
function. Everything is async. Either user the utils.regex_cmd for
simplicity or utils.regex_cmd_with_messsage if you need to know info about the
sender and if it is a private chat.@utils.regex_cmd("^!command$")defhandler(m):return"hi!"@utils.regex_cmd("^lol$")deflol(m):return"YOU SHALL NOT SAY LOL"The first argument of a handler function will always be a Match object:https://docs.python.org/3/library/re.html#match-objects@utils.regex_cmd_with_messsage("^who is (.*)$")defwhoami(m,message):m=m.group(1)returnf"You are{message.sender_nick}and I have no idea who{m}is"With regex_cmd_with_messsage there will be 2 arguments for the handler function which are the Match and the message object. The important parameters of Message are sender_nick, channel, message, is_private.The callback/handler functions can g a string, Message objects, Color objects or a list of any of those, to be sent back by the bot, a Message object, a ReplyIntent or None to send nothing.Define simple argument commandsIf all you want is a bot that take simple commands like!start!helpetc... You can use theutils.arg_commanddecorator:@utils.arg_command("test","Oh this is just some test","This command is used for like testing")defextra(args,message):returnColor("Random",Color.random())Where you can define the commandtestand with that you are also adding it to the help menu(utils.help_menu) and defining the message to display forhelp test. This will automatically create the help command. args there is still a regex match object, so the arguments start from 1, like if you calltest a b cargs[1] is a, args[2] is b and so on.You can also use theutils.setCommandsfunction to add commands all together from defined functions by passing in a dict. To change the commands prefix useutils.setPrefix. Both setCommands and the arg_command wrapper will usesimplify=Trueby default, which means the bot will accept the minimal prefix versions of the defined commands.Look at the examples to learn more.Launch the botutils.setLogging(LEVEL,LOGFILE)bot=IrcBot(HOST,PORT,NICK,CHANNELS,PASSWORD)bot.run()ColorsYou can use the Color class from IrcBot.Color(text, fg, bg) Colorize text with the fg foreground and bg backdroundColor.COLORS is the list of number codes for colorsColor.random() gs a random colorColor.str string version of the Color. Useful if you want to combine this with other Colors or textData permanencyData permanency is based on sqlite3. Define a variable like:people=persistentData("filename.db","table_name",["name","age","nickname"])The first two arguments are self explanatory. The last is a list of columns that the table will have and that you will be able to access through people.data, e.g.people.data[0]["name"]to see the name of the first registered person. people.data will be a list of dicts with the given keys/columns.Then pass it to the bot constructor as the tables argument. Notice it takes a list since you might want to have multiple of these.:bot=IrcBot(HOST,PORT,NICK,CHANNELS,PASSWORD,tables=[people])Wait for user responseStill continuing the data permanency example, you can now modify the variable on callback functions by either using the push, pop or update methods:@utils.regex_cmd_with_messsage("^!register (.*) (.*) (.*)$")# name, age, nicknamedefhandler(omsg,message):people.push([m.group(1),m.group(2),m.group(3)])# or#people.push({"name": m.group(1), "age": m.group(2),"nickname": m.group(3)})returnMessage(channel=message.)@utils.regex_cmd_with_messsage("^!register.*$")defregister(m,message):returnReplyIntent("Enter your name, age and nickname",lambdamsg:handler(original_message,msg))The regexps are matched in the other they are declared and there will be only one callback for each user input, which corresponds to the first defined callback that is matched. Like in this case the handler function will run directly if some user sends "!register name 23 nickname" but the register function won't run. If they were in swapped order then register would just always run.A ReplyIntent means that the next message this same user sends will be handled with the passed in function. This function will just receive the string message that is sent by the user next. You can specify a different channel, user, by passing in a Message object with the desired parameters for the ReplyIntent first argument.Run independently of user inputYou can call an async function after the bot connects and join a channel if it was passed to the Bot's constructor. This way you can get the bot respond independently, like send messages even if not command or regexp was sent by a user. To do this, instead of callingbot.run()dobot.runWithCallback(asyncFun):(...)asyncdefasyncFun(bot):awaitbot.sleep(1)# Not necessary, I am just showing you can wait for 1 second like thisawaitbot.join("#somechannel")awaitbot.send_message("Hello guys!!!!")bot=IrcBot(HOST,PORT,NICK,CHANNELS,PASSWORD)bot.runWithCallback(mainLoop)Take a look at the patternSpam.py example for more details.wait_for (event)You can also use async handlers to await for user input using the bot's methodwait_for. Here is an example to check and await for user's input:asyncdefask(bot:IrcBot,nick:str,question:str,expected_input=None,repeat_question=None,loop:bool=True,timeout_message:str="Response timeout!",):awaitbot.send_message(question,nick)resp=awaitbot.wait_for("privmsg",nick,timeout=10)whileloop:ifresp:ifexpected_inputisNoneorresp.get("text").strip()inexpected_input:breakawaitbot.send_message(repeat_questionifrepeat_questionelsequestion,nick)else:awaitbot.send_message(timeout_message,nick)breakresp=awaitbot.wait_for("privmsg",nick,timeout=600)returnresp.get('text').strip()ifrespelseNone@utils.arg_command("test")asyncdeftest(bot:IrcBot,args,msg):nick=msg.nickresp=awaitask(bot,msg.nick,f"{nick}: say yes/no",["yes","no"],repeat_question="You must reply with yes or no")returnf"Your answer is: '{resp}'"Notice that awaiting forresp = await bot.wait_for("privmsg", nick, timeout=10)will pause the execution until either a matching event fromnickof typeprivmsg(which means both channel messages or DM's) arrives or the timeout happens.Here is another example of using wait_for to detect if a user is identified with the nickserv:asyncdefis_identified(bot:IrcBot,nick):globalnick_cachenickserv="NickServ"awaitbot.send_message(f"status{nick}",nickserv)msg=awaitbot.wait_for("notice",nickserv,timeout=5,cache_ttl=60,# We need filter because multiple notices from nickserv can come at the same time# if multiple requests are being made to this function all togetherfilter_func=lambdam:nickinm["text"],)returnmsg.get("text").strip()==f"{nick}3{nick}"ifmsgelseFalseHere we used a lower timeout because nickserv should reply faster than any user, thecache_ttloption will keep results cached for the given time, andfilter_funcmust be a callable to be ran against any matched event (even if it is a cached result). The event will be only considered validif filter_func(is True).MiddlewaresCurrently simple middlewares are supported for every event handler (regex or command). A middleware is an async function that will take the bot instance and the Message and this method will run before every handler. You can decide to proceed and call the handler if this method returnsTrueor deny it if it returnsFalseorNone. On that case execution will be stopped.The method used to add a middleware function is:bot.add_middleware(callback).Here is an example for not letting the bot respond to other bots by checking the "+B" mode flag:# define some handlers here with utils.arg_commands_with_message# or utils.regex_commands_with_message or whatever....asyncdefcheck_no_bot(bot:IrcBot,message:Message):awaitbot.send_raw(f"WHO{message.nick}")resp=awaitbot.wait_for("who",message.nick,timeout=10,cache_ttl=10)if"B"inresp["modes"]:returnFalsereturnTrueasyncdefon_connect(bot:IrcBot):awaitbot.send_raw(f"MODE{bot.nick}+B")if__name__=="__main__":utils.setLogging(LEVEL,LOGFILE)bot=IrcBot(HOST,PORT,NICK,CHANNELS,PASSWORD,strip_messages=False,use_ssl=SSL)bot.add_middleware(check_no_bot)bot.runWithCallback(on_connect)Tips and tricks (logging, async, etc)First of all: currently it is only possible to have one bot only per python call. This means you should define only one bot per file.None, strings, a list of strings and Message can be used on the same places through this library.None: Means no message to send, like if you justreturnon some functionstr:  If you want to just send a string or f-string[str1, str2, ...]: To send multiple messages as separated messages.Message: If you want to specify the channel, or send a private message.ReplyIntent: If you want to set a callback for the next user message and
establish a dialog.Color: To send a colored message.Everything is asynchronously handled so you might not want to user something
besides the push, pop and update methods for the data permanency functions and
also not try to send messages manually.Echo bot.defecho(msg):ifmsg=="stop":returnreturnReplyIntent(msg,echo)@utils.regex_cmd_with_messsage(getcmd("^!include.*$",ACCEPT_PRIVATE_MESSAGES)definclude(m,message):returnReplyIntent(Message(channel=message.sender_nick,sender_nick=message.sender_nick,message="Hello! echo mode activated"),echo)Hot reloadYou can hot reload your bot with a command like:@utils.arg_command("reload")asyncdefreload(bot,args,message):awaitbot.hot_reload()return"Reloaded"Or you can have it automatically track file changes using the environment variableIRCBOT_HOT_RELOADfor example:IRCBOT_HOT_RELOAD=truepythonexamples/hotreload.py<<<On this mode it will automatically check and refresh when a new command is issued. Make sure to only use this in development mode!FAQDon't know how to use re match objects? convert it to a list with:utils.m2list(args)To add a color with a string usecolor.str + another_stringQ.Why aren't my regex expressions being matched?The regex commands you defined last will be matched first. That said, check up
the documentation for python's re module. Also notice that regex expressions do
not work for utils.arg_command or using setCommands, they commands will be
escaped by re.escape.Q.Can I use async functions on my callbacks?Yes, you can use any of the decorators with async functions as wellQ.What happens if i send colored messages?Currently they will be simply treated as normal text. This bot does not care
about user input colors but it can still send colored messages.Q.Why my async callback doesn't work? (or how does it even work)Compared to non async callback functions, if you try to use an async callback
like in one of util's wrappers, you will need to pass an extra argument in the
first position that is 'bot', an IrcBot object which represents the current
bot. With this you can use IrcBot's methods within a callback function like for
a command or custom_handler.Q.How can I add actions for user, join, part etc.Take a look at the utils.custom_handler decorator.ROADMAPFor version 2.0:SASL AUTHENTICATIONHandle weird character's on input (Colors, fonts, underlines, glyphs etc)Convert utils to an actual class that can be used as a contextDcc file transfer