Mod log
Mod log has now been separated from Mod for V3.
Basic Usage
from redbot.core import commands, modlog
import discord
class MyCog(commands.Cog):
@commands.command()
@commands.admin_or_permissions(ban_members=True)
async def ban(self, ctx, user: discord.Member, reason: str = None):
await ctx.guild.ban(user)
case = await modlog.create_case(
ctx.bot, ctx.guild, ctx.message.created_at, action_type="ban",
user=user, moderator=ctx.author, reason=reason
)
await ctx.send("Done. It was about time.")
Registering Case types
To register case types, use a special cog_load()
method which is called when you add a cog:
# mycog/mycog.py
from redbot.core import modlog, commands
import discord
class MyCog(commands.Cog):
async def cog_load(self):
await self.register_casetypes()
@staticmethod
async def register_casetypes():
# Registering a single casetype
ban_case = {
"name": "ban",
"default_setting": True,
"image": "\N{HAMMER}",
"case_str": "Ban",
}
try:
await modlog.register_casetype(**ban_case)
except RuntimeError:
pass
# Registering multiple casetypes
new_types = [
{
"name": "hackban",
"default_setting": True,
"image": "\N{BUST IN SILHOUETTE}\N{HAMMER}",
"case_str": "Hackban",
},
{
"name": "kick",
"default_setting": True,
"image": "\N{WOMANS BOOTS}",
"case_str": "Kick",
}
]
await modlog.register_casetypes(new_types)
# mycog/__init__.py
from .mycog import MyCog
async def setup(bot):
cog = MyCog()
await bot.add_cog(cog)
Important
Image should be the emoji you want to represent your case type with.
API Reference
Mod log
- class redbot.core.modlog.Case[source]
Bases:
object
A single mod log case
This class should ONLY be instantiated by the modlog itself.
- guild
The guild the action was taken in.
- Type:
- user
The user target by the action.
Note
This attribute will be of type
int
if the Discord user can no longer be found.- Type:
Union[discord.abc.User, int]
- moderator
The moderator who took the action.
None
if the moderator is unknown.Note
This attribute will be of type
int
if the Discord user can no longer be found.- Type:
Optional[Union[discord.abc.User, int]]
- until
The UNIX time the action is in effect until.
None
if the action is permanent.- Type:
Optional[int]
- channel
The channel the action was taken in.
None
if the action was not related to a channel.Note
This attribute will be of type
int
if the channel seems to no longer exist.- Type:
Optional[Union[discord.abc.GuildChannel, discord.Thread, int]]
- parent_channel_id
The parent channel ID of the thread in
channel
.None
if the action was not done in a thread.- Type:
Optional[int]
- amended_by
The moderator who made the last change to the case.
None
if the case was never edited.Note
This attribute will be of type
int
if the Discord user can no longer be found.- Type:
Optional[Union[discord.abc.User, int]]
- modified_at
The UNIX time of the last change to the case.
None
if the case was never edited.- Type:
Optional[float]
- message
The message created by Modlog for this case. Instance of
discord.Message
if the Case object was returned frommodlog.create_case()
, otherwisediscord.PartialMessage
.None
if we know that the message no longer exists (note: it might not exist regardless of whether this attribute isNone
) or if it has never been created.- Type:
Optional[Union[discord.PartialMessage, discord.Message]]
- last_known_username
The last known username of the user.
None
if the username of the user was never saved or if their data had to be anonymized.- Type:
Optional[str]
- classmethod await from_json(mod_channel, bot, case_number, data, **kwargs)[source]
Get a Case object from the provided information
- Parameters:
mod_channel (
discord.TextChannel
ordiscord.VoiceChannel
,discord.StageChannel
) – The mod log channel for the guildbot (Red) – The bot’s instance. Needed to get the target user
case_number (int) – The case’s number.
data (dict) – The JSON representation of the case to be gotten
**kwargs – Extra attributes for the Case instance which override values in the data dict. These should be complete objects and not IDs, where possible.
- Returns:
The case object for the requested case
- Return type:
- Raises:
discord.NotFound – The user the case is for no longer exists
discord.Forbidden – Cannot read message history to fetch the original message.
discord.HTTPException – A generic API issue
- class redbot.core.modlog.CaseType(name, default_setting, image, case_str, guild=None, **kwargs)[source]
Bases:
object
A single case type
This class should ONLY be instantiated by the modlog itself.
- await is_enabled()[source]
Determines if the case is enabled. If the guild is not set, this will always return False
- Returns:
True if the guild is set and the casetype is enabled for the guild
False if the guild is not set or if the guild is set and the type is disabled
- Return type:
- await redbot.core.modlog.create_case(bot, guild, created_at, action_type, user, moderator=None, reason=None, until=None, channel=None, last_known_username=None)[source]
Creates a new case.
This fires an event
on_modlog_case_create
- Parameters:
bot (Red) – The bot object
guild (discord.Guild) – The guild the action was taken in
created_at (datetime) – The time the action occurred at. If naive
datetime
object is passed, it’s treated as a local time (similarly to how Python treats naivedatetime
objects).action_type (str) – The type of action that was taken
user (Union[discord.Object, discord.abc.User, int]) – The user target by the action
moderator (Optional[Union[discord.Object, discord.abc.User, int]]) – The moderator who took the action
reason (Optional[str]) – The reason the action was taken
until (Optional[datetime]) – The time the action is in effect until. If naive
datetime
object is passed, it’s treated as a local time (similarly to how Python treats naivedatetime
objects).channel (Optional[Union[discord.abc.GuildChannel, discord.Thread]]) – The channel the action was taken in
last_known_username (Optional[str]) – The last known username of the user Note: This is ignored if a Member or User object is provided in the user field
- Raises:
ValueError – If the action type is not a valid action type.
RuntimeError – If user is the bot itself.
TypeError – If
channel
is of typediscord.PartialMessageable
.
- await redbot.core.modlog.get_all_cases(guild, bot)[source]
Gets all cases for the specified guild
- Parameters:
guild (
discord.Guild
) – The guild to get the cases frombot (Red) – The bot’s instance
- Returns:
A list of all cases for the guild
- Return type:
- await redbot.core.modlog.get_all_casetypes(guild=None)[source]
Get all currently registered case types
- Returns:
A list of case types
- Return type:
- await redbot.core.modlog.get_case(case_number, guild, bot)[source]
Gets the case with the associated case number
- Parameters:
case_number (int) – The case number for the case to get
guild (discord.Guild) – The guild to get the case from
bot (Red) – The bot’s instance
- Returns:
The case associated with the case number
- Return type:
- Raises:
RuntimeError – If there is no case for the specified number
- await redbot.core.modlog.get_cases_for_member(guild, bot, *, member=None, member_id=None)[source]
Gets all cases for the specified member or member id in a guild.
- Parameters:
guild (
discord.Guild
) – The guild to get the cases frombot (Red) – The bot’s instance
member (
discord.Member
) – The member to get cases aboutmember_id (int) – The id of the member to get cases about
- Returns:
A list of all matching cases.
- Return type:
- Raises:
ValueError – If at least one of member or member_id is not provided
discord.Forbidden – The bot does not have permission to fetch the modlog message which was sent.
discord.HTTPException – Fetching the user failed.
- await redbot.core.modlog.get_casetype(name, guild=None)[source]
Gets the case type
- Parameters:
name (str) – The name of the case type to get
guild (Optional[discord.Guild]) – If provided, sets the case type’s guild attribute to this guild
- Returns:
Case type with provided name. If such case type doesn’t exist this will be
None
.- Return type:
Optional[CaseType]
- await redbot.core.modlog.get_latest_case(guild, bot)[source]
Get the latest case for the specified guild.
- Parameters:
guild (discord.Guild) – The guild to get the latest case for.
bot (Red) – The bot object.
- Returns:
The latest case object.
None
if it the guild has no cases.- Return type:
Optional[Case]
- await redbot.core.modlog.get_modlog_channel(guild)[source]
Get the current modlog channel.
- Parameters:
guild (
discord.Guild
) – The guild to get the modlog channel for.- Returns:
The channel object representing the modlog channel.
- Return type:
discord.TextChannel
,discord.VoiceChannel
, ordiscord.StageChannel
- Raises:
RuntimeError – If the modlog channel is not found.
- await redbot.core.modlog.register_casetype(name, default_setting, image, case_str)[source]
Registers a case type. If the case type exists and there are differences between the values passed and what is stored already, the case type will be updated with the new values
- Parameters:
- Returns:
The case type that was registered
- Return type:
- Raises:
RuntimeError – If the case type is already registered
TypeError – If a parameter is missing
ValueError – If a parameter’s value is not valid
- await redbot.core.modlog.register_casetypes(new_types)[source]
Registers multiple case types
- Parameters:
new_types (list) – The new types to register
- Returns:
True
if all were registered successfully- Return type:
- Raises:
KeyError –
See also
- await redbot.core.modlog.reset_cases(guild)[source]
Wipes all modlog cases for the specified guild.
- Parameters:
guild (
discord.Guild
) – The guild to reset cases for
- await redbot.core.modlog.set_modlog_channel(guild, channel)[source]
Changes the modlog channel
- Parameters:
guild (
discord.Guild
) – The guild to set a mod log channel forchannel (
discord.TextChannel
,discord.VoiceChannel
,discord.StageChannel
, orNone
) – The channel to be set as modlog channel
- Returns:
True
if successful- Return type: