Custom/No Punishment Modes¶
This package recognizes end developers may wish
to punish users outside of how this package does it.
Due to this, you can use the AntiSpamTracker
to
track users yourself and work with punishments of your
choice!
-
class
antispam.ext.
AntiSpamTracker
(anti_spam_handler: antispam.anti_spam_handler.AntiSpamHandler, spam_amount_to_punish, valid_timestamp_interval=None)¶ A class devoted to people who want to handle punishments themselves.
This class wraps a few things, and handles the logic of ensuring everything exists (or doesnt) among other things such as untracking users after the valid storage interval expires
In order to use this in your code, you can either:
- Subclass this class and override the
do_punishment
method and then use it that way to keep it clean - Initialize this class and simply use the bool
is_spamming()
and do punishments based off that - Initialize this class and simply use
get_user_count()
to get the number of times the user should be punished and do your own logic
This mainly just depends on how granular you want to be within your code base.
The way it works, is everytime you call
propagate
you simply pass the returned data into update_cache and it will update said Members cache if AntiSpamHandler thinks that they should be punished. Now, you setspam_amount_to_punish
when creating an instance of this class and that is used to check if YOU think they should be punished, and what punishment to give when they hit that cap.Basically:
propagate
->update_cache
, if the User should be punished we increment internal counteris_spamming
-> Checks if the User’s internal counter meetsspam_amount_to_punish
and returns a boolNotes
This Class recognizes that individual guilds can have different options and will attempt to work with said options to the best of its ability. This is lazily conducted however, so if you wish to use any of the methods listed below please call them on this class rather then on your base AntiSpamHandler. (They will also update the AntiSpamHandler dont worry)
add_custom_guild_options
remove_custom_guild_options
-
__init__
(anti_spam_handler: antispam.anti_spam_handler.AntiSpamHandler, spam_amount_to_punish, valid_timestamp_interval=None) → None¶ Initialize this class and get it ready for usage.
Parameters: - anti_spam_handler (AntiSpamHandler) – Your AntiSpamHandler instance
- spam_amount_to_punish (int) –
A number denoting the minimum value required per user in order trip is_spamming
NOTE this is in milliseconds
- valid_timestamp_interval (int) – How long a timestamp should remain ‘valid’ for.
Defaults to
AntiSpamHandler.options.get("message_interval")
Raises: TypeError
– Invalid Arg TypeValueError
– Invalid Arg Type
-
add_custom_guild_options
(guild_id: int, **kwargs)¶ To see how to use this, refer to
antispam.AntiSpamHandler.AntiSpamHandler.add_custom_guild_options
See also
antispam.AntiSpamHandler.AntiSpamHandler.add_custom_guild_options()
- The method that this calls under the hood
Notes
Not unit-tested, I just assume it works since
add_custom_guild_options
is unit-tested. If this doesnt work as intended, please open an issue.
-
clean_cache
() → None¶ Cleans the entire internal cache removing any empty users, and empty guilds by extension
Notes
This is more part of the Optimising Package Usage section, run this once a week/day or somethin depending on how big your bot is. I haven’t profiled things.
-
do_punishment
(message: discord.message.Message, *args, **kwargs) → None¶ This only exists for if the user wishes to subclass this class and implement there own logic for punishments here.
Parameters: message (discord.Message) – The message to extract the guild and user from Notes
This does nothing unless you subclass and implement it yourself.
-
get_user_count
(message: discord.message.Message) → int¶ Returns how many messages that are still ‘valid’ (counted as spam) a certain user has
Parameters: message (discord.Message) – The message from which to extract user Returns: How many times this user has sent a message that has been marked as ‘punishment worthy’ by AntiSpamHandler within the valid interval time period Return type: int Raises: UserNotFound
– The User for themessage
could not be found
-
is_spamming
(message: discord.message.Message) → bool¶ Given a message, deduce and return if a user is classed as ‘spamming’ or not based on
punish_min_amount
Parameters: message (discord.Messsage) – The message to extract guild and user from Returns: True if the User is spamming else False Return type: bool
-
static
load_from_dict
(anti_spam_handler: antispam.anti_spam_handler.AntiSpamHandler, data: dict)¶ Given a valid input (from ``save_to_dict``) build and return a valid AntiSpamTracker state that matches the previously saved state.
Parameters: - anti_spam_handler (AntiSpamHandler) – The AntiSpamHandler instance to attach this to
- data (dict) – The state to restore from
Returns: A valid AntiSpamTracker instance restored from the state provided to this method
Return type:
-
propagate
(message: discord.message.Message, data: Optional[dict] = None) → dict¶ Overwrite the base extension to call
update_cache
internally so it can be used as an extension
-
remove_custom_guild_options
(guild_id: int)¶ To see how to use this, refer to
antispam.AntiSpamHandler.AntiSpamHandler.remove_custom_guild_options
See also
antispam.AntiSpamHandler.AntiSpamHandler.remove_custom_guild_options()
- The method that this calls under the hood
Notes
Not unit-tested, I just assume it works since
add_custom_guild_options
is unit-tested. If this doesnt work as intended, please open an issue.
-
remove_outdated_timestamps
(guild_id, user_id)¶ This logic works around checking the current time vs a messages creation time. If the message is older by the config amount it can be cleaned up
Generally not called by the end user
Parameters: - guild_id (int) – The guild’s id to clean
- user_id (int) – The id of the user to clean up
-
remove_punishments
(message: discord.message.Message)¶ After you punish someone, call this method to ‘clean up’ there punishments.
Parameters: message (discord.Message) – The message to extract user from Raises: TypeError
– Invalid argNotes
If the user can’t be found in cache, it executes the same as if the user could be found in cache for what should be somewhat obvious reasons. (They shouldn’t exist after this method finishes)
-
save_to_dict
() → dict¶ Similar to
AntiSpamHandler.save_to_dict
this method returns a dictionary which can be used to rebuild the state of the classReturns: The dict to rebuild state from Return type: dict
-
update_cache
(message: discord.message.Message, data: dict) → None¶ Takes the data returned from propagate and updates this Class’s internal cache
Parameters: - message (discord.Message) – The message related to data’s propagation
- data (dict) – The data returned from propagate
- Subclass this class and override the