Module: config¶

This is all the configuration options that can be put into a config file. The default section is the mastoscore section. Anything defined here is also available in all other sections. Like if mastoscore:hashtag is set to testtag, then querying for fetch:hashtag or graph:hashtag will return testtag unless those sections override it.

All Possible Options¶

Mastodon-related Options¶

api_base_url: String¶

URL to contact to login and do stuff. In fetch, this is the URL to start all the fetches. In post, this is the server to connect to and post some toots. When I'm testing, I connect to real servers to test the fetching, and then have a different api_base_url and cred_file defined in the post module to post to my test server.

botusername: String¶

The name of our bot. It's just a user name. So if api_base_url is https://example.social, and our bot is mastoscore@example.social then this would just be mastoscore. Any toots found in the fetch phase that are attributable to this ID will be dropped from the analysis.

cred_file: String¶

The name of a file containing some API keys. See Setting Up for details on how to create a cred_file that is compatible with Mastodon.py. Used by the Tooter class.

hashtag: String¶

Hashtag we are looking for. This is used in all modules in different ways. Omit the # sign. Example: "KungFuSat".

max: Integer¶

Maximum number of toots to pull from a server. Only used by fetch. Defaults to 2000. By default, Mastodon APIs will rate limit at 300 queries in 5 minutes. By default, Mastodon APIs allow 40 toots per API call. So in theory you can get close to 12000 toots before getting rate limited. Mastodon.py also has code to handle being rate limited. I'm not using any of it right now, and I've never tested what happens when I hit rate limits.

Analysis Related Options¶

hours_margin: Integer¶

Number of hours before and after the event time to include in the analysis.

journaldir: String¶

Directory where the journal JSON files will be written. Must be writeable. Relative to the current working directory when you run mastoscore. Example: /home/person/mastoscore/data.

journalfile: String¶

Base name of the journal files. Each file will get the server's name appended to it. So if journaldir is /home/person/mastoscore/data and journalfile is testtag-20241116 then we will write results from querying example.social into a file named /home/person/mastoscore/data/testtag-20241116-example.social.json.

lookback: Integer¶

In the fetch module, this is the Number of days to look backwards. At the moment I'm also experimenting with treating this as hours in the graph module.

top_n: Integer¶

How many top toots do you want to post? For the top 3, set top_n = 3.

timezone: String¶

This is an important option. We assume Mastodon servers send us time in GMT. Then we convert them to this local time zone. The official list can be found by looking at the pytz module. Generally they're things like 'UTC' or 'Canada/Pacific', or 'Europe/Madrid'. But you can also do some common things like 'PST8PDT' or 'EST5EDT'.

This is used in fetch and analyse to convert times into timezone-aware datetime objects. It's used in the graph module to set the X axis and put the vertical event lines in the right place. Note that the code tries hard to be timezone-aware. So you could set event_start for the event in one time zone (e.g., 2024-11-16T12:00:00-05:00) and then set timezone to 'America/Los_Angeles' and it should do the right thing.

Graphing Related Options¶

start_label: String¶

end_label: String¶

String for the start-time label or the end-time label. Only used by the graph module. This is the vertical line labeled "start" or "end" in the graph.

event_start: Datetime¶

end_time: Datetime¶

A string representing the start time or end time of the event. Only used by the graph module. This is the X coordinate for the vertical line labeled "end". Example: 2024-11-16T12:00:00-05:00. See datetime.date.fromisoformat() for the kinds of strings that are supported.

graph_title: String¶

String for the title of the graph. Only used by the graph module. I usually make this a composition of other options.

Posting Related Options¶

root_visibility: String¶

thread_visibility: String¶

These two options control the visibility attached to the various toots that the system will make. Valid options are those defined by the Mastodon API for statuses. Generally, it's public, unlisted, private, direct. Normally, I set root_visibility to public and thread_visbility to unlisted. So the first toot of the thread is public, and all other replies to it are only seen by direct followers.

tag_users: Boolean¶

Do you want to tag the users in the toots? If True, then to toot looks like this:

This toot from Random Person (@random@example.net) had 11 boosts

Sticking the @ in front of the userid will cause that to be interpetted as tagging the user. They will get a notification, most of the time, that they were tagged. If set to False, we omit the @:

This toot from Random Person (random@example.net) had 11 boosts

Without tagging, the person won't know they were mentioned. Sometimes that's what you want.

Code Reference¶

def get_event_end(config: ConfigParser) -> datetime.datetime:
    """
    Calculate event end time from event_start + event_duration.

    Args:
        config: ConfigParser object

    Returns:
        datetime.datetime object with timezone
    """
    event_duration = config.get("mastoscore", "event_duration")

    start_dt = get_event_start(config)
    hours, minutes, seconds = map(int, event_duration.split(':'))
    duration = datetime.timedelta(hours=hours, minutes=minutes, seconds=seconds)
    return start_dt + duration

def get_event_start(config: ConfigParser) -> datetime.datetime:
    """
    Return start date as datetime object. Constructs the datetime from
    event_year, event_month, event_day, event_start (time-only, e.g. "21:00:00"),
    and timezone.

    Args:
        config: ConfigParser object

    Returns:
        datetime.datetime object with timezone
    """
    event_start = config.get("mastoscore", "event_start")
    year = config.getint("mastoscore", "event_year")
    month = config.getint("mastoscore", "event_month")
    day = config.getint("mastoscore", "event_day")
    tz = pytimezone(config.get("mastoscore", "timezone"))

    t = datetime.time.fromisoformat(event_start)
    return tz.localize(datetime.datetime(year, month, day, t.hour, t.minute, t.second))

def get_fetch_window(config: ConfigParser) -> tuple[datetime.datetime, datetime.datetime]:
    """
    Calculate fetch time window: [start - margin, end + margin].

    Args:
        config: ConfigParser object

    Returns:
        Tuple of (oldest_date, newest_date) as datetime objects with timezone
    """
    hours_margin = config.getint("mastoscore", "hours_margin")
    start_dt = get_event_start(config)
    end_dt = get_event_end(config)

    oldest_date = start_dt - datetime.timedelta(hours=hours_margin)
    newest_date = end_dt + datetime.timedelta(hours=hours_margin)

    return oldest_date, newest_date

def get_graph_times(config: ConfigParser) -> tuple[datetime.datetime, datetime.datetime]:
    """
    Return the min and max suitable for graphing. It's the fetch window plus
    15 minutes just to make the graph look better.

    Args:
        config: ConfigParser object

    Returns:
        Tuple of (graph_start, graph_end) as datetime objects with timezone
    """

    start_dt, end_dt = get_fetch_window(config)
    buffer = datetime.timedelta(minutes=15)

    return start_dt - buffer, end_dt + buffer

def get_logger(config: ConfigParser, module:str) -> logging.Logger:
    """
    Get debug level from config. Defaults to logging.WARNING if
    the debug value is not found in the config. Instantiate the
    logger object and return it.

    Args:
        config (ConfigParser): ConfigParser object
        module (str): The name of the module that's doing logging

    Returns:
        Output of logger.getlogger()
    """
    debug_str = config.get("mastoscore", "debug", fallback="WARNING").upper()
    logger = logging.getLogger(module)

    # Convert string to logging level
    log_level = logging.getLevelName(debug_str)
    if not isinstance(log_level, int):
        # Invalid level name, default to WARNING
        log_level = logging.WARNING

    logging.basicConfig(
        format="%(asctime)s %(levelname)-8s %(message)s",
        level=log_level,
        datefmt="%H:%M:%S",
    )
    logger.setLevel(log_level)
    return logger

def read_config(config_file: str) -> ConfigParser | None:
    """
    Read in the config file. Return a `ConfigParser` of config options that
    will be passed around throughout the program.

    Args:
        config_file: The file name of the config file to open.

    Returns:
        If the file can be read and parsed, it returns a `ConfigParser` object.
        If there are any errors, it returns `None`.
    """

    # Don't use get_logger() here, because we haven't read the config file yet.
    logger = logging.getLogger(__name__)
    logging.basicConfig(
        format="%(asctime)s %(levelname)-8s %(message)s",
        level=logging.ERROR,
        datefmt="%H:%M:%S",
    )
    logger.setLevel(logging.ERROR)

    try:
        extinterp = ExtendedInterpolation()
        config = ConfigParser(default_section="mastoscore", interpolation=extinterp)
        with open(config_file, "r") as inifile:
            config.read_file(inifile)
    except Exception as e:
        logger.error(f"Failed to read {config_file}. Bailing")
        logger.error(e)
        return None

    return config