Skip to main content

Monitor RSS feeds for keywords and act on matching results. A special project of the Freedom of the Press Foundation.

Project description

Track The News

trackthenews is the script that powers @FOIAfeed, a Twitter bot that monitors news outlets for reporting that incorporates public records laws like the Freedom of Information Act (FOIA), and tweets links to and excerpts from matching articles. The underlying software can track any collection of RSS feeds for any keywords.

If you want to run your own instance of trackthenews, you can download and install the package, and run its built-in configuration process. It can be installed with pip:

Python 3.9 is what we currently test against, though it may work with other versions.

pip3 install trackthenews

or by cloning the GitHub repository and running setup.py:

python3 setup.py install

Once it is installed, you can create a configuration by running the following command in the appropriate directory:

trackthenews --config

By default, the script will place all configuration files in a new ttnconfig folder in your current working directory, but you can also designate a directory for it to use.

python3 trackthenews --config ~/foo/bar/path

That configuration process will create the necessary files and walk you through setting up a Twitter bot for matching stories. After it is configured, you'll need to use a text editor to add the matchwords and RSS feeds to their respective files.

Sample RSS feed and matchword files can be found in the project's GitHub repo. The RSS feed file is a JSON array of objects corresponding to each feed. Each object requires a url field, and should also have an outlet field.

The next two fields are optional: if you know the feed uses redirect URLs, you may set redirectLinks to true and the script will attempt to follow those redirects to store and tweet canonical URLs; if the feed uses URLs that depend on query- or hash-strings to display correctly—basically, if the content relies on text in the URL bar after a ? or #—you can set delicateURLs to true and the script will leave the URLs exactly as is.

Once you've got everything set up, you can run the program without the --config flag to check for matching articles.

trackthenews

If you designated a custom installation directory, or if you're running it from another directory (or a cron job, for example) you will need to designate the directory in which the configuration files are installed.

trackthenews ~/foo/bar/path

Settings, such as the background color for new posts, the font, and the user-agent, are all located in config.yaml, in the designated configuration directory.

How it works

Most of the script is dedicated to the Article class.

  • Articles are created based on inputs. Currently those inputs are RSS feeds, which are stored in rssfeeds.json, but in future versions other inputs will include direct URLs, news APIs, Twitter feeds, or scraped pages.
  • A series of Article methods then scrape and isolate the contents of each article (currently that cleanup is done with a Python port of Readability, but future versions may incorporate some per-site parsing), check whether it's suitable for posting, and then prepare images for tweeting.
  • Finally, the Article tweets itself.

All articles are recorded in a sqlite database.

Advanced feature: blocklist

In some cases, you may wish to suppress articles from being posted, even though they would otherwise match. You can do so by writing two new functions, check_article and check_paragraph, and placing them in a file named blocklist.py in the configuration directory:

  • check_article takes an Article (and so has access to its outlet, title, and url) and should return True for any article that should be skipped in its entirety.
  • check_paragraph takes an Article and an individual matching paragraph and should return True for any paragraph that should be skipped (if other paragraphs match, the article will still be posted, but without the skipped paragraphs).

Development

Quick Start

poetry env use 3.9  # Necessary if you have a different default python version
poetry install
poetry run trackthenews sample_project
# Follow the setup script instructions
cat sample_project/matchlist-sample.txt > sample_project/matchlist.txt
cat sample_project/rssfeeds-sample.json > sample_project/rssfeeds.json
poetry run trackthenews sample_project

Detailed Instructions

To develop trackthenews, clone the repository and install the package using poetry and run the CLI tool:

# Ensure you're using Python 3.9
poetry env use 3.9
# This will create a virtual environment and install trackthenews and its dependencies
poetry install --with=dev
# This will run the setup script
poetry run trackthenews sample_project

On first run this will take you through the interactive setup process. Follow the instructions. You will need a Twitter account with application keys and/or a Mastodon account.

When the setup process is complete, the configuration for your bot will live in the sample_project directory. Fill out the matchlist.txt, matchlist_case_sensitive.txt, and rssfeeds.json files or copy configuration from the provided samples:

cat sample_project/matchlist-sample.txt > sample_project/matchlist.txt
cat sample_project/rssfeeds-sample.json > sample_project/rssfeeds.json

matchlist_case_sensitive.txt is optional and we don't provide a sample.

Now run the bot:

poetry run trackthenews sample_project

Linters

We check that all code conforms to black, flake8, and isort. To run these checks locally:

poetry run black --check .  # To automatically fix issues, exclude --check flag
poetry run flake8
poetry run isort --check-only --diff .  # To automatically fix issues, exclude --check-only and --diff flag

We also provide the following makefile shortcuts to run these commands:

make black
make flake8
make isort
make black-fix  # Automatically fix issues
make isort-fix  # Automatically fix issues
make all        # Run all three checks (check only, no fixes)

License

MIT.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

trackthenews-0.3.tar.gz (285.1 kB view details)

Uploaded Source

Built Distribution

trackthenews-0.3-py3-none-any.whl (282.5 kB view details)

Uploaded Python 3

File details

Details for the file trackthenews-0.3.tar.gz.

File metadata

  • Download URL: trackthenews-0.3.tar.gz
  • Upload date:
  • Size: 285.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.3 Darwin/23.5.0

File hashes

Hashes for trackthenews-0.3.tar.gz
Algorithm Hash digest
SHA256 55c5411524a25b45f47d59485537551696978c7d7e5e9e77c1ca1ca95ab7662a
MD5 c8cc1d4b6970eeb405a12da8c91ddbb5
BLAKE2b-256 5de4ca8c4a420e8301b206268a1097455848b7153c580750d049f662233778e1

See more details on using hashes here.

File details

Details for the file trackthenews-0.3-py3-none-any.whl.

File metadata

  • Download URL: trackthenews-0.3-py3-none-any.whl
  • Upload date:
  • Size: 282.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.3 Darwin/23.5.0

File hashes

Hashes for trackthenews-0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 4364a3bdd1d13720cdc0d522f89ee721915d48cd023961740284fb804f84905f
MD5 2c26d4f4ee730eb294e3a417a904cdb9
BLAKE2b-256 ea02843bad0384bf73e4845dd135e73de35ad3e99994c022d55fb06de2eb8942

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page