Main Interface¶
This file deals with the AntiSpamHandler as it is the primary Interface for you to interact with.
Note, this is the main entrance to this entire package. As such this should be the only thing you interact with.
Punishment messages won’t be sent unless a guild sets a log channel.
This handler propagation method also returns the following class for you to use:
- class antispam.AntiSpamHandler(bot, library: antispam.enums.library.Library, *, options: Optional[antispam.dataclasses.options.Options] = None, cache: Optional[antispam.abc.cache.Cache] = None)¶
The overall handler for the DPY Anti-spam package
- __init__(bot, library: antispam.enums.library.Library, *, options: Optional[antispam.dataclasses.options.Options] = None, cache: Optional[antispam.abc.cache.Cache] = None)¶
AntiSpamHandler entry point.
- Parameters
bot – A reference to your discord bot object.
library (Library, Optional) – An enum denoting the library this AntiSpamHandler. See
antispam.enums.library.Library
for moreoptions (Options, Optional) – An instance of your custom Options the handler should use
cache (Cache, Optional) – Your choice of backend caching
- async add_guild_log_channel(log_channel: int, guild_id: int) None ¶
Registers a log channel on a guild internally
- Parameters
Notes
Not setting a log channel means it will not send any punishment messages
- async add_guild_options(guild_id: int, options: antispam.dataclasses.options.Options) None ¶
Set a guild’s options to a custom set, rather then the base level set used and defined in ASH initialization
Warning
If using/modifying
AntiSpamHandler.options
to give to this method you will also be modifying the overall options.To get an options item you can modify freely call
antispam.AntiSpamHandler.get_options()
this method will give you an instance of the current options you are free to modify however you like.Notes
This will override any current settings, if you wish to continue using existing settings and merely change some I suggest using the
get_options
method first and then giving those values back to this method with the changed arguments
- add_ignored_item(item: int, ignore_type: antispam.enums.ignored_types.IgnoreType) None ¶
Add an item to the relevant ignore list
- Parameters
item (int) – The id of the thing to ignore
ignore_type (IgnoreType) – An enum representing the item to ignore
- Raises
ValueError – item is not of type int or int convertible
Notes
This will silently ignore any attempts to add an item already added.
- async clean_cache(strict=False) None ¶
Cleans the internal cache, pruning any old/un-needed entries.
- Non Strict mode:
- Member deletion criteria:
warn_count == default
kick_count == default
duplicate_counter == default
duplicate_channel_counter_dict == default
addons dict == default
Also must have no active messages after cleaning.
- Guild deletion criteria:
options are not custom
log_channel_id is not set
addons dict == default
Also must have no members stored
- Strict mode:
- Member deletion criteria
Has no active messages
- Guild deletion criteria
Does not have custom options
log_channel_id is not set
Has no active members
- Parameters
strict (bool) – Toggles the above
Notes
This is expensive, and likely only required to be run every so often depending on how high traffic your bot is.
- async get_guild_options(guild_id: int) antispam.dataclasses.options.Options ¶
Get the options dataclass for a given guild, if the guild doesnt exist raise an exception
- Parameters
guild_id (int) – The guild to get custom options for
- Returns
The options for this guild
- Return type
- Raises
GuildNotFound – This guild does not exist
Notes
This returns a copy of the options, if you wish to change the options on the guild you should use the package methods.
- async get_options() antispam.dataclasses.options.Options ¶
Returns a safe to modify instance of this handlers options.
- Returns
The safe to use options
- Return type
- async init() None ¶
This method provides a means to initialize any async calls cleanly and without asyncio madness.
Notes
This method is guaranteed to be called before the first time propagate runs. However, it will not be run when the class is initialized.
- async static load_from_dict(bot, data: dict, library: antispam.enums.library.Library, *, raise_on_exception: bool = True, plugins: Optional[Set[Type[antispam.base_plugin.BasePlugin]]] = None)¶
Can be used as an entry point when starting your bot to reload a previous state so you don’t lose all of the previous punishment records, etc, etc
- Parameters
bot – The bot instance
data (dict) – The data to load AntiSpamHandler from
library (Library) – The
Library
you are using.raise_on_exception (bool) –
Whether or not to raise if an issue is encountered while trying to rebuild
AntiSpamHandler
from a saved stateIf you set this to False, and an exception occurs during the build process. This will return an
AntiSpamHandler
instance without any of the saved state and is equivalent to simply doingAntiSpamHandler(bot)
plugins (Set[Type[antispam.BasePlugin]]) –
A set for plugin lookups if you want to initialise plugins from an initial saved state. This should follow the format.
{ClassReference}
So for example:
1class Plugin(BasePlugin): 2 pass 3 4# Where you load ASH 5await AntiSpamHandler.load_from_dict(..., ..., plugins={Plugin}
- Returns
A new AntiSpamHandler instance where the state is equal to the provided dict
- Return type
Warning
Don’t provide data that was not given to you outside of the
save_to_dict
method unless you are maintaining the correct format.Notes
This method does not check for data conformity. Any invalid input will error unless you set
raise_on_exception
toFalse
in which case the following occursIf you set
raise_on_exception
toFalse
, and an exception occurs during the build process. This method will return anAntiSpamHandler
instance without any of the saved state and is equivalent to simply doingAntiSpamHandler(bot)
This will simply ignore the saved state of plugins that don’t have a
plugins
mapping.
- async propagate(message) Optional[Union[antispam.dataclasses.core.CorePayload, dict]] ¶
This method is the base level intake for messages, then propagating it out to the relevant guild or creating one if that is required
For what this returns please see the top of this page.
- Parameters
message (Union[discord.Message, hikari.messages.Message]) – The message that needs to be propagated out
- Returns
A dictionary of useful information about the Member in question
- Return type
- register_plugin(plugin, force_overwrite=False) None ¶
Registers a plugin for usage for within the package
- Parameters
plugin – The plugin to register
force_overwrite (bool) –
Whether to overwrite any duplicates currently stored.
Think of this as calling
unregister_extension
and then proceeding to call this method.
- Raises
PluginError – A plugin with this name is already loaded
Notes
This must be a class instance, and must subclass
BasePlugin
- async remove_guild_log_channel(guild_id: int) None ¶
Removes a registered guild log channel
- Parameters
guild_id (int) – The guild to remove it from
Notes
Silently ignores guilds which don’t exist
- async remove_guild_options(guild_id: int) None ¶
Reset a guilds options to the ASH options
- Parameters
guild_id (int) – The guild to reset
Notes
This method will silently ignore guilds that do not exist, as it is considered to have ‘removed’ custom options due to how Guild’s are created
- remove_ignored_item(item: int, ignore_type: antispam.enums.ignored_types.IgnoreType) None ¶
Remove an item from the relevant ignore list
- Parameters
item (int) – The id of the thing to un-ignore
ignore_type (IgnoreType) – An enum representing the item to ignore
- Raises
ValueError – item is not of type int or int convertible
Notes
This will silently ignore any attempts to remove an item not ignored.
- async reset_member_count(member_id: int, guild_id: int, reset_type: antispam.enums.reset_type.ResetType) None ¶
Reset an internal counter attached to a User object
- Parameters
Notes
Silently ignores if the User or Guild does not exist. This is because in the packages mind, the counts are ‘reset’ since the default value is the reset value.
- async save_to_dict() dict ¶
Creates a ‘save point’ of the current state for this handler which can then be used to restore state at a later date
- Returns
The saved state in a dictionary form. You can give this to
load_from_dict
to reload the saved state- Return type
Notes
For most expected use-case’s the returned
Messages
will be outdated, however, they are included as it is technically part of the current state.Note that is method is expensive in both time and memory. It has to iterate over every single stored class instance within the library and store it in a dictionary.
For bigger bots, it is likely better you create this process yourself using generators in order to reduce overhead.
This will return saved Plugin states where the Plugin has implemented the
save_to_dict
method.Warning
Due to the already expensive nature of this method, all returned option dictionaries are not deepcopied. Modifying them during runtime will cause this library to begin using that modified copy.
- set_cache(cache: antispam.abc.cache.Cache) None ¶
Change the AntiSpamHandler internal cache to be the one provided.
1bot.handler = AntiSpamHandler(bot) 2cache = MongoCache(bot.handler, "Connection_url") 3bot.handler.set_cache(cache)
- Parameters
cache (Cache) – The cache to change it to.
- Raises
ValueError – The provided cache was not of the expected type.
- unregister_plugin(plugin_name: str) None ¶
Used to unregister or remove a plugin that is currently loaded into AntiSpamHandler
- Parameters
plugin_name (str) – The name of the class you want to unregister
- Raises
PluginError – This extension isn’t loaded
- async visualize(content: str, message, warn_count: int = 1, kick_count: int = 2)¶
Wraps around
antispam.abc.Lib.visualizer()
as a convenience