Logging reference#

trace#

daf.logging.tracing.trace(message: str, level: TraceLEVELS | int = TraceLEVELS.NORMAL, reason: 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.

get_logger#

daf.logging.get_logger() LoggerBASE#
Returns:

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

Return type:

LoggerBASE

TraceLEVELS#

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

Levels of trace for debug.

See also

trace

Changed in version v2.3: Added DEPRECATION

Valid values are as follows:

DEPRECATED = <TraceLEVELS.DEPRECATED: 0>#

Show only deprecation notices.

ERROR = <TraceLEVELS.ERROR: 1>#

Show deprecations and errors.

WARNING = <TraceLEVELS.WARNING: 2>#

Show deprecations, errors, warnings.

NORMAL = <TraceLEVELS.NORMAL: 3>#

Show deprecations, errors, warnings, info messages.

DEBUG = <TraceLEVELS.DEBUG: 4>#

Show deprecations, errors, warnings, info messages, debug messages.

LoggerBASE#

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

New 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

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, delimiter: str, fallback: LoggerBASE | None = None)#

New in version v2.2.

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.

  • delimiter (str) – The delimiter between columns to use.

  • 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 initialize() None#

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).

LoggerJSON#

class daf.logging.LoggerJSON(path: str, fallback: LoggerBASE | None = None)#

New 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 (str) – Path to the folder where logs will be saved.

  • 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 initialize() None#

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#

class daf.logging.sql.LoggerSQL(username: str | None = None, password: str | None = None, server: str | None = None, port: int | None = None, database: str | None = None, dialect: Literal['sqlite', 'mssql', 'postgresql', 'mysql'] = None, fallback: LoggerBASE | None = Ellipsis)#

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).

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()

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]]#
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.

async analytic_get_message_log(guild: int | None = None, author: int | None = None, after: datetime | None = None, before: datetime | None = None, 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 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 meassured in % and it is defined by:

    Successuly 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 update(**kwargs)#

New 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.