Status Events

The status cog has two events you can listen to, on_vexed_status_update and on_vexed_status_channel_send.

status_channel_send is fired in quick succession, especially on larger bots with lots of channels added, so you shouldn’t do anything expensive. status_channel_send is dispatched after a successful channel send, so it won’t be dispatched if the bot couldn’t send for whatever reason.

status_update is dispatched with the channels the cog intends to send updates to when an update has been confirmed as a non-ghost update.

There is a guaranteed delay of 1 second between status_update and the first status_channel_send to allow you to perform an expensive process (or avoid repeated config calls for each dispatch) and then cache the result for the when status_channel_send dispatches for each channel so you get the timing correct and you can guarantee it was sent.

Though this is incredibly unlikely, the cog will cancel sending updates (and the subsequent status_channel_send) if it lasts longer than 4 minutes after it started that check for updates. Note multiple services’ updates may be included in this time.

The events are linear. on_status_update guarantees the next status_channel_send will be the same update.

Note

If you are using this cog/event to get a parsed update to send yourself, note that status_update will not trigger if no channels are subscribed to the service - the cog only checks feeds that have channels subscribed to it.

Tip

For testing, the statusdev checkfeed (alias statusdev cf) command can be used. It will send the latest incident and scheduled maintenance for the service provided to the current channel, with the force parameter being True.

You can also use statusdev forcestatus (alias statusdev fs) which will send the latest incident to ALL channels in ALL servers that recieve that service’s incidents.

Example

@commands.Cog.listener()
async def on_vexed_status_update(self, **_kwargs):
    data = await self.config.all_channels()  # get you data from config here
    self.data_cache = data

@commands.Cog.listener()
async def on_vexed_status_channel_send(self, *, service, channel_data, **_kwargs):
    data = self.data_cache.get(channel_data.channel.id)
    # then get it back here for each channel send to reduce config calls,
    # esp on larger bots

    if data is None:
        return

    mention_ids = data["user_mentions"].get(service)
    # if you registered in config as user_mentions
    if mention_ids is None:
        return

    mention_ids = [f"<@{id}>" for id in mention_ids]
    await channel_data.channel.send(humanize_list(mention_ids))

Event Reference

on_vexed_status_update(update, service, channels, force)

This event triggers before updates are sent to channels. See above for details.

Parameters:

update (Update) – The main class with the update information, including what was sent and the settings it was sent with. It has subclasses in the attributes - see below Custom Objects.
service (str) – The name of the service, in lower case. Guaranteed to be on of the keys in the file-level consts of status.py, though new services are being added over time so don’t copy-paste and expect it to be one of them.
channels (dict) – A dict with the keys as channel IDs and the values as a nested dict containing the settings for that channel.
force (bool) – Whether or not the update was forced to update with statusdev checkfeed/statusdev cf

on_vexed_status_channel_send(update, service, channel_data, force)

This is has similarities to the above event, mainly that it dispatches after an update was successfully sent to a specific channel. See above info at the top of this page for details.

Parameters:

update (Update) – The main class with the update information, including what was sent and the settings it was sent with. It has subclasses - see below Custom Objects.
service (str) – The name of the service, in lower case. Guaranteed to be on of the keys in the file-level consts of status.py, though new services are being added over time so don’t copy-paste and expect it to be one of them.
channel_data (ChannelData) – The channel it was sent to and the associated settings. It has subclasses in the attributes - see below Custom Objects.
force (bool) – Whether or not the update was forced to update with statusdev checkfeed/statusdev cf

Custom Objects

ChannelData

objects/channel.py (ignore the custom errors in this file) This object has all the settings that the update was sent with.

Attributes

channel (discord.TextChannel) – Idk, this might just be the channel the update was sent to.
mode (str) – The mode the update was sent as.
webhook (bool) – Whether or not it was sent as a webhook.
edit_id (Dict[str, int]) – I cba to explain this, you don’t need to know.
embed (bool) – Whether or not it was sent as an embed.

Update

objects/incidentdata.py This is a base object from which the two below are nested in.

Attributes

incidentdata (incidentdata) – The feed data from which the update was sent. See below.

new_fields (List[UpdateField]) – A list of new fields since the service was last checked. Usually 1.

incidentdata

objects/incidentdata.py This is present in the incidentdata attribute of the Update object.

Attributes

fields (List[UpdateField]) – A list containing UpdateField objects
title (str) – The title of the incident
time: (datetime | None) - Parsed time, or None
link (str) – The incident link.
actual_time: (datetime | None) - Parsed time, or None
description (str | None) – Exclusively used for when a scheduled incident is being sent
incident_id (str) – The incident’s unique ID
scheduled_for: (datetime | None) If the incident sent was scheduled, this is when the event starts/started

Methods

to_dict() – Get a dict of the data held in the object

get_update_ids() – Get the group IDs. These are unique and represent each update. See UpdateField for more information

UpdateField

objects/incidentdata.py This is present in the fields attribute of the above incidentdata object and the new_fields attribute of the Update object.

Attributes

name (str) – The name of the field
value (str) – The value of the field
update_id (str) – The group ID of the field. These are unique unless the field was split up to accommodate embed limits