diff options
Diffstat (limited to 'discord/guild.py')
| -rw-r--r-- | discord/guild.py | 70 |
1 files changed, 66 insertions, 4 deletions
diff --git a/discord/guild.py b/discord/guild.py index 209d057b..50426fd3 100644 --- a/discord/guild.py +++ b/discord/guild.py @@ -41,6 +41,7 @@ from .enums import GuildRegion, Status, ChannelType, try_enum, VerificationLevel from .mixins import Hashable from .user import User from .invite import Invite +from .iterators import AuditLogIterator BanEntry = namedtuple('BanEntry', 'reason user') @@ -921,7 +922,7 @@ class Guild(Hashable): return role @asyncio.coroutine - def kick(self, user): + def kick(self, user, *, reason=None): """|coro| Kicks a user from the guild. @@ -935,6 +936,8 @@ class Guild(Hashable): ----------- user: :class:`abc.Snowflake` The user to kick from their guild. + reason: Optional[str] + The reason the user got kicked. Raises ------- @@ -943,10 +946,10 @@ class Guild(Hashable): HTTPException Kicking failed. """ - yield from self._state.http.kick(user.id, self.id) + yield from self._state.http.kick(user.id, self.id, reason=reason) @asyncio.coroutine - def ban(self, user, *, delete_message_days=1): + def ban(self, user, *, reason=None, delete_message_days=1): """|coro| Bans a user from the guild. @@ -963,6 +966,8 @@ class Guild(Hashable): delete_message_days: int The number of days worth of messages to delete from the user in the guild. The minimum is 0 and the maximum is 7. + reason: Optional[str] + The reason the user got banned. Raises ------- @@ -971,7 +976,7 @@ class Guild(Hashable): HTTPException Banning failed. """ - yield from self._state.http.ban(user.id, self.id, delete_message_days) + yield from self._state.http.ban(user.id, self.id, delete_message_days, reason=reason) @asyncio.coroutine def unban(self, user): @@ -1017,3 +1022,60 @@ class Guild(Hashable): if state.is_bot: raise ClientException('Must not be a bot account to ack messages.') return state.http.ack_guild(self.id) + + def audit_logs(self, *, limit=100, before=None, after=None, reverse=None, user=None, action=None): + """Return an :class:`AsyncIterator` that enables receiving the guild's audit logs. + + You must have :attr:`Permissions.view_audit_log` permission to use this. + + Parameters + ----------- + limit: Optional[int] + The number of entries to retrieve. If ``None`` retrieve all entries. + before: Union[:class:`abc.Snowflake`, datetime] + Retrieve entries before this date or entry. + If a date is provided it must be a timezone-naive datetime representing UTC time. + after: Union[:class:`abc.Snowflake`, datetime] + Retrieve entries after this date or entry. + If a date is provided it must be a timezone-naive datetime representing UTC time. + reverse: bool + If set to true, return entries in oldest->newest order. If unspecified, + this defaults to ``False`` for most cases. However if passing in a + ``after`` parameter then this is set to ``True``. This avoids getting entries + out of order in the ``after`` case. + user: :class:`abc.Snowflake` + The moderator to filter entries from. + action: :class:`AuditLogAction` + The action to filter with. + + Yields + -------- + :class:`AuditLogEntry` + The audit log entry. + + Examples + ---------- + + Getting the first 100 entries: :: + + async for entry in guild.audit_logs(limit=100): + print('{0.user} did {0.action} to {0.target}'.format(entry)) + + Getting entries for a specific action: :: + + async for entry in guild.audit_logs(action=discord.AuditLogAction.ban): + print('{0.user} banned {0.target}'.format(entry)) + + Getting entries made by a specific user: :: + + entries = await guild.audit_logs(limit=None, user=guild.me).flatten() + await guild.default_channel.send('I made {} moderation actions.'.format(len(entries))) + """ + if user: + user = user.id + + if action: + action = action.value + + return AuditLogIterator(self, before=before, after=after, limit=limit, + reverse=reverse, user_id=user, action_type=action) |