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.

dry_run: Boolean¶

Don't do destructive things. The fetch module will not connect to remote servers if this is True. The post module will print on standard out instead of actually posting.

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 start_time 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.

start_time: 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. Example: "#Monsterdon 2024-11-16 (The Monolith Monsters)"

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¶

117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

def read_config(config_file: str) -> ConfigParser:
    """ 
    Read in the config file. Return a `ConfigParser` of config options that
    will be passed around throughout the program. A few options are mandatory, so this
    will check for their presence and error out if they're missing.

    # Parameters
    - **config*_file*: The file name of the config file to open.

    # Returns

    If all the mandatory options are present, it returns a `ConfigParser`
    object with all the values in it.

    If there are any errors, it returns `None`.
    """

    logger = logging.getLogger(__name__)
    logging.basicConfig(format='%(levelname)s\t%(message)s')
    logger.setLevel(logging.ERROR)

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

    for phase, spec in CONFIG_FORMAT.items():
        # I don't like this behavior of configparser. If you make 'mastoscore' the
        # default section name, and then ask has_section('mastoscore') it returns
        # false. That's weird, but seems to be documented that way. I opened a bug
        # to get documentation updated: https://github.com/python/cpython/issues/132478
        if config.has_section(phase) or phase == "mastoscore":
            # first check if mandatory stuff is there
            for opt in spec['mandatory']:
                if not config.has_option(phase, opt):
                    logger.error(
                        f"Mandatory option {opt} not found in {phase} section of config.")
                    return None
        elif spec['required']:
            logger.error(
                f"Required section '{phase}' missing from config file. Can't continue.")
            return None

    return config