4.1 KiB
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.