Module contents

Modules that handle the events the bot recognizes and reacts to

async spotted.handlers.add_commands(app)

Adds the list of commands with their description to the bot

Parameters:

app (Application) – supplied application

spotted.handlers.add_handlers(app)

Adds all the needed handlers to the application

Parameters:

app (Application) – supplied application

spotted.handlers.add_jobs(app)

Adds all the jobs to be scheduled to the application

Parameters:

app (Application) – supplied application

spotted.handlers package

Submodules

spotted.handlers.anonym_comment module

Anonym Comment on a post in the comment group

async spotted.handlers.anonym_comment.anonymous_comment_msg(update, context)

Handles a new anonym comment on a post in the comment group. Deletes the original post and sends a message with the same text, to avoid any abuse.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.approve module

Approve actions the admin can take on a pending post.

async spotted.handlers.approve.approve_no_callback(update, context)

Handles the approve_no callback. Add a negative vote to the post, updating the keyboard if necessary. If the number of negative votes is greater than the number of votes required, the post is rejected, deleting it from the pending_post table and notifying the user

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

async spotted.handlers.approve.approve_status_callback(update, context)

Handles the approve_status callback. Pauses or resume voting on a specific pending post

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

text and replyMarkup that make up the reply, new conversation state

async spotted.handlers.approve.approve_yes_callback(update, context)

Handles the approve_yes callback. Add a positive vote to the post, updating the keyboard if necessary. If the number of positive votes is greater than the number of votes required, the post is approved, deleting it from the pending_post table and copying it to the channel

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

async spotted.handlers.approve.reject_post(info, pending_post, reason=None)

Rejects a pending post

Parameters:

• info (EventInfo) – information about the callback

• pending_post (PendingPost) – pending post to reject

• reason (str | None, default: None) – reason for the rejection, currently used on autoreply

spotted.handlers.autoreply module

/autoreply command

async spotted.handlers.autoreply.autoreply_callback(update, context)

Handles the autoreply callback. Reply to the user with the autoreply message to inform them about the reason of the rejection

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

async spotted.handlers.autoreply.autoreply_cmd(update, context)

Handles the /autoreply command. Used by replying to one of his pending posts with /autoreply + one of the keys in the autoreplies dictionary in the config file. Send a message to the user with the autoreply message to inform them about a problem with their post

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.ban module

/ban command

async spotted.handlers.ban.ban_cmd(update, context)

Handles the /ban command. Ban a user by replying to one of his pending posts with /ban

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

async spotted.handlers.ban.execute_ban(user_id, info)

Execute the ban of a user by his user_id

Parameters:

• user_id (int) – The user_id of the user to ban

• info (EventInfo) – The EventInfo object

spotted.handlers.cancel module

/cancel command

async spotted.handlers.cancel.cancel_cmd(update, context)

Handles the /cancel command. Exits from the post pipeline and removes the eventual pending post of the user

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.clean_pending module

/clean_pending command

async spotted.handlers.clean_pending.clean_pending_cmd(_, context)

Handles the /clean_pending command. Automatically rejects all pending posts that are older than the chosen amount of hours

Parameters:

• _ – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.constants module

Constants used by the bot handlers

class spotted.handlers.constants.ConversationState(*values)

Bases: Enum

Enum for the states of the conversation. The end state must have value -1, since it is the convention used by the ConversationHandler to terminate the conversation.

END = -1

POSTING = 1

POSTING_CONFIRM = 3

POSTING_PREVIEW = 2

REPORTING_SPOT = 4

REPORTING_USER = 5

REPORTING_USER_REASON = 6

SENDING_USER_REPORT = 7

spotted.handlers.db_backup module

/db_backup command

async spotted.handlers.db_backup.db_backup_cmd(update, context)

Handles the /db_backup command. Automatically upload and send current version of db for backup

Parameters:

• _ – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.follow_comment module

Detect Comment on a post in the comment group

async spotted.handlers.follow_comment.follow_spot_comment(update, context)

Handles a new comment on a post in the comment group. Checks if someone is following the post, and sends them an update in case.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.follow_spot module

Handles callback when the ‘Follow Spot’ button is clicked.

async spotted.handlers.follow_spot.follow_spot_callback(update, context)

Handles the follow callback.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.forwarded_post module

Message forwarded by the telegram channel

async spotted.handlers.forwarded_post.forwarded_post_msg(update, context)

Handles the post forwarded in the channel group. Sends a reply in the channel group and stores it in the database, so that the post can be voted

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.help module

/help command

async spotted.handlers.help.help_cmd(update, context)

Handles the /help command. Sends an help message

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.job_handlers module

Scheduled jobs of the bot

async spotted.handlers.job_handlers.clean_muted_users(context)

Job called each day at 05:00 utc. Removed expired users mute records from the database

Parameters:

context (CallbackContext) – context passed by the jobqueue

async spotted.handlers.job_handlers.clean_pending_job(context)

Job called each day at 05:00 utc. Automatically rejects all pending posts that are older than the chosen amount of hours

Parameters:

context (CallbackContext) – context passed by the jobqueue

async spotted.handlers.job_handlers.db_backup_job(context)

Job called each day at 05:00 utc. Automatically upload and send last version of db for backup

Parameters:

context (CallbackContext) – context passed by the jobqueue

spotted.handlers.job_handlers.get_backup()

Get the database backup, either encrypted or not. When the crypto_key setting is set, the backup is encrypted with Fernet, otherwise it’s returned as is, in plaintext.

Returns:

bytes – bytes of the backup file, either encrypted or not

spotted.handlers.job_handlers.get_updated_backup_path()

Get the path of the database backup file, applying some transformations if needed. If backup_keep_pending is set to False, it creates a copy of the database file and drops the pending_post table from the copy, so the backup won’t contain any pending post.

Returns:

str – path of the database backup file

spotted.handlers.job_handlers.get_zip_backup()

Zip the database file and return the bytes of the zip file, optionally encrypting it with a password if crypto_key is set in the settings. It is called if zip_backup is set to True in the settings.

Returns:

bytes – bytes of the (possibly encrypted) zip file

spotted.handlers.mute module

/mute command

async spotted.handlers.mute.mute_cmd(update, context)

Handles the /mute command. Mute a user by replying to one of his message in the comment group with /mute <n_days> :type update: Update :param update: update event :type context: CallbackContext :param context: context passed by the handler

spotted.handlers.purge module

/purge command

async spotted.handlers.purge.purge_cmd(update, context)

Handles the /purge command. Deletes all posts and the related votes in the database whose actual telegram message could not be found

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.reload module

/reload command

async spotted.handlers.reload.reload_cmd(update, context)

Handles the /reload command. Reload the configuration file, updating the bot’s settings. This incudes both the _settings.yaml_ and the _autorereply.yaml_ file. This way the bot can be updated without restarting it.

In actuality, the current singleton is destroyed and a new one is created as soon as a configuration request is deemed necessary.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Warning

Loading different configurations may cause inconsistencies in live conversations.

spotted.handlers.reply module

/reply command

async spotted.handlers.reply.reply_cmd(update, context)

Handles the /reply command. Send a message to a user by replying to one of his pending posts with /reply + the message you want to send

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.report_spot module

report callback

async spotted.handlers.report_spot.report_spot_callback(update, context)

Handles the report callback.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.report_spot.report_spot_conv_handler()

Creates the report (user) conversation handler. The states are:

• reporting_spot: submit the reason of the report. Expects text

Returns:

ConversationHandler – conversation handler

async spotted.handlers.report_spot.report_spot_msg(update, context)

Handles the reply to the key “Report”. Checks the message the user wants to report, and goes to the final step

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.report_user module

/report command

async spotted.handlers.report_user.report_cmd(update, context)

Handles the reply to the key “Report”. Checks the message the user wants to report

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.report_user.report_user_conv_handler()

Creates the /report (user) conversation handler. The states are:

• reporting_user: submit the username to report. Expects text starting with @ and without spaces in between

• reporting_user_reason: submit the reason of the report. Expects text

Returns:

ConversationHandler – conversation handler

async spotted.handlers.report_user.report_user_msg(update, context)

Handles the reply to the /report command after sent the @username. Checks the the user wants to report, and goes to ask the reason

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

async spotted.handlers.report_user.report_user_sent_msg(update, context)

Handles the reply to the /report command after sent the reason. Checks the the user wants to report, and goes to final step

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.rules module

/rules command

async spotted.handlers.rules.rules_cmd(update, context)

Handles the /rules command. Sends a message containing the rules

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.sban module

/sban command

async spotted.handlers.sban.sban_cmd(update, context)

Handles the /sban command. Sban a user by using this command and listing all the user_id to sban

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.settings module

/settings command

async spotted.handlers.settings.settings_callback(update, context)

Handles the settings,[ anonimo | credit ] callback.

• anonimo: Removes the user_id from the table of credited users, if present.

• credit: Adds the user_id to the table of credited users, if it wasn’t already there.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

async spotted.handlers.settings.settings_cmd(update, context)

Handles the /settings command. Let’s the user choose whether his posts will be credited or not

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.spam_comment module

Anonym Comment on a post in the comment group

async spotted.handlers.spam_comment.spam_comment_msg(update, context)

Handles a spam comment on a post in the comment group. Deletes the original post and bans the user.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Return type:

None

spotted.handlers.spot module

/spot command

async spotted.handlers.spot.spot_cmd(update, context)

Handles the /spot command. Checks that the user is in a private chat and it’s not banned and start the post conversation

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

async spotted.handlers.spot.spot_confirm_query(update, context)

Handles the [ submit | cancel ] callback. Creates the bid or cancels its creation.

• submit: saves the post as pending and sends it to the admins for them to check.

• cancel: cancels the current spot conversation

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.spot.spot_conv_handler()

Creates the spot conversation handler. The states are:

• posting: submit the spot. Expects text, photo or many other formats

• confirm: confirm or cancel the spot submission. Expects an inline query

Returns:

ConversationHandler – conversation handler

async spotted.handlers.spot.spot_msg(update, context)

Handles the reply to the /spot command. Checks the message the user wants to post, and goes to the final step

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

async spotted.handlers.spot.spot_preview_query(update, context)

Handles the [ accept | reject ] callback. Let the user decide if wants to post the message with or without preview.

• accept: the post will be published with preview

• reject: the post will be published without preview

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

Returns:

int – next state of the conversation

spotted.handlers.start module

/start command

async spotted.handlers.start.start_cmd(update, context)

Handles the /start command. Sends a welcoming message

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.unmute module

/unmute command

async spotted.handlers.unmute.unmute_cmd(update, context)

Handles the /unmute command. Unmute a user by using this command and listing all the user_id to unmute

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler

spotted.handlers.warn module

/warn command

async spotted.handlers.warn.execute_warn(info, user_id, comment, from_community=False)

Execute the /warn command. Add a warn to the user and auto-ban is necessary

Args:

user_id: The user_id of the interested user bot: a telegram bot instance from_community: a flag for auto-delete command invokation

async spotted.handlers.warn.warn_cmd(update, context)

Handles the /warn command.

Warn a user by replying to a user’comment on the community group or to a pending spot/report.

Parameters:

• update (Update) – update event

• context (CallbackContext) – context passed by the handler