Roles¶

The following section documents everything related to roles.

Models¶

BaseRole¶

Attributes

id
members
server
server_id
state

Methods

async delete
async edit
def get_server
async set_permissions

class stoat.BaseRole(*, state, id, server_id)[source]¶

Represents a base role in Stoat server.

This inherits from Base.

server_id¶

The server’s ID the role belongs to.

Type:: str

get_server()[source]¶: Optional[Server]: The server this role belongs to.

property members[source]¶

The members who have this role.

Type:: List[Member]

property server[source]¶

The server this role belongs to.

Type:: Server

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes the role.

You must have manage_roles to do this.

Fires ServerRoleDeleteEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

NotElevated

Rank of your top role is higher than rank of role you’re trying to delete.

MissingPermission

You do not have the proper permissions to delete role.
NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, name=UNDEFINED, color=UNDEFINED, hoist=UNDEFINED, rank=UNDEFINED)[source]¶

This function is a coroutine.

Edits the role.

You must have manage_roles to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new role name. Must be between 1 and 32 characters long.
color (UndefinedOr[Optional[str]]) – The new role color. Must be a valid CSS color.
hoist (UndefinedOr[bool]) – Whether this role should be displayed separately.
rank (UndefinedOr[int]) –
The new ranking position. The smaller value is, the more role takes priority.

Deprecated since version 1.2: Use bulk_edit_role_ranks() instead.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value

Reason

NotElevated

One of these:

Rank of your top role is higher than rank of role you’re trying to edit.
Rank of your top role is higher than rank you’re trying to set for this role.

MissingPermission

You do not have the proper permissions to edit role.

NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated role.

Return type:

Role

await set_permissions(*, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for this role.

You must have manage_permissions to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow.
deny (Permissions) – The permissions to deny.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit permissions for this role.

NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server with new permissions.

Return type:

Server

id¶

The ID of the entity.

Type:: str

state¶

The state that controls this entity.

Type:: State

PartialRole¶

Attributes

color
hoist
id
members
name
permissions
rank
server
server_id
state

Methods

async delete
async edit
def get_server
def into_full
async set_permissions

class stoat.PartialRole(*, state, id, server_id, name, permissions, color, hoist, rank)[source]¶

Represents a partial role for the server.

Unmodified fields will have UNDEFINED value.

This inherits from BaseRole.

name¶

The new role’s name.

Type:: UndefinedOr[str]

permissions¶

The new role’s permissions.

Type:: UndefinedOr[PermissionOverride]

color¶

The new role’s color. This can be any valid CSS color.

Type:: UndefinedOr[Optional[str]]

hoist¶

Whether this role should be shown separately on the member sidebar.

Type:: UndefinedOr[bool]

rank¶

The new role’s rank.

Type:: UndefinedOr[int]

into_full()[source]¶: Optional[Role]: Tries transform this partial role into full object. This is useful when caching role.

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes the role.

You must have manage_roles to do this.

Fires ServerRoleDeleteEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

NotElevated

Rank of your top role is higher than rank of role you’re trying to delete.

MissingPermission

You do not have the proper permissions to delete role.
NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, name=UNDEFINED, color=UNDEFINED, hoist=UNDEFINED, rank=UNDEFINED)[source]¶

This function is a coroutine.

Edits the role.

You must have manage_roles to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new role name. Must be between 1 and 32 characters long.
color (UndefinedOr[Optional[str]]) – The new role color. Must be a valid CSS color.
hoist (UndefinedOr[bool]) – Whether this role should be displayed separately.
rank (UndefinedOr[int]) –
The new ranking position. The smaller value is, the more role takes priority.

Deprecated since version 1.2: Use bulk_edit_role_ranks() instead.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value

Reason

NotElevated

One of these:

Rank of your top role is higher than rank of role you’re trying to edit.
Rank of your top role is higher than rank you’re trying to set for this role.

MissingPermission

You do not have the proper permissions to edit role.

NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated role.

Return type:

Role

get_server()[source]¶: Optional[Server]: The server this role belongs to.

id¶

The ID of the entity.

Type:: str

property members[source]¶

The members who have this role.

Type:: List[Member]

property server[source]¶

The server this role belongs to.

Type:: Server

server_id¶

The server’s ID the role belongs to.

Type:: str

await set_permissions(*, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for this role.

You must have manage_permissions to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow.
deny (Permissions) – The permissions to deny.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit permissions for this role.

NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server with new permissions.

Return type:

Server

state¶

The state that controls this entity.

Type:: State

Role¶

Attributes

color
hoist
id
members
name
permissions
rank
server
server_id
state

Methods

async delete
async edit
def get_server
def locally_update
async set_permissions
def to_dict

class stoat.Role(*, state, id, server_id, name, permissions, color, hoist, rank)[source]¶

Represents a role in Stoat server.

This inherits from BaseRole.

name¶

The role’s name.

Type:: str

permissions¶

Permissions available to this role.

Type:: PermissionOverride

color¶

The role’s color. This is valid CSS color.

Type:: Optional[str]

hoist¶

Whether this role should be shown separately on the member sidebar.

Type:: bool

rank¶

The role’s rank.

Type:: int

locally_update(data, /)[source]¶: Locally updates role with provided data.

Warning

This is called by library internally to keep cache up to date.

to_dict()[source]¶: dict: Convert role to raw data.

await delete(*, http_overrides=None)[source]¶

This function is a coroutine.

Deletes the role.

You must have manage_roles to do this.

Fires ServerRoleDeleteEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.
Forbidden – Possible values for type:

Value

Reason

NotElevated

Rank of your top role is higher than rank of role you’re trying to delete.

MissingPermission

You do not have the proper permissions to delete role.
NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

await edit(*, http_overrides=None, name=UNDEFINED, color=UNDEFINED, hoist=UNDEFINED, rank=UNDEFINED)[source]¶

This function is a coroutine.

Edits the role.

You must have manage_roles to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
name (UndefinedOr[str]) – The new role name. Must be between 1 and 32 characters long.
color (UndefinedOr[Optional[str]]) – The new role color. Must be a valid CSS color.
hoist (UndefinedOr[bool]) – Whether this role should be displayed separately.
rank (UndefinedOr[int]) –
The new ranking position. The smaller value is, the more role takes priority.

Deprecated since version 1.2: Use bulk_edit_role_ranks() instead.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value

Reason

NotElevated

One of these:

Rank of your top role is higher than rank of role you’re trying to edit.
Rank of your top role is higher than rank you’re trying to set for this role.

MissingPermission

You do not have the proper permissions to edit role.

NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The newly updated role.

Return type:

Role

get_server()[source]¶: Optional[Server]: The server this role belongs to.

id¶

The ID of the entity.

Type:: str

property members[source]¶

The members who have this role.

Type:: List[Member]

property server[source]¶

The server this role belongs to.

Type:: Server

server_id¶

The server’s ID the role belongs to.

Type:: str

await set_permissions(*, http_overrides=None, allow=<Permissions: 0>, deny=<Permissions: 0>)[source]¶

This function is a coroutine.

Sets permissions for this role.

You must have manage_permissions to do this.

Fires RawServerRoleUpdateEvent for all server members.

Parameters:

http_overrides (Optional[HTTPOverrideOptions]) – The HTTP request overrides.
allow (Permissions) – The permissions to allow.
deny (Permissions) – The permissions to deny.

Raises:

Unauthorized – Possible values for type:

Value

Reason

InvalidSession

The current bot/user token is invalid.

Forbidden – Possible values for type:

Value	Reason
`CannotGiveMissingPermissions`	Your new provided permissions contained permissions you didn’t have.
`NotElevated`	Rank of your top role is higher than rank of role you’re trying to set override for.
`MissingPermission`	You do not have the proper permissions to edit permissions for this role.

NotFound – Possible values for type:

Value

Reason

NotFound

The server/role was not found.
InternalServerError – Possible values for type:

Value

Reason

Populated attributes

DatabaseError

Something went wrong during querying database.

collection, operation

Returns:

The updated server with new permissions.

Return type:

Server

state¶

The state that controls this entity.

Type:: State

Value	Reason
`InvalidSession`	The current bot/user token is invalid.

Value	Reason	Populated attributes
`DatabaseError`	Something went wrong during querying database.	`collection`, `operation`

Value	Reason
`NotFound`	The server/role was not found.

Value	Reason
`NotFound`	The server/role was not found.

Value	Reason
`NotFound`	The server/role was not found.

Value	Reason
`NotFound`	The server/role was not found.