Logging reference¶

TraceLEVELS¶

enum daf.logging.tracing.TraceLEVELS(value)¶

Levels of trace for debug.

trace¶

daf.logging.tracing.trace(message: str, level: TraceLEVELS | int = TraceLEVELS.NORMAL, reason: Exception | None = None, exception_cls: Exception | None = None)¶

Prints a trace to the console. This is thread safe.

Changed in version v2.3:

Will only print if the level is lower than the configured (thru run()’s debug parameter max level.

Eg. if the max level is ERROR, then the level parameter needs to be either DEPRECATED or ERROR, else nothing will be printed.

Parameters:

message (str) – Trace message.
level (TraceLEVELS | int) – Level of the trace. Defaults to TraceLEVELS.NORMAL.
reason (Optional[Exception]) – Optional exception object, which caused the prinout.
exception_cls (Optional[Exception]) – An exception to raise after tracing.

get_logger¶

daf.logging.get_logger() → LoggerBASE¶

Returns:: The selected logging object which is of inherited type from LoggerBASE.
Return type:: LoggerBASE

LoggerBASE¶

class daf.logging.LoggerBASE(fallback=None)¶

Changed in version v2.7: Invite link tracking.

Added in version v2.2.

The base class for making loggers. This can be used to implement your custom logger as well. This does absolutely nothing, and is here just for demonstration.

Parameters:: fallback (Optional[LoggerBASE]) – The manager to use, in case saving using this manager fails.

async initialize() → None¶: Initializes self and the fallback

abstract async analytic_get_num_messages(guild: int | None = None, author: int | None = None, after: datetime | None = None, before: datetime | None = None, guild_type: Literal['USER', 'GUILD'] | None = None, message_type: Literal['TextMESSAGE', 'VoiceMESSAGE', 'DirectMESSAGE'] | None = None, sort_by: Literal['successful', 'failed', 'guild_snow', 'guild_name', 'author_snow', 'author_name'] = 'successful', sort_by_direction: Literal['asc', 'desc'] = 'desc', limit: int = 500, group_by: Literal['year', 'month', 'day'] = 'day') → List[Tuple[date, int, int, int, str, int, str]]¶

Counts all the messages in the configured group based on parameters.

Parameters:

guild (int) – The snowflake id of the guild.
author (int) – The snowflake id of the author.
after (Union[datetime, None] = None) – Only count messages sent after the datetime.
before (Union[datetime, None]) – Only count messages sent before the datetime.
guild_type (Literal["USER", "GUILD"] | None,) – Type of guild.
message_type (Literal["TextMESSAGE", "VoiceMESSAGE", "DirectMESSAGE"] | None,) – Type of message.
sort_by (Literal["successful", "failed", "guild_snow", "guild_name", "author_snow", "author_name"],) – Sort items by selected. Defaults to “successful”
sort_by_direction (Literal["asc", "desc"]) – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the rows to return. Defaults to 500.
group_by (Literal["year", "month", "day"]) – Results returned are grouped by group_by

Returns:

List of tuples.

Each tuple contains:

Date
Successful sends
Failed sends
Guild snowflake id,
Guild name
Author snowflake id,
Author name

Return type:

list[tuple[date, int, int, int, str, int, str]]

abstract async delete_logs(table: Any, logs: List[Any])¶

Method used to delete log objects objects.

Parameters:

table (Any) – The logging table to delete from.
primary_keys (List[int]) – List of Primary Key IDs that match the rows of the table to delete.

async update(**kwargs)¶

Used to update the original parameters.

Parameters:

kwargs (Any) – Keyword arguments of any original parameters.

Raises:

TypeError – Invalid keyword argument was passed.
Other – Other exceptions raised from .initialize method (if it exists).

LoggerJSON¶

class daf.logging.LoggerJSON(path: str = '/home/docs/daf/History', fallback: LoggerBASE | None = None)¶

Changed in version v3.1: The index of each log is now a snowflake ID. It consists of <timestamp in ms since epoch> | <sequence number>. <sequence number> is of fixed size 8 bits, while timestamp is not of fixed size.

Changed in version v2.8: When file reaches size of 100 kilobytes, a new file is created.

Added in version v2.2.

Logging class for generating .json file logs. The logs are saved into JSON files and fragmented by guild/user and day (each day, new file for each guild).

Parameters:

path (Optional[str]) – Path to the folder where logs will be saved. Defaults to /<user-home>/daf/History
fallback (Optional[LoggerBASE]) – The manager to use, in case saving using this manager fails.

Raises:

OSError – Something went wrong at OS level (insufficient permissions?) and fallback failed as well.

async delete_logs(logs: List[dict])¶

Method used to delete log objects objects.

Parameters:

table (Any) – The logging table to delete from.
primary_keys (List[int]) – List of Primary Key IDs that match the rows of the table to delete.

async analytic_get_num_messages(guild: int | None = None, author: int | None = None, after: datetime = datetime.datetime(1, 1, 1, 0, 0), before: datetime = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), guild_type: Literal['USER', 'GUILD'] | None = None, message_type: Literal['TextMESSAGE', 'VoiceMESSAGE', 'DirectMESSAGE'] | None = None, sort_by: Literal['successful', 'failed', 'guild_snow', 'guild_name', 'author_snow', 'author_name'] = 'successful', sort_by_direction: Literal['asc', 'desc'] = 'desc', limit: int = 500, group_by: Literal['year', 'month', 'day'] = 'day') → list¶

Counts all the messages in the configured group based on parameters.

Parameters:

guild (int) – The snowflake id of the guild.
author (int) – The snowflake id of the author.
after (Union[datetime, None] = None) – Only count messages sent after the datetime.
before (Union[datetime, None]) – Only count messages sent before the datetime.
guild_type (Literal["USER", "GUILD"] | None,) – Type of guild.
message_type (Literal["TextMESSAGE", "VoiceMESSAGE", "DirectMESSAGE"] | None,) – Type of message.
sort_by (Literal["successful", "failed", "guild_snow", "guild_name", "author_snow", "author_name"],) – Sort items by selected. Defaults to “successful”
sort_by_direction (Literal["asc", "desc"]) – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the rows to return. Defaults to 500.
group_by (Literal["year", "month", "day"]) – Results returned are grouped by group_by

Returns:

List of tuples.

Each tuple contains:

Date
Successful sends
Failed sends
Guild snowflake id,
Guild name
Author snowflake id,
Author name

Return type:

list[tuple[date, int, int, int, str, int, str]]

async initialize()¶: Initializes self and the fallback

async update(**kwargs)¶

Used to update the original parameters.

Parameters:

kwargs (Any) – Keyword arguments of any original parameters.

Raises:

TypeError – Invalid keyword argument was passed.
Other – Other exceptions raised from .initialize method (if it exists).

LoggerCSV¶

class daf.logging.LoggerCSV(path: str = '/home/docs/daf/History', delimiter: str = ';', fallback: LoggerBASE | None = None)¶

Added in version v2.2.

Caution

Invite link tracking is not supported with LoggerCSV!

Logging class for generating .csv file logs. The logs are saved into CSV files and fragmented by guild/user and day (each day, new file for each guild).

Each entry is in the following format:

Timestamp, Guild Type, Guild Name, Guild Snowflake, Message Type, Sent Data, Message Mode (Optional), Channels (Optional), Success Info (Optional)

Parameters:

path (str) – Path to the folder where logs will be saved. Defaults to /<user-home>/daf/History
delimiter (str) – The delimiter between columns to use. Defaults to ‘;’
fallback (Optional[LoggerBASE]) – The manager to use, in case saving using this manager fails.

Raises:

OSError – Something went wrong at OS level (insufficient permissions?) and fallback failed as well.

async delete_logs(table: Any, logs: List[Any])¶

Method used to delete log objects objects.

Parameters:

table (Any) – The logging table to delete from.
primary_keys (List[int]) – List of Primary Key IDs that match the rows of the table to delete.

Counts all the messages in the configured group based on parameters.

Parameters:

guild (int) – The snowflake id of the guild.
author (int) – The snowflake id of the author.
after (Union[datetime, None] = None) – Only count messages sent after the datetime.
before (Union[datetime, None]) – Only count messages sent before the datetime.
guild_type (Literal["USER", "GUILD"] | None,) – Type of guild.
message_type (Literal["TextMESSAGE", "VoiceMESSAGE", "DirectMESSAGE"] | None,) – Type of message.
sort_by (Literal["successful", "failed", "guild_snow", "guild_name", "author_snow", "author_name"],) – Sort items by selected. Defaults to “successful”
sort_by_direction (Literal["asc", "desc"]) – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the rows to return. Defaults to 500.
group_by (Literal["year", "month", "day"]) – Results returned are grouped by group_by

Returns:

List of tuples.

Each tuple contains:

Date
Successful sends
Failed sends
Guild snowflake id,
Guild name
Author snowflake id,
Author name

Return type:

list[tuple[date, int, int, int, str, int, str]]

async initialize()¶: Initializes self and the fallback

async update(**kwargs)¶

Used to update the original parameters.

Parameters:

kwargs (Any) – Keyword arguments of any original parameters.

Raises:

TypeError – Invalid keyword argument was passed.
Other – Other exceptions raised from .initialize method (if it exists).

LoggerSQL¶

Changed in version v2.7:

Invite link tracking.
Default database file output set to /<user-home-dir>/daf/messages

Used for controlling the SQL database used for message logs.

Parameters:

username (Optional[str]) – Username to login to the database with.
password (Optional[str]) – Password to use when logging into the database.
server (Optional[str]) – Address of the server.
port (Optional[int]) – The port of the database server.
database (Optional[str]) – Name of the database used for logs.
dialect (Optional[str]) – Dialect or database type (SQLite, mssql, )
fallback (Optional[LoggerBASE]) – The fallback manager to use in case SQL logging fails. (Default: LoggerJSON (“History”))

Raises:

ValueError – Unsupported dialect (db type).
ModuleNotFoundError – Extra requirements are required.

async initialize() → None¶

This method initializes the connection to the database, creates the missing tables and fills the lookup tables with types defined by the register_type(lookup_table) function.

Note

This is automatically called when running the daf.

Raises:: Any – from ._begin_engine() from ._create_tables() from ._generate_lookup_values()

Counts all the messages in the configured group based on parameters.

Parameters:

guild (int) – The snowflake id of the guild.
author (int) – The snowflake id of the author.
after (Union[datetime, None] = None) – Only count messages sent after the datetime.
before (Union[datetime, None]) – Only count messages sent before the datetime.
guild_type (Literal["USER", "GUILD"] | None,) – Type of guild.
message_type (Literal["TextMESSAGE", "VoiceMESSAGE", "DirectMESSAGE"] | None,) – Type of message.
sort_by (Literal["successful", "failed", "guild_snow", "guild_name", "author_snow", "author_name"],) – Sort items by selected. Defaults to “successful”
sort_by_direction (Literal["asc", "desc"]) – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the rows to return. Defaults to 500.
group_by (Literal["year", "month", "day"]) – Results returned are grouped by group_by

Returns:

List of tuples.

Each tuple contains:

Date
Successfule sends
Failed sends
Guild snowflake id,
Guild name
Author snowflake id,
Author name

Return type:

list[tuple[date, int, int, int, str, int, str]]

Raises:

SQLAlchemyError – There was a problem with the database.

analytic_get_message_log(guild: int | None = None, author: int | None = None, after: datetime = datetime.datetime(1, 1, 1, 0, 0), before: datetime = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), success_rate: Tuple[float, float] = (0, 100), guild_type: Literal['USER', 'GUILD'] | None = None, message_type: Literal['TextMESSAGE', 'VoiceMESSAGE', 'DirectMESSAGE'] | None = None, sort_by: Literal['timestamp', 'success_rate'] = 'timestamp', sort_by_direction: Literal['asc', 'desc'] = 'desc', limit: int = 500) → List[MessageLOG]¶

Returns a list of MessageLOG objects (message logs) that match the parameters.

Parameters:

guild (Union[int, None]) – The snowflake id of the guild.
author (Union[int, None]) – The snowflake id of the author.
after (Union[datetime, None]) – Include only messages sent after this datetime.
before (Union[datetime, None]) – Include only messages sent before this datetime.
success_rate (tuple[int, int]) –
Success rate tuple containing minimum success rate and maximum success rate the message log can have for it to be included. Success rate is measured in % and it is defined by:

Successfully sent channels / all channels.
guild_type (Literal["USER", "GUILD"] | None,) – Type of guild.
message_type (Literal["TextMESSAGE", "VoiceMESSAGE", "DirectMESSAGE"] | None,) – Type of message.
sort_by (Literal["timestamp", "success_rate", "data"],) – Sort items by selected. Defaults to “timestamp”
sort_by_direction (Literal["asc", "desc"] = "desc") – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the message logs to return. Defaults to 500.

Returns:

List of the message logs.

Return type:

list[MessageLOG]

async analytic_get_num_invites(guild: int | None = None, after: datetime = datetime.datetime(1, 1, 1, 0, 0), before: datetime = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), sort_by: Literal['count', 'guild_snow', 'guild_name', 'invite_id'] = 'count', sort_by_direction: Literal['asc', 'desc'] = 'desc', limit: int = 500, group_by: Literal['year', 'month', 'day'] = 'day') → List[Tuple[date, int, str]]¶

Returns invite link join counts.

Parameters:

guild (int) – The snowflake id of the guild.
after (Union[datetime, None] = None) – Only count messages sent after the datetime.
before (Union[datetime, None]) – Only count messages sent before the datetime.
sort_by (Literal["count", "guild_snow", "guild_name", "invite_id"],) – Sort items by selected. Defaults to “successful”
sort_by_direction (Literal["asc", "desc"]) – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the rows to return. Defaults to 500.
group_by (Literal["year", "month", "day"]) – Results returned are grouped by group_by

Returns:

List of tuples.

Each tuple contains:

Date
Invite count
Invite ID

Return type:

list[Tuple[date, int, int, str, str]]

Raises:

SQLAlchemyError – There was a problem with the database.

analytic_get_invite_log(guild: int | None = None, invite: str | None = None, after: datetime = datetime.datetime(1, 1, 1, 0, 0), before: datetime = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), sort_by: Literal['timestamp'] = 'timestamp', sort_by_direction: Literal['asc', 'desc'] = 'desc', limit: int = 500) → List[InviteLOG]¶

Returns a list of InviteLOG objects (invite logs) filtered by the given parameters.

Parameters:

guild (Union[int, None]) – The snowflake id of the guild.
invite (Union[str, None]) – Discord invite ID (final part of URL).
after (Union[datetime, None]) – Include only invites sent after this datetime.
before (Union[datetime, None]) – Include only invites sent before this datetime.
sort_by (Literal["timestamp"],) – Sort items by selected. Defaults to “timestamp”
sort_by_direction (Literal["asc", "desc"] = "desc") – Sort items by sort_by in selected direction (asc = ascending, desc = descending). Defaults to “desc”
limit (int = 500) – Limit of the invite logs to return. Defaults to 500.

Returns:

List of the message logs.

Return type:

list[InviteLOG]

async delete_logs(table: MessageLOG | InviteLOG, primary_keys: List[int])¶

Method used to delete log objects objects.

Parameters:

table (MessageLOG | InviteLOG) – The logging table to delete from.
primary_keys (List[int]) – List of Primary Key IDs that match the rows of the table to delete.

async update(**kwargs)¶

Added in version v2.0.

Used for changing the initialization parameters the object was initialized with.

Warning

Upon updating, the internal state of objects get’s reset, meaning you basically have a brand new created object. It also resets the message objects.

Parameters:

**kwargs (Any) – Custom number of keyword parameters which you want to update, these can be anything that is available during the object creation.

Raises:

TypeError – Invalid keyword argument was passed.
Other – Raised from .initialize() method.