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()
@checks.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 an asynchronous initialize()
method and call
it from your setup function:
# mycog/mycog.py
from redbot.core import modlog, commands
import discord
class MyCog(commands.Cog):
async def initialize(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 cog.initialize()
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
(bot, guild, created_at, action_type, user, moderator, case_number, reason=None, until=None, channel=None, amended_by=None, modified_at=None, message=None, last_known_username=None)[source]¶ Bases:
object
A single mod log case
-
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) – The mod log channel for the guild
- bot (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
-
classmethod await
-
class
redbot.core.modlog.
CaseType
(name, default_setting, image, case_str, guild=None, **kwargs)[source]¶ Bases:
object
A single case type
-
default_setting
¶ Whether the case type should be on (if
True
) or off (ifFalse
) by defaultType: bool
-
classmethod
from_json
(name, data, **kwargs)[source]¶ Parameters: Returns: The case type object created from given data.
Return type:
-
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: bool
-
-
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_all_cases
(guild, bot)[source]¶ Gets all cases for the specified guild
Parameters: - guild (
discord.Guild
) – The guild to get the cases from - bot (Red) – The bot’s instance
Returns: A list of all cases for the guild
Return type: - guild (
-
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 from - bot (Red) – The bot’s instance
- member (
discord.Member
) – The member to get cases about - member_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.
- guild (
-
await
redbot.core.modlog.
create_case
(bot, guild, created_at, action_type, user, moderator=None, reason=None, until=None, channel=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
- action_type (str) – The type of action that was taken
- user (Union[discord.User, discord.Member]) – The user target by the action
- moderator (Optional[Union[discord.User, discord.Member]]) – 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
- channel (Optional[discord.TextChannel]) – The channel the action was taken in
-
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_all_casetypes
(guild=None)[source]¶ Get all currently registered case types
Returns: A list of case types Return type: list
-
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 successfullyReturn type: Raises: - KeyError –
- ValueError –
- AttributeError –
-
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
Raises: RuntimeError – If the modlog channel is not found.
-
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 for - channel (
discord.TextChannel
orNone
) – The channel to be set as modlog channel
Returns: True
if successfulReturn type: - guild (
-
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