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:

antispam.CorePayload

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 more
options (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

log_channel (int) – The channel id you wish to use for logging
guild_id (int) – The id of the guild to store this on

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: Options
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: Options

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 state

If 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 doing AntiSpamHandler(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

AntiSpamHandler

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 to False in which case the following occurs

If you set raise_on_exception to False, and an exception occurs during the build process. This method will return an AntiSpamHandler instance without any of the saved state and is equivalent to simply doing AntiSpamHandler(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: dict

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

member_id (int) – The user to reset
guild_id (int) – The guild they are attached to
reset_type (ResetType) – An enum representing the counter to reset

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: dict

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.

bot.handler = AntiSpamHandler(bot)
cache = MongoCache(bot.handler, "Connection_url")
bot.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