mirror of
https://github.com/Cog-Creators/Red-DiscordBot.git
synced 2025-11-06 03:08:55 -05:00
[Docs] Warnings Cog Guide (#4920)
* Initial commit * labeler and index * change parameter names and labeler * fix typo * docstrings, quotes and improved names * merge conflict affect fixes * remove aliases * get from v3/develop * update var names * fixes * improve grammar * black
This commit is contained in:
Kreusada
GitHub
parent
db86de3a7a
commit
b630e71d08
3
.github/labeler.yml
vendored
3
.github/labeler.yml
vendored
@ -177,4 +177,7 @@
|
||||
# Docs
|
||||
- docs/framework_utils.rst
|
||||
"Category: Warnings":
|
||||
# Source
|
||||
- redbot/cogs/warnings/*
|
||||
# Docs
|
||||
- docs/cog_guides/warnings.rst
|
||||
|
||||
403
docs/cog_guides/warnings.rst
Normal file
403
docs/cog_guides/warnings.rst
Normal file
@ -0,0 +1,403 @@
|
||||
.. _warnings:
|
||||
|
||||
========
|
||||
Warnings
|
||||
========
|
||||
|
||||
This is the cog guide for the warnings cog. You will
|
||||
find detailed docs about usage and commands.
|
||||
|
||||
``[p]`` is considered as your prefix.
|
||||
|
||||
.. note:: To use this cog, load it by typing this::
|
||||
|
||||
[p]load warnings
|
||||
|
||||
.. _warnings-usage:
|
||||
|
||||
-----
|
||||
Usage
|
||||
-----
|
||||
|
||||
Warn misbehaving users and take automated actions.
|
||||
|
||||
|
||||
.. _warnings-commands:
|
||||
|
||||
--------
|
||||
Commands
|
||||
--------
|
||||
|
||||
.. _warnings-command-actionlist:
|
||||
|
||||
^^^^^^^^^^
|
||||
actionlist
|
||||
^^^^^^^^^^
|
||||
|
||||
.. note:: |admin-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]actionlist
|
||||
|
||||
**Description**
|
||||
|
||||
List all configured automated actions for Warnings.
|
||||
|
||||
.. _warnings-command-mywarnings:
|
||||
|
||||
^^^^^^^^^^
|
||||
mywarnings
|
||||
^^^^^^^^^^
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]mywarnings
|
||||
|
||||
**Description**
|
||||
|
||||
List warnings for yourself.
|
||||
|
||||
.. _warnings-command-reasonlist:
|
||||
|
||||
^^^^^^^^^^
|
||||
reasonlist
|
||||
^^^^^^^^^^
|
||||
|
||||
.. note:: |admin-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]reasonlist
|
||||
|
||||
**Description**
|
||||
|
||||
List all configured reasons for Warnings.
|
||||
|
||||
.. _warnings-command-unwarn:
|
||||
|
||||
^^^^^^
|
||||
unwarn
|
||||
^^^^^^
|
||||
|
||||
.. note:: |admin-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]unwarn <member> <warn_id> [reason]
|
||||
|
||||
**Description**
|
||||
|
||||
Remove a warning from a member.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<member>``: The member to remove the warning from. |member-input-quotes|
|
||||
* ``<warn_id>``: The warning ID to remove from the member.
|
||||
* ``[reason]``: The reason for unwarning this member.
|
||||
|
||||
.. _warnings-command-warn:
|
||||
|
||||
^^^^
|
||||
warn
|
||||
^^^^
|
||||
|
||||
.. note:: |admin-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warn <member> [points=1] <reason>
|
||||
|
||||
**Description**
|
||||
|
||||
Warn the user for the specified reason.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<member>``: The member to warn. |member-input-quotes|
|
||||
* ``[points]``: The number of points the warning should be for. If no number is supplied, 1 point will be given. Pre-set warnings disregard this.
|
||||
* ``<reason>``: The reason for the warning. This can be a registered reason, or a custom reason if ``[p]warningset allowcustomreasons`` is set.
|
||||
|
||||
.. _warnings-command-warnaction:
|
||||
|
||||
^^^^^^^^^^
|
||||
warnaction
|
||||
^^^^^^^^^^
|
||||
|
||||
.. note:: |guildowner-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnaction
|
||||
|
||||
**Description**
|
||||
|
||||
Manage automated actions for Warnings.
|
||||
|
||||
Actions are essentially command macros. Any command can be run
|
||||
when the action is initially triggered, and/or when the action
|
||||
is lifted.
|
||||
|
||||
Actions must be given a name and a points threshold. When a
|
||||
user is warned enough so that their points go over this
|
||||
threshold, the action will be executed.
|
||||
|
||||
.. _warnings-command-warnaction-add:
|
||||
|
||||
""""""""""""""
|
||||
warnaction add
|
||||
""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnaction add <name> <points>
|
||||
|
||||
**Description**
|
||||
|
||||
Create an automated action.
|
||||
|
||||
Duplicate action names are not allowed.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<name>``: The name of the action.
|
||||
* ``<points>``: The number of points for this action.
|
||||
|
||||
.. _warnings-command-warnaction-delete:
|
||||
|
||||
"""""""""""""""""
|
||||
warnaction delete
|
||||
"""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnaction delete <action_name>
|
||||
|
||||
**Description**
|
||||
|
||||
Delete the action with the specified name.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<action_name>``: The name of the action to delete.
|
||||
|
||||
.. _warnings-command-warnings:
|
||||
|
||||
^^^^^^^^
|
||||
warnings
|
||||
^^^^^^^^
|
||||
|
||||
.. note:: |admin-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnings <member>
|
||||
|
||||
**Description**
|
||||
|
||||
List the warnings for the specified member.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<member>``: The member to get the warnings for. |member-input|
|
||||
|
||||
.. _warnings-command-warningset:
|
||||
|
||||
^^^^^^^^^^
|
||||
warningset
|
||||
^^^^^^^^^^
|
||||
|
||||
.. note:: |guildowner-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warningset
|
||||
|
||||
**Description**
|
||||
|
||||
Manage settings for Warnings.
|
||||
|
||||
.. _warnings-command-warningset-allowcustomreasons:
|
||||
|
||||
"""""""""""""""""""""""""""""
|
||||
warningset allowcustomreasons
|
||||
"""""""""""""""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warningset allowcustomreasons <true_or_false>
|
||||
|
||||
**Description**
|
||||
|
||||
Enable or disable custom reasons for a warning.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<true_or_false>``: |bool-input|
|
||||
|
||||
.. _warnings-command-warningset-senddm:
|
||||
|
||||
"""""""""""""""""
|
||||
warningset senddm
|
||||
"""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warningset senddm <true_or_false>
|
||||
|
||||
**Description**
|
||||
|
||||
Set whether warnings should be sent to users in DMs.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<true_or_false>``: |bool-input|
|
||||
|
||||
.. _warnings-command-warningset-showmoderator:
|
||||
|
||||
""""""""""""""""""""""""
|
||||
warningset showmoderator
|
||||
""""""""""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warningset showmoderator <true_or_false>
|
||||
|
||||
**Description**
|
||||
|
||||
Decide whether the name of the moderator warning a user should be included in the DM to that user.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<true_or_false>``: |bool-input|
|
||||
|
||||
.. _warnings-command-warningset-usewarnchannel:
|
||||
|
||||
"""""""""""""""""""""""""
|
||||
warningset usewarnchannel
|
||||
"""""""""""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warningset usewarnchannel <true_or_false>
|
||||
|
||||
**Description**
|
||||
|
||||
Set if warnings should be sent to a channel set with ``[p]warningset warnchannel``.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<true_or_false>``: |bool-input|
|
||||
|
||||
.. _warnings-command-warningset-warnchannel:
|
||||
|
||||
""""""""""""""""""""""
|
||||
warningset warnchannel
|
||||
""""""""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warningset warnchannel [channel]
|
||||
|
||||
**Description**
|
||||
|
||||
Set the channel where warnings should be sent to.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``[channel]``: |channel-input| Leave empty to use the channel ``[p]warn`` command was called in.
|
||||
|
||||
.. _warnings-command-warnreason:
|
||||
|
||||
^^^^^^^^^^
|
||||
warnreason
|
||||
^^^^^^^^^^
|
||||
|
||||
.. note:: |guildowner-lock|
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnreason
|
||||
|
||||
**Description**
|
||||
|
||||
Manage warning reasons.
|
||||
|
||||
Reasons must be given a name, description and points value. The
|
||||
name of the reason must be given when a user is warned.
|
||||
|
||||
.. _warnings-command-warnreason-create:
|
||||
|
||||
"""""""""""""""""
|
||||
warnreason create
|
||||
"""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnreason create <name> <points> <description>
|
||||
|
||||
.. tip:: Alias: ``warnreason add``
|
||||
|
||||
**Description**
|
||||
|
||||
Create a warning reason.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<name>``: The name for the new reason.
|
||||
* ``<points>``: The number of points with the new reason.
|
||||
* ``<description>``: The description of the new warn reason.
|
||||
|
||||
.. _warnings-command-warnreason-delete:
|
||||
|
||||
"""""""""""""""""
|
||||
warnreason delete
|
||||
"""""""""""""""""
|
||||
|
||||
**Syntax**
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
[p]warnreason delete <reason_name>
|
||||
|
||||
**Description**
|
||||
|
||||
Delete a warning reason.
|
||||
|
||||
**Arguments**
|
||||
|
||||
* ``<reason_name>``: The name of the reason to delete.
|
||||
@ -52,6 +52,7 @@ Welcome to Red - Discord Bot's documentation!
|
||||
cog_guides/reports
|
||||
cog_guides/streams
|
||||
cog_guides/trivia
|
||||
cog_guides/warnings
|
||||
red_core_data_statement
|
||||
|
||||
.. toctree::
|
||||
|
||||
@ -156,7 +156,6 @@ class Warnings(commands.Cog):
|
||||
@commands.guild_only()
|
||||
async def warnchannel(self, ctx: commands.Context, channel: discord.TextChannel = None):
|
||||
"""Set the channel where warnings should be sent to.
|
||||
|
||||
Leave empty to use the channel `[p]warn` command was called in.
|
||||
"""
|
||||
guild = ctx.guild
|
||||
@ -192,11 +191,9 @@ class Warnings(commands.Cog):
|
||||
@checks.guildowner_or_permissions(administrator=True)
|
||||
async def warnaction(self, ctx: commands.Context):
|
||||
"""Manage automated actions for Warnings.
|
||||
|
||||
Actions are essentially command macros. Any command can be run
|
||||
when the action is initially triggered, and/or when the action
|
||||
is lifted.
|
||||
|
||||
Actions must be given a name and a points threshold. When a
|
||||
user is warned enough so that their points go over this
|
||||
threshold, the action will be executed.
|
||||
@ -207,7 +204,6 @@ class Warnings(commands.Cog):
|
||||
@commands.guild_only()
|
||||
async def action_add(self, ctx: commands.Context, name: str, points: int):
|
||||
"""Create an automated action.
|
||||
|
||||
Duplicate action names are not allowed.
|
||||
"""
|
||||
guild = ctx.guild
|
||||
@ -259,7 +255,6 @@ class Warnings(commands.Cog):
|
||||
@checks.guildowner_or_permissions(administrator=True)
|
||||
async def warnreason(self, ctx: commands.Context):
|
||||
"""Manage warning reasons.
|
||||
|
||||
Reasons must be given a name, description and points value. The
|
||||
name of the reason must be given when a user is warned.
|
||||
"""
|
||||
@ -368,26 +363,25 @@ class Warnings(commands.Cog):
|
||||
async def warn(
|
||||
self,
|
||||
ctx: commands.Context,
|
||||
user: discord.Member,
|
||||
member: discord.Member,
|
||||
points: UserInputOptional[int] = 1,
|
||||
*,
|
||||
reason: str,
|
||||
):
|
||||
"""Warn the user for the specified reason.
|
||||
|
||||
`<points>` number of points the warning should be for. If no number is supplied
|
||||
1 point will be given. Pre-set warnings disregard this.
|
||||
`<reason>` can be a registered reason if it exists or a custom one
|
||||
is created by default.
|
||||
`<reason>` is reason for the warning. This can be a registered reason,
|
||||
or a custom reason if ``[p]warningset allowcustomreasons`` is set.
|
||||
"""
|
||||
guild = ctx.guild
|
||||
if user == ctx.author:
|
||||
if member == ctx.author:
|
||||
return await ctx.send(_("You cannot warn yourself."))
|
||||
if user.bot:
|
||||
if member.bot:
|
||||
return await ctx.send(_("You cannot warn other bots."))
|
||||
if user == ctx.guild.owner:
|
||||
if member == ctx.guild.owner:
|
||||
return await ctx.send(_("You cannot warn the server owner."))
|
||||
if user.top_role >= ctx.author.top_role and ctx.author != ctx.guild.owner:
|
||||
if member.top_role >= ctx.author.top_role and ctx.author != ctx.guild.owner:
|
||||
return await ctx.send(
|
||||
_(
|
||||
"The person you're trying to warn is equal or higher than you in the discord hierarchy, you cannot warn them."
|
||||
@ -421,7 +415,7 @@ class Warnings(commands.Cog):
|
||||
return await ctx.send(msg)
|
||||
if reason_type is None:
|
||||
return
|
||||
member_settings = self.config.member(user)
|
||||
member_settings = self.config.member(member)
|
||||
current_point_count = await member_settings.total_points()
|
||||
warning_to_add = {
|
||||
str(ctx.message.id): {
|
||||
@ -443,7 +437,7 @@ class Warnings(commands.Cog):
|
||||
)
|
||||
em.add_field(name=_("Points"), value=str(reason_type["points"]))
|
||||
try:
|
||||
await user.send(
|
||||
await member.send(
|
||||
_("You have received a warning in {guild_name}.").format(
|
||||
guild_name=ctx.guild.name
|
||||
),
|
||||
@ -457,13 +451,13 @@ class Warnings(commands.Cog):
|
||||
_(
|
||||
"A warning for {user} has been issued,"
|
||||
" but I wasn't able to send them a warn message."
|
||||
).format(user=user.mention)
|
||||
).format(user=member.mention)
|
||||
)
|
||||
async with member_settings.warnings() as user_warnings:
|
||||
user_warnings.update(warning_to_add)
|
||||
current_point_count += reason_type["points"]
|
||||
await member_settings.total_points.set(current_point_count)
|
||||
await warning_points_add_check(self.config, ctx, user, current_point_count)
|
||||
await warning_points_add_check(self.config, ctx, member, current_point_count)
|
||||
|
||||
toggle_channel = guild_settings["toggle_channel"]
|
||||
if toggle_channel:
|
||||
@ -480,7 +474,7 @@ class Warnings(commands.Cog):
|
||||
if warn_channel.permissions_for(guild.me).send_messages:
|
||||
with contextlib.suppress(discord.HTTPException):
|
||||
await warn_channel.send(
|
||||
_("{user} has been warned.").format(user=user.mention),
|
||||
_("{user} has been warned.").format(user=member.mention),
|
||||
embed=em,
|
||||
)
|
||||
|
||||
@ -489,7 +483,7 @@ class Warnings(commands.Cog):
|
||||
await ctx.tick()
|
||||
else:
|
||||
await ctx.send(
|
||||
_("{user} has been warned.").format(user=user.mention), embed=em
|
||||
_("{user} has been warned.").format(user=member.mention), embed=em
|
||||
)
|
||||
else:
|
||||
if not dm_failed:
|
||||
@ -501,7 +495,7 @@ class Warnings(commands.Cog):
|
||||
description=reason_type["description"], points=reason_type["points"]
|
||||
),
|
||||
prefix=ctx.clean_prefix,
|
||||
user=user.id,
|
||||
user=member.id,
|
||||
message=ctx.message.id,
|
||||
)
|
||||
await modlog.create_case(
|
||||
@ -509,7 +503,7 @@ class Warnings(commands.Cog):
|
||||
ctx.guild,
|
||||
ctx.message.created_at.replace(tzinfo=timezone.utc),
|
||||
"warning",
|
||||
user,
|
||||
member,
|
||||
ctx.message.author,
|
||||
reason_msg,
|
||||
until=None,
|
||||
@ -519,18 +513,18 @@ class Warnings(commands.Cog):
|
||||
@commands.command()
|
||||
@commands.guild_only()
|
||||
@checks.admin()
|
||||
async def warnings(self, ctx: commands.Context, user: Union[discord.Member, int]):
|
||||
async def warnings(self, ctx: commands.Context, member: Union[discord.Member, int]):
|
||||
"""List the warnings for the specified user."""
|
||||
|
||||
try:
|
||||
userid: int = user.id
|
||||
userid: int = member.id
|
||||
except AttributeError:
|
||||
userid: int = user
|
||||
user = ctx.guild.get_member(userid)
|
||||
user = user or namedtuple("Member", "id guild")(userid, ctx.guild)
|
||||
userid: int = member
|
||||
member = ctx.guild.get_member(userid)
|
||||
member = member or namedtuple("Member", "id guild")(userid, ctx.guild)
|
||||
|
||||
msg = ""
|
||||
member_settings = self.config.member(user)
|
||||
member_settings = self.config.member(member)
|
||||
async with member_settings.warnings() as user_warnings:
|
||||
if not user_warnings.keys(): # no warnings for the user
|
||||
await ctx.send(_("That user has no warnings!"))
|
||||
@ -554,7 +548,7 @@ class Warnings(commands.Cog):
|
||||
await ctx.send_interactive(
|
||||
pagify(msg, shorten_by=58),
|
||||
box_lang=_("Warnings for {user}").format(
|
||||
user=user if isinstance(user, discord.Member) else user.id
|
||||
user=member if isinstance(member, discord.Member) else member.id
|
||||
),
|
||||
)
|
||||
|
||||
@ -598,7 +592,7 @@ class Warnings(commands.Cog):
|
||||
async def unwarn(
|
||||
self,
|
||||
ctx: commands.Context,
|
||||
user: Union[discord.Member, int],
|
||||
member: Union[discord.Member, int],
|
||||
warn_id: str,
|
||||
*,
|
||||
reason: str = None,
|
||||
@ -608,10 +602,10 @@ class Warnings(commands.Cog):
|
||||
guild = ctx.guild
|
||||
|
||||
try:
|
||||
user_id = user.id
|
||||
member = user
|
||||
user_id = member.id
|
||||
member = member
|
||||
except AttributeError:
|
||||
user_id = user
|
||||
user_id = member
|
||||
member = guild.get_member(user_id)
|
||||
member = member or namedtuple("Member", "guild id")(guild, user_id)
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user