RoleInvite

API Reference

class roleinvite.api.API(bot, config)

Bases: object

Interact with RoleInvite from your cog.

To import the cog and use the functions, type this in your code:

roleinvite = bot.get_cog('RoleInvite').api

Warning

If roleinvite is None, the cog is not loaded/installed. You won’t be able to interact with the API at this point.

Tip

You can get the cog version by doing this

version = bot.get_cog('RoleInvite').__version__

escape_invite_links(text: str) → str

Return a Discord invite link that won’t show an embed

Parameters

text (str) – The text which needs to have invite links previews removes

Returns

text – The cleared text

Return type

str

await update_invites() → dict

Update all invites registered to keep their uses count good.

This is usually called on cog load since these values could have been modified while the bot or the cog was offline.

Returns

The updated dictionnary.

Note

The value enabled may have been switched to False if the manage_guild permission was lost on the guild.

Return type

dict

await add_invite(guild: discord.guild.Guild, invite: str, roles: list) → bool

Add an invite link to the autorole system.

Parameters

• guild (discord.Guild) – The guild to get the invites from.

• invite (str) – The invite link to create/extend. Give main or default if you want to edit the main/default autorole system.

• roles (list) – A list of roles ID to add to the roles list.

Returns

True if successful

Return type

bool

Raises

• NotInvite – The invite given is not a discord invite, not is is main/default.

• CannotGetInvites – The bot doesn’t have the permission to get the guild’s invites

• EmptyRolesList – The list of roles given is empty

• InviteNotFound – The invite given doesn’t exist in the guild.

await remove_invite(guild: discord.guild.Guild, invite: str, roles: list = []) → bool

Remove a list of roles from the invite links.

Parameters

• guild (discord.Guild) – The guild to get the invites from.

• roles (list) – A : py:class:list of roles ID to remove from the roles list. If it’s empty, it will remove the invite from the autorole system.

• invite (:py:class`str`) – The invite to remove roles from. Give main or default to edit the main/default autorole system.

Returns

True if successful.

Return type

bool

Raises

KeyError – The invite given doesn’t exist.

await get_invites(guild) → dict

Return a list of the invites linked to the autorole system of the guild.

Parameters

guild (discord.Guild) – The guild to get the invites from.

Returns

A dict of invites linked to any role on the guild.

Example

{
    "main" : {
        "roles" : [
            987654321234567890
        ]
    },
    "https://discord.gg/example" : {
        "roles" : [
            012345678987654321,
            987654321234567890
        ],
        "uses" : 42
    }
}

Return type

dict

Errors

Custom error handling used for the cog and the API

If you need to prevent and exception, do it like this

errors = bot.get_cog('RoleInvite').errors

try:
    await api.add_invite(
        ctx.guild, 'main', [42]
    )
except errors.CannotAddRole:
    print("Missing permissions")
except InviteNotFound:
    print("Invalid invite")
except:
    # occurs for any exception
    print("Fatal error")
else:
    # executed if the try succeeded
    print("All good")
finally:
    # always executed
    print("End of function")

exception roleinvite.errors.EmptyRolesList

Bases: Exception

The list of roles that needs to be linked to an invite is empty.

exception roleinvite.errors.NotInvite

Bases: Exception

The invite sent is not found as a discord.Invite object.

exception roleinvite.errors.InviteNotFound

Bases: Exception

The invite sent isn’t in the guild’s invite list.

exception roleinvite.errors.CannotGetInvites

Bases: Exception

The bot isn’t allowed to get the guild invites. Manage server permission is needed.

exception roleinvite.errors.CannotAddRole

Bases: Exception

The bot isn’t allowed to give a role. The role hierarchy was modified or a 3rd party module added the role without check.