Mastoboost

Mastoboost is licensed under CC-BY-NC-SA 4.0. See LICENSE file for details.

Introduction

Mastoboost is a specialized Mastodon bot which favourites and reblogs statuses which contain a given hashtag.

As this is a bot, do make sure that bot accounts are allowed by Mastodon instance which Mastoboost will use, and that the account it uses clearly states that it is a bot account.

Restrictions

Time restriction

Mastoboost is designed to be run in batches rather than as a daemon. As hashtag timelines may grow indefinitely long, a single Mastoboost execution could run indefinitely too.

In order to avoid this, Mastoboost has the --hours option, which restricts how far back in hours it can go back on the timeline; statuses older that this many hours will be ignored.

By default Mastoboost has a 6 hours limit. It may or may not be appropriate for your use case, but remember that as it crawls further back in time, it will run longer and use more resources from the instance it queries. This may lead to the instance throttling Mastoboost, or even disabling the accout it uses!

Self-restriction

If Mastoboost sees a status that the account has already favourited and reblogged, it will stop there even if the time restriction has not been met. This allows Mastoboost to detect when it has already processed a status, thus when it can confidently stop.

You can bypass this behavior explicitly with --diligent.

Language restriction

By default Mastoboost does not care about languages.

However, it is possible to restrict it to some specific language(s) by specifying at least one --lang LL option where LL is the language's two-letter designation, such as en or fr.

It is also possible to exclude one or more languages, instead of restricting, by specifying option --lang-exclude alongside --lang option(s).

There is no way to both specify some languages and exclude others, as it amounts to specifying the difference between the two lists of languages.

Reverse run

You can run Mastoboost with its usual arguments plus --reverse.

This will make it unfavourite and unreblog instead of favouriting and reblogging. It is intended for instance to correct a wrong run.

NOTE: when under --reverse, language restrictions do not apply, so that a previous run with wrong language settings can be undone.

Dry run

You can run Mastoboost with its usual arguments (including --reverse) plus --dry-run.

This will prevent Mastodon from actually favouriting and reblogging (or, if under --reverse, from unfavouriting and unblogging).

Together with --log-level, it can be used to analyze the decisions of Mastoboost and assess which statuses it would actually operate on.

Requirements

To use this bot, you'll need a computer which:

• is connected to the Internet
• runs Python 3 (3.9 tested, might work with earlier versions)
• can run periodic tasks (e.g., a Linux machine with a cron daemon)
• has pipenv installed, or lets you install it

If you need to install pipenv yourself, run

pip install pipenv

Installation

You can either clone this repository or simply create an empty directory and copy the following files in it:

Pipfile
Pipfile.lock
src/mastoboost.py

In either case, go to the directory which contains Pipfile and run

`pipenv sync`

This will guarantee that your installation uses the versions of the dependencies that the project uses.

If you want to try the newest dependencies, instead of pipenv sync you can run

`pipenv install`

Development

The Pipfile lists the development dependencies. You can pipenv sync -d (or pipenv install -d) to install them.

Before committing, the code should be run through

`pipenv run black src/*.py`
`pipenv run prospector -w bandit -w vulture -w mypy src/*.py`

It should show 0 messages found.

The code should also be run through

`pipenv run radon cc -s --total-average src/*.py`

New commits should always have an average complexity at most equal to that of their parent commit.

END OF THIS README