register_feed2toot_app: --name, --user-credentials-file and client-credentials-file CLI options and documentation

This commit is contained in:
Carl Chenet 2020-12-08 19:35:56 +01:00
parent 38f6ddb355
commit 72100f4cac
4 changed files with 98 additions and 33 deletions

View File

@ -31,6 +31,7 @@ import os
# ones. # ones.
extensions = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
'sphinx.ext.autosectionlabel'
] ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.

View File

@ -1,23 +1,34 @@
Configure Feed2toot Configure Feed2toot
=================== ===================
Create credentials for Mastodon
-------------------------------
As a prerequisite to use Feed2toot, you need to authorize a Mastodon app for your account. As a prerequisite to use Feed2toot, you need to authorize a Mastodon app for your account.
Just use the script register_feed2toot_app to register the feed2toot app for your account.:: Just use the script register_feed2toot_app to register the feed2toot app for your account.::
$ ./register_feed2toot_app $ ./register_feed2toot_app
This app generates Mastodon app credentials needed by Feed2toot. This script generates the Mastodon application credentials for Feed2toot.
feed2toot_clientcred.txt and feed2toot_usercred.txt will be written in the current dir /home/chaica/progra/python/feed2toot. feed2toot_clientcred.txt and feed2toot_usercred.txt will be written
One connection is initiated to create the app. in the current directory: /home/me/feed2toot.
WARNING: previous files with the same names will be overwritten.
A connection is also initiated to create the application.
Your password is *not* stored. Your password is *not* stored.
Mastodon instance url (defaults to https://mastodon.social): Mastodon instance URL (defaults to https://mastodon.social): https://framapiaf.org
Mastodon login:chaica@ohmytux.com Mastodon login: toto@titi.com
Mastodon password: Mastodon password:
The feed2toot app was added to your preferences=>authorized apps page
As described above, two files were created. You'll need them in the feed2toot configuration. The app feed2toot was added to your Preferences=>Accounts=>Authorized apps page.
The file feed2toot_clientcred.txt and feed2toot_usercred.txt were created in the current directory.
As described above, two files were created. See the :ref:`Use register_feed2toot_app` section for more options for register_feed2toot_app.
Create Feed2toot configuration
------------------------------
After using register_feed2toot_app, you'll need the credentials in the feed2toot configuration.
In order to configure Feed2toot, you need to create a feed2toot.ini file (or any name you prefer, finishing with the extension .ini) with the following parameters:: In order to configure Feed2toot, you need to create a feed2toot.ini file (or any name you prefer, finishing with the extension .ini) with the following parameters::
@ -88,7 +99,7 @@ For the [rss] section:
- {one field of the rss feed}_pattern: takes a string representing a pattern to match for a specified field of each rss entry of the rss feed, like title_pattern or summary_pattern. - {one field of the rss feed}_pattern: takes a string representing a pattern to match for a specified field of each rss entry of the rss feed, like title_pattern or summary_pattern.
- {one field of the rss feed}_pattern_case_sensitive: either the pattern matching for the specified field should be case sensitive or not. Default to true if not specified. - {one field of the rss feed}_pattern_case_sensitive: either the pattern matching for the specified field should be case sensitive or not. Default to true if not specified.
- no_uri_pattern_no_global_pattern: don't apply global pattern (see above) when no pattern-by-uri is defined in the uri_list. Allows to get all entries of a rss in the uri_list because no pattern is defined so we match them all. Defaults to false, meaning the global patterns will be tried on every rss in the uri_list NOT HAVING specific patterns and so ONLY entries from the specific uri in the uri_list matching the global patterns will be considered. - no_uri_pattern_no_global_pattern: don't apply global pattern (see above) when no pattern-by-uri is defined in the uri_list. Allows to get all entries of a rss in the uri_list because no pattern is defined so we match them all. Defaults to false, meaning the global patterns will be tried on every rss in the uri_list NOT HAVING specific patterns and so ONLY entries from the specific uri in the uri_list matching the global patterns will be considered.
addtags: add the tags from the rss feed at the end of the toot. Defaults to true. - addtags: add the tags from the rss feed at the end of the toot. Defaults to true.
- ignore_ssl: when the uri or uri_list contains an https url with an invalid certificate (e.g an expired one), feed2toot will be unable to get rss content. This option allows to bypass the ssl security to catch the rss content. Defaults to false. - ignore_ssl: when the uri or uri_list contains an https url with an invalid certificate (e.g an expired one), feed2toot will be unable to get rss content. This option allows to bypass the ssl security to catch the rss content. Defaults to false.
For the [hashtaglist] section: For the [hashtaglist] section:
@ -143,8 +154,8 @@ Match specific patterns of rss feeds in the uri_list files
---------------------------------------------------------- ----------------------------------------------------------
You can use specific pattern matching for uri in the uri_list file to filter some of the rss entries of a rss feed. Lets modify the previous file:: You can use specific pattern matching for uri in the uri_list file to filter some of the rss entries of a rss feed. Lets modify the previous file::
https://www.journalduhacker.net/rss|title|hacker,psql https://www.journalduhacker.net/rss|title|hacker,psql
https://carlchenet.com/feed|title|gitlab https://carlchenet.com/feed|title|gitlab
Each line of this file starts with an uri, followed by a pipe (|), followed by the name of the available section to parse (see below), again followed by a pipe (|), followed by patterns, each pattern being separated from the other one by a semi-colon (,). Each line of this file starts with an uri, followed by a pipe (|), followed by the name of the available section to parse (see below), again followed by a pipe (|), followed by patterns, each pattern being separated from the other one by a semi-colon (,).
@ -166,9 +177,3 @@ In you rsslist.txt, just don't give anything else than the needed feed url to ge
The last line of the file above only has the url of a rss feed. All entries from this feed will be tooted. The last line of the file above only has the url of a rss feed. All entries from this feed will be tooted.
How to display available sections of the rss feed
=================================================
Feed2toot offers the **--rss-sections** command line option to display the available section of the rss feed and exits::
$ feed2toot --rss-sections -c feed2toot.ini
The following sections are available in this RSS feed: ['title', 'comments', 'authors', 'link', 'author', 'summary', 'links', 'tags', id', 'author_detail', 'published'].

View File

@ -5,7 +5,7 @@ After the configuration of Feed2toot, just launch the following command::
$ feed2toot -c /path/to/feed2toot.ini $ feed2toot -c /path/to/feed2toot.ini
Run Feed2toot on a regular basis Run Feed2toot on a regular basis
================================= ---------------------------------
Feed2toot should be launched on a regular basis in order to efficiently send your new RSS entries to Mastodon. It is quite easy to achieve by adding a line to your user crontab, as described below:: Feed2toot should be launched on a regular basis in order to efficiently send your new RSS entries to Mastodon. It is quite easy to achieve by adding a line to your user crontab, as described below::
@hourly feed2toot -c /path/to/feed2toot.ini @hourly feed2toot -c /path/to/feed2toot.ini
@ -15,19 +15,19 @@ will execute feed2toot every hour. Or without the syntactic sugar in the global
0 * * * * johndoe feed2toot -c /path/to/feed2toot.ini 0 * * * * johndoe feed2toot -c /path/to/feed2toot.ini
Test option Test option
=========== -----------
In order to know what's going to be sent to Mastodon without actually doing it, use the **--dry-run** option:: In order to know what's going to be sent to Mastodon without actually doing it, use the **--dry-run** option::
$ feed2toot --dry-run -c /path/to/feed2toot.ini $ feed2toot --dry-run -c /path/to/feed2toot.ini
Debug option Debug option
============ ------------
In order to increase the verbosity of what's Feed2toot is doing, use the **--debug** option followed by the level of verbosity see [the the available different levels](https://docs.python.org/3/library/logging.html):: In order to increase the verbosity of what's Feed2toot is doing, use the **--debug** option followed by the level of verbosity see [the the available different levels](https://docs.python.org/3/library/logging.html)::
$ feed2toot --debug -c /path/to/feed2toot.ini $ feed2toot --debug -c /path/to/feed2toot.ini
Populate the cache file without posting tweets Populate the cache file without posting toots
============================================== ---------------------------------------------
Starting from 0.8, Feed2toot offers the **--populate-cache** command line option to populate the cache file without posting to Mastodon:: Starting from 0.8, Feed2toot offers the **--populate-cache** command line option to populate the cache file without posting to Mastodon::
$ feed2toot --populate-cache -c feed2toot.ini $ feed2toot --populate-cache -c feed2toot.ini
@ -43,22 +43,55 @@ Starting from 0.8, Feed2toot offers the **--populate-cache** command line option
populating RSS entry https://www.journalduhacker.net/s/lqswmz populating RSS entry https://www.journalduhacker.net/s/lqswmz
How to display available sections of the rss feed How to display available sections of the rss feed
================================================= -------------------------------------------------
Starting from 0.8, Feed2toot offers the **--rss-sections** command line option to display the available section of the rss feed and exits:: Starting from 0.8, Feed2toot offers the **--rss-sections** command line option to display the available section of the rss feed and exits::
$ feed2toot --rss-sections -c feed2toot.ini $ feed2toot --rss-sections -c feed2toot.ini
The following sections are available in this RSS feed: ['title', 'comments', 'authors', 'link', 'author', 'summary', 'links', 'tags', id', 'author_detail', 'published']. The following sections are available in this RSS feed: ['title', 'comments', 'authors', 'link', 'author', 'summary', 'links', 'tags', id', 'author_detail', 'published'].
Using syslog Using syslog
============ ------------
Feed2toot is able to send its log to syslog. You can use it with the following command:: Feed2toot is able to send its log to syslog. You can use it with the following command::
$ feed2toot --syslog=WARN -c /path/to/feed2toot.ini $ feed2toot --syslog=WARN -c /path/to/feed2toot.ini
Limit number of rss entries published at each execution Limit number of rss entries published at each execution
======================================================= -------------------------------------------------------
If you want to limit the number of rss entries published at each execution, you can use the --limit CLI option. If you want to limit the number of rss entries published at each execution, you can use the --limit CLI option.
$ feed2toot --limit 5 -c /path/to/feed2toot.ini $ feed2toot --limit 5 -c /path/to/feed2toot.ini
The number of posts to Mastodon will be at 5 posts top with this CLI option. The number of posts to Mastodon will be at 5 posts top with this CLI option.
Use register_feed2toot_app
==========================
You need a Mastodon app associated to a user on the Mastodon instance. The script register_feed2toot_app will create an app for Feed2toot and upload it on the specified Mastodon instance.
Primary usage ::
$ register_feed2toot_app
Possible CLI options:
- use the **--client-credentials-file** option to change the filename in which the client credentials are stored (defaults to feed2toot_clientcred.txt)
- use the **--user-credentials-file** option to change the filename in which the user credentials are stored (defaults to feed2toot_usercred.txt)
- use the **--name** to change the Mastodon app name (defaults to feed2toot)
Example with full options and full output::
$ ./register_feed2toot_app --user-credentials-file f2tusercreds.txt --client-credentials-file f2tclientcreds.txt --name f2t
This script generates the Mastodon application credentials for Feed2toot.
f2tclientcreds.txt and f2tusercreds.txt will be written
in the current directory: /home/me/feed2toot/scripts.
WARNING: previous files with the same names will be overwritten.
A connection is also initiated to create the application.
Your password is *not* stored.
Mastodon instance URL (defaults to https://mastodon.social): https://framapiaf.org
Mastodon login: toto@titi.com
Mastodon password:
The app f2t was added to your preferences=>authorized apps page.
The file f2tclientcreds.txt and f2tusercreds.txt were created in the current directory.

View File

@ -14,13 +14,34 @@
# You should have received a copy of the GNU General Public License # You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/> # along with this program. If not, see <http://www.gnu.org/licenses/>
from argparse import ArgumentParser
from getpass import getpass from getpass import getpass
from os import getcwd from os import getcwd
from os import linesep
from os import sep
from mastodon import Mastodon from mastodon import Mastodon
from mastodon.Mastodon import MastodonIllegalArgumentError from mastodon.Mastodon import MastodonIllegalArgumentError
import sys import sys
print('\nThis script generates the Mastodon application credentials for Feed2toot.\nfeed2toot_clientcred.txt and feed2toot_usercred.txt will be written\nin the current directory: {cwd}.\nA connection is initiated to create the application.\nYour password is *not* stored.\n'.format(cwd=getcwd())) __version__ = '0.2'
epilog = 'For more information: https://feed2toot.readthedocs.io'
description = 'Create a Mastodon app for Feed2toot'
parser = ArgumentParser(prog='register_feed2toot_app',
description=description,
epilog=epilog)
parser.add_argument('--version', action='version', version=__version__)
parser.add_argument('--client-credentials-file', dest='clientcredfile', help='the name of the client credentials for the Mastodon app', default='feed2toot_clientcred.txt')
parser.add_argument('--user-credentials-file', dest='usercredfile', help='the name of the user credentials for the Mastodon app', default='feed2toot_usercred.txt')
parser.add_argument('--name', help='the name of the Mastodon app', default='feed2toot')
opts = parser.parse_args()
clientcredfile=opts.clientcredfile
usercredfile=opts.usercredfile
headline = '{linesep}This script generates the Mastodon application credentials for Feed2toot.{linesep}{clientcredfile} and {usercredfile} will be written{linesep}in the current directory: {cwd}.{linesep}WARNING: previous files with the same names will be overwritten.{linesep}{linesep}A connection is also initiated to create the application.{linesep}Your password is *not* stored.{linesep}'.format(linesep=linesep, clientcredfile=clientcredfile, usercredfile=usercredfile, cwd=getcwd())
print(headline)
# get the instance # get the instance
instance = input('Mastodon instance URL (defaults to https://mastodon.social): ') instance = input('Mastodon instance URL (defaults to https://mastodon.social): ')
@ -45,20 +66,25 @@ while not userok:
# get the password # get the password
password = getpass(prompt='Mastodon password: ') password = getpass(prompt='Mastodon password: ')
Mastodon.create_app( Mastodon.create_app(
'feed2toot', opts.name,
api_base_url=instance, api_base_url=instance,
to_file = '{cwd}/feed2toot_clientcred.txt'.format(cwd=getcwd()) to_file = '{cwd}{sep}{clientcredfile}'.format(cwd=getcwd(), sep=sep, clientcredfile=clientcredfile)
) )
mastodon = Mastodon(client_id = '{cwd}/feed2toot_clientcred.txt'.format(cwd=getcwd()), mastodon = Mastodon(client_id = '{cwd}{sep}{clientcredfile}'.format(cwd=getcwd(), sep=sep, clientcredfile=clientcredfile),
api_base_url=instance) api_base_url=instance)
try: try:
mastodon.log_in( mastodon.log_in(
user, user,
password, password,
to_file = '{cwd}/feed2toot_usercred.txt'.format(cwd=getcwd()) to_file = '{cwd}{sep}{usercredfile}'.format(cwd=getcwd(), sep=sep, usercredfile=usercredfile)
) )
except MastodonIllegalArgumentError as err: except MastodonIllegalArgumentError as err:
print(err) print(err)
sys.exit('\nI guess you entered a bad login or password.\n') sys.exit('{linesep}I guess you entered a bad login or password.{linesep}'.format(linesep=linesep))
print('feed2toot was added to your preferences=>authorized apps page.')
summary = '{linesep}The app {appname} was added to your Preferences=>Accounts=>Authorized apps page.{linesep}The file {clientcredfile} and {usercredfile} were created in the current directory.{linesep}'.format(appname=opts.name,
linesep=linesep,
clientcredfile=clientcredfile,
usercredfile=usercredfile)
print(summary)
sys.exit(0) sys.exit(0)