Hummus.py

This is an asynchronous wrapper currently in version 1.1.2!

You can read the official documentation. It is unfinished, so you can currently find it in the docs folder of the Github. The Gitlab repository is currently unmaintained. We will have a ReadTheDocs page soon.

Installation

You can do pip install hummus2016.py to install Hummus.py as a package (you can also use its mirror package, hmus), or you can import it manually by downloading the files from the repository.

Getting started

You can use the following code in the main file to connect to Hummus:

import hummus
import asyncio

class Client(hummus.Client):
	async def on_ready(self,bot):
		print(f"Logged in as {bot.user.username}#{bot.user.discriminator}")

	async def on_message_create(self,message):
		if message.author.id == self.user.id or message.author.bot:
			return
		if "ping" in message.content.lower():
			await message.send("pong")

bot = Client(token="BOT_TOKEN_HERE")

asyncio.run(bot.run())

If you don't want to use the on_message_create event class to detect for commands, you can import Commands from hummus.utils and create functions under that. (remember: In every function, you must have the self and ctx parameters!):

from hummus.utils import Commands

class Cmds(Commands):
	async def test(self,ctx): # you can also add more parameters to create command arguments
		await ctx.reply("test!")

For more information, please refer to our Readthedocs page (coming soon).

Other important notes

Arguments

When adding parameters to command functions in an inherited Commands object, argument splitting will work a little different from other packages.

The argument system looks for quotation marks in a message, and if there is text within quotation marks, no matter if there are spaces, the entire text (within the quotations!) will be considered as a single argument. This allows for easier usage of commands like !nickname where you can specify a nickname with spaces, as long as the nickname is within quotation marks (See documentation on how to disable this).

Quotation marks are not necessary for arguments with no spaces!

Features

Please read the official documentation. It is unfinished, so you can currently find it in the docs folder of the Github repository. If you still need help, look below for ways to contact me.

Support

I am LG125YT#2241 on Hummus, and @ytlg on Discord. My email is [email protected], though I may not check it much.

Credits

• Fossbotpy by arandomnewaccount, used parts of it in in hummus.utils.Enums.Colors and hummus.File processing.
• Discord.py by Rapptz, used in hummus.Permissions and related permissions functionality.
• LmTechyTEMOG's contributions and testing for version 1.0.0 of this package, he helped make the development of v1.0.0 faster.

Changelog

Version 1.1.2:

• Bug fix about too many arguments being passed through internally.

Version 1.1.1:

• Bug fix surrounding @everyone being explicitly added as a role whenever modifying roles.
• Bug fix about an incorrectly named function being used within the library
• Regex filter to suppress all mentions in a "reply" (avoid a double ping by not repeating the ping in the reply content).

Version 1.1.0:

• Many bug fixes, too lazy to remember them all. Some of them are type fixes for python 3.8 (i will forever hate pyright-extended for existing) and support for bots with no avatar set.
• Client.on_ message_create is now not initialized in a thread. This is mainly to attempt to prevent file read/write conflicts if the event and a command executes at the same time and have to deal with the same files.
• Began support for Oldcord. There still needs to be quite a bit of patching.

Version 1.0.0:

• Package revamp, it should now much easier to work on this and make projects using this package. Please note that updating from a version before this will break your project until you make the proper revisions. The following notes will explain all the changes made. Please refer to the [official docs] for more specific usage explanations.
• New utils folder, there's probably some stuff from there you might want to import to make bot development easier. Some of them are explained below.
• Commands and events have moved around. You will need to import Commands from hummus.utils, and inherit that class and add commands there. An inherited Client class now serves only for events. Class initialization for both Client and Commands has therefore changed, please refer to the docs for more information.
• Aliases have been added as an optional decorator for commands, import from hummus.utils, refer to docs for usage.
• Some exceptions are now customizable via inheritance, import CustomizableExceptions from hummus.utils, and refer to the docs for usage.
• Status updates now require passing an instance of the CustomStatus class, which can simply be imported from hummus.
• Enums now exists (import from hummus.utils), there is a section in them for presences and another for status types.
• Hummus.py now uses threading. Why I didn't add it before, I have no idea, but bots should be able to process multiple commands at once now, yay.
• New Context object, contains a Message object, state attribute containing the Client instance active (the same attribute is referred to as instance in every other object it exists in), and an HTTP object (found in http.py) where you can perform every available HTTP request to Hummus.
• Guild has been renamed to PartialGuild, and allGuild has been renamed to Guild. All objects now have the instance attribute, containing the active Client instance. The allGuilds attribute (that contained a list of AllGuild, now Guild, objects), has been renamed to guilds.
• A Client instance now has a state attribute containing a Ready object with data recieved on the READY event. However, the list of guilds is a list of IDs (guilds recieved on READY are marked as unavailable because guilds are loaded through GUILD_CREATE events) since you already have access to the list of guilds the client is in through Client.guilds. The Client instance also has a new user attribute, which is the data you recieve on the account you log into on READY, can also be obtained through ready.user.
• There is no more funcs.py, any sort of permissions checking is now done through a Member or Role object.
• User objects now have a getGuildMember() function, returns a Member object of the user only if the User object has a non-None guild ID attribute.
• Objects now have all available functions respective to their nature (please refer to the docs for a list of them and specifics on their usage), anything HTTP-related calls the necessary function from the HTTP object found in http.py.
• Added hummus.Member as a working type annotation when making a command, will raise exception if mentioned user is not in guild or if the argument is not a mention.
• Added bool as a working type annotation, should be self-explanatory.
• There's likely something I'm forgetting, however, in-depth usage examples and explanations of Hummus.py will be provided in the documentation. Thanks for reading this.

Version 0.7.1:

• Message delete event bug fix
• Guild ban add/remove bug fix
• Me trying to satisfy some random red underlines because oh boy pyright-extended or whatever "corrects" my code loves to be stupid about the randomest stuff
• Randomly the toDict() function for an allGuild object was asynchronous, i un-async-ed it cause like why not (it is literally like 1 line)

Version 0.7.0:

• No more mental breakdown, I tested my scripts! (hopefully)
• Bug fix with emojis not updating for cache
• The State object in the Client object has moved to a new state.py file, a Message object now has a state attribute, and a State object now has a edit function where you pass a channel id, message id, and content.
• New Attachment class, a Message object will now have a list of attachment objects. Attachment objects have the attributes id, filename, size, url, proxy_url, height, and width. Man I really need a readthedocs page or something.

Version 0.6.6, 0.6.7:

• IM SORRY IM SORRY IM SORRY ILL TEST MY SCRIPTS, IM SORRY PYTHON GODS, WHY, WHY, WHYYYYYYYYYYYYYYYYYYYYYYYYYYYY (yes i tested the script this time)

Version 0.6.5:

• Perm checking now actually works hopefully (yay i love publishing untested scripts)

Verson 0.6.4:

• Some bug in guild update got fixed, thats kinda it
• Excuses to pretend that I actively update hummus.py!!!! (real)

Version 0.6.3:

• ok guys, i tested starting up, so stuff should not break now (i love forgetting yet another bug making this unusable)

Version 0.6.2:

• i am so idiot i literally didnt test this version out and realize one of the files was missing a parenthesis! (the whole package broke

Version 0.6.1:

• Bug fixes with setRoles(), addRoles(), and removeRoles() in the Member and User objects
• Forgot to add ban() and unban() functions in the Member and User objects, also their respective gateway events now exist in hummus.Events
• README update, more up-to-date ig

Version 0.6.0:

• AllGuild now inherits from Guild instead of making a Guild attribute in the class.
• New Channel and Emoji objects exist, which arw available in an AllGuild object. PermOverwrites is also a new object that you can create instances of to edit channel permissions.
• All Most events are added. In the middle of this update, banning has been added to Hummus and Oldground, and the events and functions do not exist for it yet.
• Hummus.py now supports catching websocket errors, and auto-restarts if an error occurs (such as heartbeat expiring).
• fullPermsCheck() now correctly checks for server owner ID before returning whether the user has a specific permission.
• Channel object attributes now have support for both voice and text channels.
• User and Member now have role-related functions (addRoles, removeRoles, and setRoles)
• Many of these new objects have a toDict() function, however, this should be mainly internal.
• Message objects now have a guild and channel attribute containing the entire Guild and Channel objects (respectively). The old attributes that only had the ID are now called guild_id and channel_id.
• getGuildChannels() exists as a function in a Message object.
• The Permissions object now supports empty/fake role creation and the creation of a role with only a permissions integer.
• The Role object now has a Permissions object for their permissions attribute.
• The bottoken parameter name has been changed to token when creating a Client/Commands object.
• Hummus.py will now get the cdn url from the base url provided, no need to provide a cdn url when creating a Client/Commands object now.

Version 0.5.2:

• Again, no real changes to hummus.py, but I'm pretty sure I figured out how to fix the previous error. Also, hmus exists as a mirror package now if you don't want to type in hummus2016.py to install the package.

Version 0.5.1:

• No real changes, I'm just trying to fix the pypi issue where import hummus doesnt work. Also updating this file a little to be more up-to-date.

Version 0.5.0:

• You now need to upload files by creating a File object with your file in it. This allows for less cluttering in message.py for the send function, and it allows me to easily add more freedom to uploading files.
• Continuation of above note, you can now provide a file path, bytes object, BytesIO object, or an io.BufferedReader object (the object you get when you assign a variable to open("name.ext","rb"))
• All Message objects now have a delete() function, which sends a request to delete that message on Hummus. (Previously, we only had deleteMessage(id), where you needed to provide a message ID to delete.)
• For some reason, the v0.4.x versions have not been updating the hummus folder, and only the hummus2016 folder. If it persists, consider switching all from hummus import * and import hummus to from hummus2016 import * and import hummus2016. This may also require changing some other lines, or you can use import hummus2016 as hummus.

Version 0.4.1:

• Updates in 0.4.0 didn't push for some reason lol. Here they are (again).
• Turns out that the Image and Thumbnail objects do work, they just require width and height parameters that Hummus.py will automatically take care for you. Nothing has changed, you can continue uploading files as before.
• Fixed bug not letting Hummus.py work, its just me forgetting to include headers when making the request to get the websocket url.

Version 0.4.0:

• Added embed support (Image and Thumbnail objects to not work on Hummus, so they are not included in Hummus.py)
• Added attachment support (You only have to include the filepath)

Version 0.3.4:

• Fixed ctx.edit() so that it edits only the "content" section of the "reply" from ctx.reply() (basically it doesn't edit the whole message)
• Added a new is_reply (boolean), original_reply (content of the message being replied to), and original_author (User class) attributes to the Message object
  • is_reply is entirely local, it is only true for a message object where the ctx.reply() function is used, and cannot detect replies outside of ctx.reply()
• Errors caught by the package exception handler now print out the traceback
• Minor changes to the README

Version 0.3.3:

• Updated the README (this thingy you're reading!) to not have the wackiest indents (frick you replit)

Version 0.3.2:

• Fixed hummus.py not working when you didn't manually register an Events class to listen.

Version 0.3.1:

• Quick update just added ctx.deleteMessage(id) because i forgor to add it before :sku:

Version 0.3.0:

• More events in the Events class work now, also self.allGuilds in the Client class now updates on related events like guild member join/leave and guild add/remove
• Client class initialization redone a little, see the "Getting Started" and "Events" section in this README
• Command args should now fully work, you do not need to add a default value to parameters and some annotations (namely str,int, and hummus.member.User) now work
• The Author class has been renamed to the User class because most use cases within the package do not reflect the "Author" status of a user (this should not affect much of anything since annotations did not work before this update)

Too lazy to log changes from before, if you want to do it for me, go for it.

Contributing

Contribute if you want, you can make a pull request on the GitLab repository or GitHub repository, or fork the Replit project. Note that the Replit project is the most recent version of Hummus.py, because it is where I test new features. You can see upcoming features on the Replit project if you want.

Authors

This wrapper was made by LG125YT. Contact me on Hummus (LG125YT#2241) or Discord (@ytlg).