Functions

Tracing

trace

daf.logging.tracing.trace(message: str, level: Union[TraceLEVELS, int] = TraceLEVELS.NORMAL)

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.

Getters

get_logger

daf.logging.get_logger() → LoggerBASE

Returns:

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

Return type:

LoggerBASE

get_client

daf.client.get_client() → Client

Returns the CLIENT object used for communicating with Discord.

get_guild_user

daf.core.get_guild_user(snowflake: Union[int, Object, Guild, User]) → Optional[Union[GUILD, USER]]

Retrieves the GUILD/USER object that has the snowflake ID from the shilling list.

Parameters:

snowflake (Union[int, discord.Object, discord.Guild, discord.User, discord.Object]) – Snowflake ID or discord objects containing snowflake id of the GUILD.

Raises:

TypeError – Incorrect snowflake type

Returns:

• daf.guild.GUILD | daf.guild.USER – The object requested.

• None – If not guild/user not in the shilling list.

get_shill_list

daf.core.get_shill_list() → List[Union[GUILD, USER]]

New in version v2.1.

Returns:

The shilling list.

Return type:

List[Union[guild.GUILD, guild.USER]]

Decorators

data_function

daf.dtypes.data_function(fnc: Callable)

Decorator used for wrapping a function that will return data to send when the message is ready.

The fnc function must return data that is of type that the xMESSAGE object supports. If the type returned is not valid, the send attempt will simply be ignored and nothing will be logged at at, this is useful if you want to use the fnc function to control whenever the message is ready to be sent. For example: if we have a function defined like this:

@daf.data_function
def get_data():
    return None

...
daf.TextMESSAGE(..., data=get_data())
...

then no messages will ever be sent, nor will any logs be made since invalid values are simply ignored by the framework.

Parameters:

fnc (Callable) – The function to wrap.

Returns:

A class for creating wrapper objects is returned. These wrapper objects can be used as a data parameter to the Messages objects.

Return type:

FunctionCLASS

import  daf, datetime, secret
from daf import discord
from datetime import timedelta


############################################################################################
# It's VERY IMPORTANT that you use @daf.data_function!
############################################################################################


@daf.data_function
def get_data(parameter):
    l_time = datetime.datetime.now()
    return f"Parameter: {parameter}\nTimestamp: {l_time.day}.{l_time.month}.{l_time.year} :: {l_time.hour}:{l_time.minute}:{l_time.second}"

guilds = [
    daf.GUILD(
        snowflake=123456789,    # ID of server (guild) or a discord.Guild object
        messages=[              # List MESSAGE objects 
            daf.TextMESSAGE(
                              start_period=None,                    # If None, messages will be send on a fixed period (end period)
                              end_period=timedelta(seconds=15),     # If start_period is None, it dictates the fixed sending period,
                                                                    # If start period is defined, it dictates the maximum limit of randomized period
                              data=get_data(123),                   # Data you want to sent to the function (Can be of types : str, embed, file, list of types to the left
                                                                    # or function that returns any of above types(or returns None if you don't have any data to send yet), 
                                                                    # where if you pass a function you need to use the daf.FUNCTION decorator on top of it ).
                              channels=[123456789],                 # List of ids of all the channels you want this message to be sent into
                              mode="send",                          # "send" will send a new message every time, "edit" will edit the previous message, "clear-send" will delete
                                                                    # the previous message and then send a new one
                              start_in=timedelta(seconds=0),        # Start sending now (True) or wait until period
                              remove_after=None                     # Remove the message never or after n-times, after specific date or after timedelta
                              ),  
        ],
        logging=True,           # Generate file log of sent messages (and failed attempts) for this server
        remove_after=None       # When to remove the guild and it's message from the shilling list
    )
]

############################################################################################

daf.run(token=secret.C_TOKEN,        
        server_list=guilds,
        is_user=False)
    

Core control

initialize

async daf.core.initialize(token: str, server_list: Optional[List[Union[GUILD, USER, AutoGUILD]]] = None, is_user: Optional[bool] = False, user_callback: Optional[Union[Callable, Coroutine]] = None, server_log_output: Optional[str] = None, sql_manager: Optional[LoggerSQL] = None, intents: Optional[Intents] = None, debug: Optional[Union[TraceLEVELS, int, str, bool]] = TraceLEVELS.NORMAL, proxy: Optional[str] = None, logger: Optional[LoggerBASE] = None) → None

The main initialization function. It initializes all the other modules, creates advertising tasks and initializes all the core functionality. If you want to control your own event loop, use this instead of run.

Parameters:

Any (Any) – Parameters are the same as in daf.core.run().

shutdown

async daf.core.shutdown(loop: Optional[AbstractEventLoop] = None) → None

Stops the framework.

Changed in version v2.1: Made the function non async and shutdown everything.

Parameters:

loop (Optional[asyncio.AbstractEventLoop]) – The loop everything is running in. Leave empty for default loop.

run

daf.core.run(token: str, server_list: Optional[List[Union[GUILD, USER, AutoGUILD]]] = None, is_user: Optional[bool] = False, user_callback: Optional[Union[Callable, Coroutine]] = None, server_log_output: Optional[str] = None, sql_manager: Optional[LoggerSQL] = None, intents: Optional[Intents] = None, debug: Optional[Union[TraceLEVELS, int, str, bool]] = TraceLEVELS.NORMAL, proxy: Optional[str] = None, logger: Optional[LoggerBASE] = None) → None

Runs the framework and does not return until the framework is stopped (daf.core.shutdown()). After stopping, it returns None.

Warning

This will block until the framework is stopped, if you want manual control over the asyncio event loop, eg. you want to start the framework as a task, use the daf.core.initialize() coroutine.

Changed in version v2.2:

• Added logger parameter

• user_callback can now be a regular function as well as async

Deprecated since version v2.2:

These parameters are replaced with logger parameter.

• sql_manager

• server_log_output

Parameters:

• token (str) – Discord’s access token for account.

• server_list (Optional[List[Union[GUILD, USER]]) – Predefined server list (guild list) to shill.

• is_user (Optional[bool]) – Set to True if the token is for an user account.

• user_callback (Optional[Union[Callable, Coroutine]]) – Function or async function to call after the framework has been started.

• server_log_output (Optional[str]) – Path where the server log files will be created.

• sql_manager (Optional[LoggerSQL]) – SQL manager object that will save logs into the database.

• intents (Optional[discord.Intents]) – Discord Intents object (represents settings to which events it will be listened to).

• debug (Optional[TraceLEVELS | int | str] = TraceLEVELS.NORMAL) –

  Changed in version v2.3: Deprecate use of bool (assume TraceLEVELS.NORMAL). Add support for TraceLEVELS or int or str that converts to TraceLEVELS.

  The level of trace for trace function to display. The higher value this option is, the more will be displayed.

• proxy (Optional[str]) – URL of a proxy you want the framework to use.

• logger (Optional[loggers.LoggerBASE]) – The logging class to use. If this is not provided, JSON is automatically used.

Raises:

• ModuleNotFoundError – Missing modules for the wanted functionality, install with pip install discord-advert-framework[optional-group].

• ValueError – Invalid proxy url.

Shilling list modification

add_object

daf.core.add_object(obj: Union[guild.USER, guild.GUILD]) → None

Adds a guild or an user to the daf.

Parameters:

• obj: Union[guild.USER, guild.GUILD]

  The guild object to add into the daf.

Raises:

• ValueError

  The guild/user is already added to the daf.

• TypeError

  The object provided is not supported for addition.

• TypeError

  Invalid parameter type.

• Other

  Raised in the obj.initialize() method

add_object

daf.core.add_object(obj: Union[message.DirectMESSAGE, message.TextMESSAGE, message.VoiceMESSAGE], snowflake: Union[int, guild.GUILD, guild.USER, dc.Guild, dc.User, dc.Object]) → None

Adds a message to the daf.

Parameters:

• obj: Union[message.DirectMESSAGE, message.TextMESSAGE, message.VoiceMESSAGE]

  The message object to add into the daf.

• snowflake: Union[int, guild.GUILD, guild.USER, discord.Guild, discord.User]

  Which guild/user to add it to (can be snowflake id or a framework _BaseGUILD object or a discord API wrapper object).

Raises:

• ValueError

  guild_id wasn’t provided when adding a message object (to which guild should it add)

• TypeError

  The object provided is not supported for addition.

• TypeError

  Missing snowflake parameter.

• ValueError

  Could not find guild with that id.

• Other

  Raised in the obj.add_message() method

add_object

daf.core.add_object(obj: guild.AutoGUILD) → None

Adds a AutoGUILD to the shilling list.

Parameters:

• obj: daf.guild.AutoGUILD

  AutoGUILD object that automatically finds guilds to shill in.

Raises:

• TypeError

  The object provided is not supported for addition.

• Other

  From initialize() method.

remove_object

daf.core.remove_object(snowflake: Union[int, Object, Guild, User, _BaseGUILD, BaseMESSAGE, AutoGUILD]) → None

Changed in version v2.3: Instead of raising DAFNotFound, raises ValueError

Removes an object from the daf.

Parameters:

snowflake (Union[int, dc.Object, dc.Guild, dc.User, dc.Object, guild._BaseGUILD, message.BaseMESSAGE, guild.AutoGUILD]) – The GUILD/USER object to remove/snowflake of GUILD/USER or a xMESSAGE object or AutoGUILD object.

Raises:

• ValueError – Item (with specified snowflake) not in the shilling list.

• TypeError – Invalid argument.