clashcallerbotreddit package

Submodules

clashcallerbotreddit.database module

Setup the MySQL-compatible database.

If run directly, this module will setup the ClashCallerBot database with tables and display their format and contents. Additionally, this module provides a class with various methods for managing the MySQL-compatible database:

• Create database and tables.
• View table data and properties.
• Lock tables for reading and writing.
• Grant user permissions (if logged into database as root).
• Add rows to tables.
• Delete tables and rows.
• Convert python datetime to MySQL datetime.

class clashcallerbotreddit.database.ClashCallerDatabase(config_file=None, section='bot', root_user=None)

Bases: object

Implements a class for a ClashCaller Database.

Acts as an object-relational mapper for mysql.connector specific to ClashCallerBot.

config_file

A configparser object with database.ini file pre-read.

Type:configparser.ConfigParser

section

Section heading containing bot information. Defaults to ‘bot’.

Type:str

root_user

Specifies whether the database will be setup as root user.

Type:bool

mysql_connection

A mysql.connector.connect object.

Type:mysql.connector.connect

cursor

A mysql.connector.connect.cursor object.

Type:mysql.connector.connect.cursor

close_connections() → None

Close database connections.

Method closes database cursor and connection.

static convert_datetime(dt: <module 'datetime' from '/usr/lib/python3.6/datetime.py'>) → str

Converts python datetime to MySQL datetime.

Method converts given python datetime object to MySQL datetime format.

Parameters:dt – Datetime object in default format. Returns:Datetime string in MySQL format.

create_database() → None

Create database.

Method creates database with database name.

create_table(tbl_name: str, cols: str) → None

Create table in database.

Method creates table in database with given name and specifications.

Parameters:

• tbl_name – Name to give table.
• cols – Columns to put in table.

Example

>>> from clashcallerbotreddit import config
>>> from clashcallerbotreddit.database import ClashCallerDatabase
>>> db = ClashCallerDatabase(config, root_user=False)
>>> tbl_name = 'table'
>>> cols = 'id INT UNSIGNED NOT NULL AUTO_INCREMENT, '
...        'permalink VARCHAR(100), message VARCHAR(100), new_date DATETIME, '
...        'userID VARCHAR(20), PRIMARY KEY(id)'
...
>>> db.create_table(tbl_name, cols)

delete_row(tid: str) → None

Deletes row from message table.

Method deletes given table id (row) from message table.

Parameters:tid – Table id from id column of message table.

describe_table(tbl_name: str) → list

Gets description of table.

Method returns a list describing the structure of the given table.

Parameters:tbl_name – Name of table to describe Returns:List with table description, empty list otherwise.

drop_table(tbl_name: str) → None

Drop table from database.

Function drops given table from given database.

Parameters:tbl_name – Table to drop.

get_expired_messages(time_now: datetime.datetime) → list

Retrieves list of messages that have expired.

Method returns list of messages whose expiration times are before current datetime.

Parameters:time_now – Current datetime. Returns:List containing results of query.

get_removable_messages(usr_name: str, link: str) → list

Retrieves list of messages that match the username and permalink.

Checks the message table for rows containing the given user name and given link.

Parameters:

• usr_name – Reddit username wanting to delete saved calls.
• link – Comment permalink of saved call (without domain prefix)

Returns:

List of messages matching query. Empty list if none found.

get_rows(tbl_name: str) → tuple

Fetch table rows.

Method gets rows of given table by order of id in a tuple.

Parameters:tbl_name – Name of table to get rows from. Returns:Tuple containing each row’s data, empty tuple otherwise.

get_tables() → list

Return table list of database.

Method returns a list with the names of the tables.

Returns:List of table names.

get_user_messages(usr_name: str) → list

Retrieves list of messages that match the username.

Checks the message table for rows containing the given user name.

Parameters:usr_name – Reddit username wanting to list saved calls. Returns:List of messages matching query. Empty list if none found.

grant_permissions() → None

Grants bot user permissions to database.

Method grants bot user permissions to database.

Notes

Only database root user can grant database permissions.

lock_read(tbl_name: str) → None

Locks table for reading.

Method locks a given table for read access.

Parameters:tbl_name – Name of table to lock. Returns:True if successful, False otherwise.

Notes

• Any previous locks are implicitly released.
• Read locks have lower priority than write locks.

lock_write(tbl_name: str) → None

Locks table for writing.

Method locks a given table for write access.

Parameters:tbl_name – Name of table to lock.

Notes

• Any previous locks are implicitly released.
• Write locks have higher priority than read locks.

open_connections() → None

Open database connections.

Method makes database connection and cursor.

save_message(link: str, msg: str, exp: <module 'datetime' from '/usr/lib/python3.6/datetime.py'>, usr_name: str) → None

Saves given comment data into message_data table.

Method saves given inputs in message_date table as a row.

Parameters:

• link – Comment permalink.
• msg – Comment message.
• exp – Expiration datetime object.
• usr_name – Comment author username.

select_database() → None

Select database for command execution.

Method selects database within MySQL for command execution.

unlock_tables() → None

Unlocks tables to allow access.

Method unlocks tables to allow read/write access.

clashcallerbotreddit.database.main()

clashcallerbotreddit.reply module

Performs cleanup operations.

This module implements functions designed to clean up various data sets:

• Sends and deletes stored messages in the MySQL-compatible database.

• Checks bot’s comments and removes comments below a certain threshold.

• Checks bot’s messages for keywords and deletes them after:

  • Adding message author to call reminder.
  • PMing list of message author’s calls.
  • Deleting message author from call.

clashcallerbotreddit.reply.check_comments(usr: str, limit: int = -5) → None

Checks comments and deletes if at or below threshold.

Checks given user’s last 100 comments and deletes each one at or below the given threshold.

Parameters:

• usr – User to check comments of.
• limit – Threshold at or below which comment will be deleted. Defaults to -5.

Returns:

None. Comments at or below threshold are deleted.

Note

Skips archived comments (> 6 months from start time).

clashcallerbotreddit.reply.check_database() → None

Checks messages in database and sends PM if expiration time passed.

Checks messages saved in a MySQL-compatible database and sends a reminder via PM if the expiration time has passed. If so, the message is removed from the database.

Returns:None. Message is removed from database if expiration time has passed.

clashcallerbotreddit.reply.check_messages() → None

Checks inbox messages.

Checks authorized user’s inbox messages for commands, processes them, then deletes the message.

Returns:None. Messages are processed then deleted.

Notes

• Does not process mentions or comment replies.
• Skips old messages (> 6 months from start time).

clashcallerbotreddit.reply.get_parent(link: str) → str

Fetch parent comment or submission.

Function gets parent comment of given permalink or submission if top level comment.

Parameters:link – Permalink to get parent of. Returns:Parent comment link or default string.

clashcallerbotreddit.reply.main()

clashcallerbotreddit.reply.process_add_me(msg_obj: praw.models.reddit.message.Message)

Process an AddMe! command from a message.

Processes an AddMe! command from a given message that invoked it. The message author is added to the MySQL-compatible database with the permalink, message, and expiration time from the message body.

Parameters:msg_obj – Instance of Message class that invoked the AddMe! command. Returns:Error message string if unsuccessful, None otherwise.

clashcallerbotreddit.reply.process_delete_me(msg_obj: praw.models.reddit.message.Message)

Process a DeleteMe! command from a message.

Processes a DeleteMe! command from a given message that invoked it. If calls from the message author for the permalink from the message body are found in the MySQL-compatible database, they are removed from the database.

Parameters:msg_obj – Instance of Message class that invoked the DeleteMe! command. Returns:Error message string if unsuccessful, None otherwise.

clashcallerbotreddit.reply.process_my_calls(msg_obj: praw.models.reddit.message.Message)

Process a MyCalls! command from a message.

Processes a MyCalls! command from a given message that invoked it. If calls from the message author are found in the MySQL-compatible database, they are sent in a table format via PM.

Parameters:msg_obj – Instance of Message class that invoked the MyCalls! command. Returns:Error message string if unsuccessful, None otherwise.

clashcallerbotreddit.reply.send_reminder(link: str, msg: str, usr: str) → None

Sends reminder PM to username.

Function sends given permalink and message to given username.

Parameters:

• link – Permalink to comment.
• msg – Message in comment that was saved.
• usr – User to send reminder to.

clashcallerbotreddit.search module

Searches recent reddit comments for ClashCaller! string and saves to database.

This module uses the Python Reddit API Wrapper (PRAW) to search recent reddit comments for the ClashCaller! string.

If found, the userID, permalink, comment time, message, and expiration time (if any) are parsed. The default, or provided, expiration time is applied, then all the comment data is saved to a MySQL-compatible database.

The comment is replied to, then the userID is PM’ed confirmation.

clashcallerbotreddit.search.have_replied(cmnt_obj: praw.reddit.Reddit.comment, usr_name: str) → bool

Check if user has replied to a comment.

Function checks reply authors of given comment for given user.

Parameters:

• cmnt_obj – Comment object to get replies of.
• usr_name – Name of bot to check for.

Returns:

True if successful, False otherwise.

clashcallerbotreddit.search.is_recent(cmnt_time: float, time_arg: datetime.datetime) → bool

Checks if comment is a recent comment.

Function compares given comment Unix timestamp with given time.

Parameters:

• cmnt_time – Comment’s created Unix timestamp in UTC.
• time_arg – Time to compare with comment timestamp.

Returns:

True if comment’s created time is after given time, False otherwise.

clashcallerbotreddit.search.main()

clashcallerbotreddit.search.send_confirmation(usr_name: str, link: str, exp: datetime.datetime) → None

Send confirmation to reddit user.

Function sends given user confirmation of given expiration time with given link.

Parameters:

• usr_name – username of user.
• link – Permalink of comment.
• exp – Expiration datetime of call.

Returns:

None.

clashcallerbotreddit.search.send_confirmation_reply(cmnt_obj: praw.reddit.Reddit.comment, exp: datetime.datetime, message_arg: str)

Replies to a comment.

Function replies to a given comment object with a given message.

Parameters:

• cmnt_obj – Comment object to reply to.
• exp – Expiration datetime of call.
• message_arg – Original call message.

Returns:

id of new comment if successful, None otherwise

clashcallerbotreddit.search.send_error_message(usr_name: str, link: str, error: str) → None

Send error message to reddit user.

Function sends given error to given user.

Parameters:

• usr_name – username of user.
• link – Permalink of comment.
• error – Error to send to user.

Returns:

None.

clashcallerbotreddit.search.send_message(usr_name: str, subject_arg: str, message_arg: str) → None

Send message to reddit user.

Sends a message to a reddit user with given subject line.

Parameters:

• usr_name – username of user.
• subject_arg – Subject line of message.
• message_arg – Message to send.

Returns:

None.

Module contents

clashcallerbot-reddit constants

Contains constant variables used in source files.

clashcallerbotreddit.__version__

String with version number using the Semantic Versioning Scheme

Type:str

clashcallerbotreddit.config

A configparser object containing the sections inside database.ini

Type:configparser.ConfigParser

clashcallerbotreddit.module_dir

String with the absolute path of the module’s directory.

Type:str

clashcallerbotreddit.locations

List containing all possible paths of database.ini

Type:list

clashcallerbotreddit.LOGGING

Dictionary containing definitions for the loggers, handlers, and formatters.

Type:dict