# Mastoboost

![](https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png)

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