Merge pull request #45 from robertoszek/develop

Bump to v0.8.7

.gitignore

@@ -12,3 +12,4 @@ error.log
 /coverage.xml
 /config.yml.bak
 **/__pycache__/
+/site

CHANGELOG.md

@@ -1,3 +1,12 @@
+## [0.8.7] - 2021-05-01
+## Added
+- ```delay_post``` mapping, for setting how long to wait (in seconds) between each post request to avoid hitting rate limits of the target Fediverse instance
+- ```hashtags``` mapping (list), for filtering out tweets which don't match any of them
+- ```tweet_ids``` mapping, for listing specific tweets to retrieve and post on the Fediverse account
+## Enhancements
+- Provide a more meaningful exception message when an HTTP error code 422 is returned when updating the Fediverse profile
+- Referenced more directly in the documentation the need to use an account ID instead of a username when targeting a Mastodon instance
+
 ## [0.8.6] - 2021-02-27
 ## Fixed
 - Log file handler not being attached when running as a module

README.md

@@ -2,6 +2,7 @@
 
 [![Build Status](https://travis-ci.com/robertoszek/pleroma-bot.svg?branch=develop)](https://travis-ci.com/robertoszek/pleroma-bot)
 [![Version](https://img.shields.io/pypi/v/pleroma-bot.svg)](https://pypi.org/project/pleroma-bot/)
+[![AUR version](https://img.shields.io/aur/version/python-pleroma-bot)](https://aur.archlinux.org/packages/python-pleroma-bot)
 [![codecov](https://codecov.io/gh/robertoszek/pleroma-bot/branch/master/graph/badge.svg?token=0c4Gzv4HjC)](https://codecov.io/gh/robertoszek/pleroma-bot)
 [![Python 3.6](https://img.shields.io/badge/python-3.6+-blue.svg)](https://www.python.org/downloads/release/python-360/)
 [![Requires.io (branch)](https://img.shields.io/requires/github/robertoszek/pleroma-bot/master)](https://requires.io/github/robertoszek/pleroma-bot/requirements/?branch=master)
@@ -130,6 +131,9 @@ users:
   include_rts: false
   # (optional) If replies are to be also posted in the Fediverse account. By default they are included
   include_replies: false
+  # (optional) List of hashtags to use for filtering out tweets which don't include any of them
+  hashtags:
+    - sponsored
   # (optional) How big attachments can be before being ignored and not being uploaded to the Fediverse post
   # Examples: "30MB", "1.5GB", "0.5TB"
   file_max_size: 500MB

docs/contribute/contributing.md

@@ -0,0 +1,14 @@
+# Contributing
+
+## Code
+
+Patches, pull requests, and bug reports are more than [welcome](https://github.com/robertoszek/pleroma-bot/issues/new/choose), please keep the style consistent with the original source.
+
+## Translations
+
+We're looking for translators for other languages! You can get the PO template from [here](https://github.com/robertoszek/pleroma-bot/blob/develop/pleroma_bot/locale/pleroma_bot.pot) and create a translation with an editor such as [Poedit](https://poedit.net/).
+
+| Language       | Status                                                  | Translator                                    |
+|:--------------:|:-------------------------------------------------------:|:---------------------------------------------:|
+| en_US          | :octicons-check-circle-24: Complete                     | [robertoszek](https://github.com/robertoszek) |
+| es_ES          | :octicons-check-circle-24: Complete                     | [robertoszek](https://github.com/robertoszek) |

docs/gettingstarted/automateit.md

@@ -0,0 +1,125 @@
+# Automate it
+
+Great, now you're all ready to go, you have installed ```pleroma-bot``` and created a config for your needs. But where's the fun in all of that if you have to run it manually everytime, right?
+
+## Skip first run checks
+
+It's worth noting that ```pleroma-bot``` accepts the flag ```--skipChecks```, which will ignore all of the first run checks (e.g. no user folder found, no posts/toots in the target Fediverse account, etc). Most importantly, if you pass this argument you can rest assured no input will be asked during the run. Which makes it perfect for our purposes of running it on a timer with no manual intervention.
+
+```console
+$ pleroma-bot --skipChecks
+```
+
+
+## Cron
+
+Fan favourite and well-known. 
+If you have trouble figuring out cron schedule expressions, you can use this [site](https://crontab.guru/) to analyze them.
+
+First, start by editing your current crontab:
+
+```console
+$ crontab -e
+```
+
+In our example, we'll add some lines at the end of the crontab, which will:
+
+* Post new tweets **(every 10 min.)**
+* Update profile info **(everyday at 6:15 AM)**
+
+
+=== "Using PyPi"
+    !!! info "Feel free to omit "```1> /dev/null```" Its main use here is to drop any output from the standard output, in case you have configured cron to send you emails if any commands generate output"
+
+    * System-wide:
+
+    ```bash
+    # Post tweets every 10 min
+    */10 * * * * pleroma-bot --noProfile --skipChecks -c /path/to/config.yml -l /path/to/error.log 1> /dev/null
+
+    # Update pleroma profile with Twitter info every day at 6:15 AM
+    15 6 * * * pleroma-bot --skipChecks -c /path/to/config.yml 1> /dev/null
+    ```
+
+    * Or if you're using a [virtual environment :octicons-file-code-24:](https://docs.python.org/3/tutorial/venv.html):
+
+    ```bash
+    # Post tweets every 10 min
+    */10 * * * * cd /path/to/your/venv/ && . bin/activate && pleroma-bot --noProfile --skipChecks -c /path/to/config.yml -l /path/to/error.log
+
+    # Update pleroma profile with Twitter info every day at 6:15 AM
+    15 6 * * * cd /path/to/your/venv/ && . bin/activate && pleroma-bot --skipChecks -c /path/to/config.yml -l /path/to/error.log
+    ```
+
+
+=== "Using AUR package"
+    !!! info "You can freely omit ```1> /dev/null```. Its main use here is to drop any output from the standard output, in case you have configured cron to send you emails if any commands generate output"
+
+    ```bash
+    # Post tweets every 10 min
+    */10 * * * * pleroma-bot --noProfile --skipChecks -c /path/to/config.yml -l /path/to/error.log
+
+    # Update pleroma profile with Twitter info every day at 6:15 AM
+    15 6 * * * pleroma-bot --skipChecks -c /path/to/config.yml -l /path/to/error.log
+    ```
+
+=== "Using Git"
+    !!! info "You can freely omit ```1> /dev/null```. Its main use here is to drop any output from the standard output, in case you have configured cron to send you emails if any commands generate output"
+
+    ```bash
+    # Post tweets every 10 min
+    */10 * * * * cd /path/to/cloned/repo/ && python3 -m pleroma_bot.cli --noProfile --skipChecks -c /path/to/config.yml -l /path/to/error.log
+
+    # Update pleroma profile with Twitter info every day at 6:15 AM
+    15 6 * * * cd /path/to/cloned/repo/ && python3 -m pleroma_bot.cli --skipChecks -c /path/to/config.yml -l /path/to/error.log
+    ```
+
+## Systemd timers
+
+You can achieve the same results with [Systemd timers](https://www.freedesktop.org/software/systemd/man/systemd.timer.html). The choice of which one to use (cron or systemd timers) it's really up to you, basically which one fits more your needs.
+
+Create a service file with the following content:
+### /etc/systemd/system/[email protected]
+```bash
+[Unit]
+Description=Bot that mirrors Twitter accounts on the Fediverse
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/pleroma-bot --skipChecks -c /path/to/config.yml -l /path/to/error.log %i
+```
+
+Also, create 2 timer files with the following content:
+### /etc/systemd/system/pleroma-bot-tweets.timer
+```bash
+[Unit]
+Description=Run pleroma-bot every 10min
+
+[Timer]
+[email protected]
+OnCalendar=*:0/10
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+### /etc/systemd/system/pleroma-bot-profile.timer
+```bash
+[Unit]
+Description=Run pleroma-bot with noProfile at 6:15am
+
+[Timer]
+[email protected]
+OnCalendar=*-*-* 6:15:00
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+Enable and start the timers:
+```console
+# systemctl enable pleroma-bot-profile.timer
+# systemctl --user start pleroma-bot-profile.timer
+# systemctl enable pleroma-bot-tweets.timer
+# systemctl --user start pleroma-bot-tweets.timer
+```

docs/gettingstarted/beforerunning.md

@@ -0,0 +1,61 @@
+# Before running
+
+If you haven't already, you need to [apply for a Twitter developer account](https://developer.twitter.com/en/apply-for-access).
+
+The process involves some review of the developer account application by Twitter and it's very likely you'll be asked for some details pertaining your usecase. It usually doesn't take longer than a day or two to complete the application, the back and forth is mostly automated on their part.
+
+## Twitter tokens
+
+Once you have a Twitter developer account, you need to access your [dashboard](https://developer.twitter.com/en/portal/dashboard) and create a new project (so your app has V2 access) and also create a new app associated to that new project.
+
+Now, enter your new application "Keys and tokens" section, copy and safely store all of your tokens.
+
+![Keys and tokens](/pleroma-bot/images/keys.png)
+
+* The [Bearer Token](https://developer.twitter.com/en/docs/authentication/api-reference/token) is usually enough for most usecases when running ```pleroma-bot```
+
+
+However, if you plan on retrieving tweets from an account with **protected** tweets, you'll also need the following:
+
+!!! warning "Keep in mind your Twitter developer account needs to **follow** or be the owner of the protected account for this to work"
+
+* Consumer Key and Secret (or API key & secret)
+* Access Token Key and Secret
+
+Alternatively, you can obtain the Access Token and Secret by running [this](https://github.com/joestump/python-oauth2/wiki/Twitter-Three-legged-OAuth-Python-3.0) locally, while being logged in with a Twitter account which follows or is the owner of the protected account.
+
+## Fediverse tokens
+
+You also need to obtain the bearer tokens for the Fediverse account(s) you plan to use for mirroring.
+
+*While* being logged in as the Fediverse account, [follow the instructions on this site](https://tinysubversions.com/notes/mastodon-bot/) and enter:
+
+* Your server/instance URL (**without** *the protocol at the beginning, e.g. https://*)
+* The name of your app (doesn't really matter which one you choose, it's just a meaningful name so it's easy *for you* to identify)
+* Scopes: ```read write```
+
+
+When you're done with the last step (as in, running the cURL command):
+
+```bash
+$ curl -F grant_type=authorization_code \
+       -F redirect_uri=urn:ietf:wg:oauth:2.0:oob \ 
+       -F client_id=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
+       -F client_secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
+       -F code=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
+       -X POST https://yourinstance.fedi/oauth/token
+```
+You'll get a response similar to this:
+```json
+{
+    "access_token":"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
+    "created_at":99999999,
+    "expires_in":99999,
+    "me":"https://yourinstance.fedi/users/yourfediuser",
+    "refresh_token":"ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ",
+    "scope":"read write",
+    "token_type":"Bearer"
+}
+```
+
+Save the value of ```access_token```. *That* is the bearer token generated for that Fediverse account, you'll need it in the next section.