RoleInvite

API Reference

class roleinvite.api.API(bot, config)[source]

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__
await add_invite(guild: discord.guild.Guild, invite: str, roles: list) → bool[source]

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. :raises CannotGetInvites: The bot doesn’t have the permission to get the guild’s invites :raises EmptyRolesList: The list of roles given is empty :raises InviteNotFound: The invite given doesn’t exist in the guild.

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 get_invites(guild) → dict[source]

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

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

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 update_invites() → dict[source]

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

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.CannotAddRole[source]

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

exception roleinvite.errors.CannotGetInvites[source]

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

exception roleinvite.errors.EmptyRolesList[source]

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

exception roleinvite.errors.InviteNotFound[source]

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

exception roleinvite.errors.NotInvite[source]

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