126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
# 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 24 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
|