async def ban(self,
victim: 'typing.Union[dt_member.Member, dt_user.User]',
*,
delete_message_days: int = 7):
"""
Bans somebody from the guild.
This can either ban a :class:`~.Member`, in which they must be in the guild.
Or this can ban a :class:`~.User`, which does not need to be in the guild.
Example for banning a member:
.. code:: python
member = guild.members[66237334693085184]
await guild.ban(member)
Example for banning a user:
.. code:: python
user = await client.get_user(66237334693085184)
await guild.ban(user)
:param victim: The :class:`.Member` or :class:`.User` object to ban.
:param delete_message_days: The number of days to delete messages.
"""
if not self.me.guild_permissions.ban_members:
raise PermissionsError("ban_members")
if isinstance(victim, dt_member.Member):
if self.owner == victim:
raise HierarchyError("Cannot ban the owner")
if victim.guild_id != self.id:
raise ValueError(
"Member must be from this guild (try `member.user` instead)"
)
if victim.top_role >= self.me.top_role:
raise HierarchyError(
"Top role is equal to or lower than victim's top role")
victim_id = victim.user.id
elif isinstance(victim, dt_user.User):
victim_id = victim.id
else:
raise TypeError("Victim must be a Member or a User")
await self._bot.http.ban_user(guild_id=self.id,
user_id=victim_id,
delete_message_days=delete_message_days)
async def remove(self, *roles: 'dt_role.Role'):
"""
Removes roles from this member.
:param roles: The roles to remove.
"""
if not self._member.guild.me.guild_permissions.manage_roles:
raise PermissionsError("manage_roles")
for _r in roles:
if _r >= self._member.guild.me.top_role:
msg = "Cannot remove role {} - it has a higher or equal position to our top role" \
.format(_r.name)
raise HierarchyError(msg)
async def _listener(before, after: Member):
if after.id != self._member.id:
return False
if not all(role not in after.roles for role in roles):
return False
return True
# Calculate the roles to keep.
to_keep = set(self._member.roles) - set(roles)
async with self._member._bot.events.wait_for_manager(
"guild_member_update", _listener):
role_ids = set([_r.id for _r in to_keep])
await self._member._bot.http.edit_member_roles(
self._member.guild_id, self._member.id, role_ids)
async def add(self, *roles: 'dt_role.Role'):
"""
Adds roles to this member.
:param roles: The :class:`.Role` objects to add to this member's role list.
"""
if not self._member.guild.me.guild_permissions.manage_roles:
raise PermissionsError("manage_roles")
# Ensure we can add all of these roles.
for _r in roles:
if _r >= self._member.guild.me.top_role:
msg = "Cannot add role {} - it has a higher or equal position to our top role" \
.format(_r.name)
raise HierarchyError(msg)
async def _listener(before, after: Member):
if after.id != self._member.id:
return False
if not all(role in after.roles for role in roles):
return False
return True
async with self._member._bot.events.wait_for_manager(
"guild_member_update", _listener):
role_ids = set([_r.id for _r in self._member.roles] +
[_r.id for _r in roles])
await self._member._bot.http.edit_member_roles(
self._member.guild_id, self._member.id, role_ids)
async def set(self, new_nickname: str) -> 'Nickname':
"""
Sets the nickname of the username.
:param new_nickname: The new nickname of this user. If None, will reset the nickname.
"""
# Ensure we don't try and set a bad nickname, which makes an empty listener.
if new_nickname == self:
return self
guild: dt_guild.Guild = self.parent.guild
me = False
if self.parent == self.parent.guild.me:
me = True
if not guild.me.guild_permissions.change_nickname:
raise PermissionsError("change_nickname")
else:
if not guild.me.guild_permissions.manage_nicknames:
raise PermissionsError("manage_nicknames")
# we can't change the owner nickname, unless we are the owner
if guild.owner == self.parent:
raise HierarchyError("Cannot change the nickname of the owner")
if self.parent.top_role >= guild.me.top_role and self.parent != guild.me:
raise HierarchyError(
"Top role is equal to or lower than victim's top role")
if new_nickname is not None and len(new_nickname) > 32:
raise ValueError("Nicknames cannot be longer than 32 characters")
async def _listener(before, after):
return after.guild == guild and after.id == self.parent.id
async with self.parent._bot.events.wait_for_manager(
"guild_member_update", _listener):
await self.parent._bot.http.change_nickname(
guild.id, new_nickname, member_id=self.parent.id, me=me)
# the wait_for means at this point the nickname has been changed
return self.parent.nickname
async def kick(self, victim: 'dt_member.Member'):
"""
Kicks somebody from the guild.
:param victim: The :class:`.Member` to kick.
"""
if not self.me.guild_permissions.kick_members:
raise PermissionsError("kick_members")
if victim.guild != self:
raise ValueError("Member must be from this guild (try `member.user` instead)")
if victim.top_role >= self.me.top_role:
raise HierarchyError("Top role is equal to or lower than victim's top role")
victim_id = victim.user.id
await self._bot.http.kick_member(self.id, victim_id)
async def change_role_positions(self,
roles: 'typing.Union[typing.Dict[dt_role.Role, int], '
'typing.List[typing.Tuple[dt_role.Role, int]]]'):
"""
Changes the positions of a mapping of roles.
:param roles: A dict or iterable of two-item tuples of new roles that is in the format of \
(role, position).
"""
if not self.me.guild_permissions.manage_roles:
raise PermissionsError("manage_roles")
if isinstance(roles, dict):
roles = roles.items()
to_send = []
for r, new_position in roles:
if new_position >= self.me.top_role.position:
raise HierarchyError("Cannot move role above our top role")
to_send.append((str(r.id), new_position))
to_send = [(str(r.id), new_position) for (r, new_position) in roles]
await self._bot.http.edit_role_positions(to_send)
