Add configurable post-process hooks

On Mon, Jan 21, 2013 at 11:16:58PM -0800, Arun Persaud wrote:
> but I was wondering if there is any chance to add some hooks, so
> that the user can modify the feed before it gets send, something
> that takes the url, uid, and other interesting information and
> returns the body of the feed that should get emailed.

This is not quite what he asked for (e.g., I don't pass the URL
explicitly, the hook should return the full message instead of just
payload, ...), but I think it get's the job done.

Signed-off-by: W. Trevor King <wking@tremily.us>

email: Don't assume `extra_headers` has content in get_message()

The default is None, so we should at least handle that case
gracefully.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: Remove the for loop variable `e` for a clean namespace

Otherwise:

  >>> import rss2email.feed
  >>> print([x for x in dir(rss2email) if not x.startswith('_')])
  ['Feed', 'e']

which might confuse people ;).

Signed-off-by: W. Trevor King <wking@tremily.us>

main: Catch command-less case for Python 3.3

In Python 3.2, the argument parser raises an error if no subcommand is
listed on the command line.  This does not seem to be the case with
Python 3.3.0, and the changed behavior seems to have been a side
effect of this:

  http://hg.python.org/cpython/rev/cab204a79e09
  changeset:   70741:cab204a79e09
  user:        R David Murray <rdmurray@bitdance.com>
  date:        Thu Jun 09 12:34:07 2011 -0400
  summary:     #10424: argument names are now included in the missing argument mes

Anyhow, it's easy enough to catch the new behaviour in rss2email and
print the appropriate error.

Reported-by: Dmitry Bogatov <KAction@gnu.org>
Signed-off-by: W. Trevor King <wking@tremily.us>

rss2email: Sort __contributors__ by first name and add missing folks

This brings __contributors__ in line with the auto-generated AUTHORS.
I'm not convinced that listing __contributors__ in a Python-parsable
manner is worth the trouble, but I'll leave it in for now.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed|feeds: Update datafile format to version 2

We may want to store additional data about previously seen entries
besides our possibly auto-generated ID.  Convert the `seen` mapping
from:

  entry_id -> our_id

to:

  entry_id -> {'id': our_id}

Signed-off-by: W. Trevor King <wking@tremily.us>

r2e.1: Update ConfigParser URL after PEP 430

Signed-off-by: W. Trevor King <wking@tremily.us>

r2e.1: Update __contributors__ location and direct bugs to the mailing list

Signed-off-by: W. Trevor King <wking@tremily.us>

r2e.1: Update maintainer from Lindsey to me.

This should have happened in:

  commit 6460e8738b5e7c66df6c2143e8a29c048cf308bd
  Author: W. Trevor King <wking@tremily.us>
  Date:   Fri Nov 9 07:46:17 2012 -0500

    Change maintainer from Lindsey to Trevor.

Signed-off-by: W. Trevor King <wking@tremily.us>

feeds: Follow the the XDG Base Directory Specification

This splits config files and data files into different directories (by
default), so we no longer need an rss2email subdirectory (we only have
one config file and one data file).  The default config file is now
~/.config/rss2email.cfg and the default data file is now
~/.local/share/rss2email.json.

Signed-off-by: W. Trevor King <wking@tremily.us>

feeds: Use JSON instead of Pickle for storing dynamic feed state

It's safer, more portable, and possibly faster.  I've also added
version information to the data file for easier future upgrades.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: Split entry link extraction out into Feed._get_entry_link

Now other methods can all access the same link, without having to
extract it in _process_entry and pass the extracted link around
explicitly.  Currently, nothing special happens during link
extraction, but the new method helps future proof us.

Signed-off-by: W. Trevor King <wking@tremily.us>

Ran update-copyright.py

Signed-off-by: W. Trevor King <wking@tremily.us>

main: Add missing `# Copyright` tag for update-copyright.py

Signed-off-by: W. Trevor King <wking@tremily.us>

version: Add get_versions and teach rss2email --full-version

This makes it easier for users to submit useful bug reports.

Signed-off-by: W. Trevor King <wking@tremily.us>

main: Add an explicit --version argument.

Use an explicit `version` action instead of the undocumented (and
deprecated) `version` keyword to ArgumentParser [1,2].

[1]: http://docs.python.org/3.3/library/argparse.html#action
[2]: http://docs.python.org/3.3/library/argparse.html#upgrading-optparse-code

Signed-off-by: W. Trevor King <wking@tremily.us>

error: Strip trailing whitespace in module docstring

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: Raise the new InvalidFeedConfig on missing feed.url

You can't fetch a feed without a URL.  This new error message makes
the cause explicit, compared to the somewhat ambigious former error
messages:

  fetch $NAME (None -> $TO)
  process $NAME (None -> $TO)
  HTTP status 200
  could not get HTTP headers: $NAME (None -> $TO)
  unrecognized version: $NAME (None -> $TO)
  sax parsing error: <unknown>:2:0: no element found: $NAME (None -> $TO)

I was getting URL-less feeds when I clobbered my
~/.config/rss2email/config [1], removing some newer entries.  However,
because I never deleted the feeds explicitly, they were repopulated
(without their URL) from ~/.config/rss2email/feeds.dat, and subsequent
runs generated the above error.

[1]: The clobbering was related to my dotfile management, and not due
to an rss2email issue.

Signed-off-by: W. Trevor King <wking@tremily.us>

test:disqus: add a Disqus feed for testing

This raised a few issues with the handling of missing IDs, which I've
just fixed.  The new test will make sure we keep exercising these code
paths.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: fix id fallback in Feed._process_entry

The old `entry['id'] or _id` raised a KeyError when the entry lacked
an ID.  The new `entry.get('id', _id)` falls back appropriately.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: use hashlib.sha1 for fallback IDs in Feed._get_entry_id

This fixes what I broke in

  commit 0fc2ff4465d741823b3dceebcfcf3a98a0081522
  Author: W. Trevor King <wking@tremily.us>
  Date:   Thu Oct 4 08:33:32 2012 -0400

    Cleanup global module configuration.

  diff --git a/rss2email.py b/rss2email.py
  index 216c13d..3919bd7 100755
  --- a/rss2email.py
  +++ b/rss2email.py
  ...
  -hash = hashlib.md5
  ...

I've come back with sha1 instead of md5, mostly because that's what
Git uses ;).  We don't migrate recorded IDs from the old configuration
method, so the change from md5 to sha1 shouldn't affect anyone.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: fix Feed._get_entry_content unpacking in Feed._get_entry_title

_get_entry_content returns a single dict, but _get_entry_id had been
unpacking it as if it was an object with a `content` attribute.

Also convert HTML to text before extracting the title, to avoid things
like `<p>In the beginning...` in the title.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: fix Feed._get_entry_content unpacking in Feed._get_entry_id

_get_entry_content returns a single dict, but _get_entry_id had been
unpacking it as if it was a length-two tuple.

Signed-off-by: W. Trevor King <wking@tremily.us>

feed: fix the `type` key returned by Feed._get_entry_content

The previous version used the Python object `type` where it should
have used the string 'type'.  I hadn't caught the bug before because
none of my example feeds fell through that far.

Signed-off-by: W. Trevor King <wking@tremily.us>

test:gmane:README: fix "feed.atom" -> "feed.rss" typo

Probably a copy-paste error from seeding with
test/allthingsrss/README.

Signed-off-by: W. Trevor King <wking@tremily.us>

Link to Debian & Ubuntu package pages

(instead of search)

Signed-off-by: Etienne Millon <me@emillon.org>

Don't put UTF8 last in the list of encodings

Sometimes, BIG5 will be selected for english text if quotes make it
not representable in ASCII. See [1] for the original bug report.

This default list is arguably European-centric but at least it documents a good
amount of the alternative encodings.

[1]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=659920

Reported-by: James Cloos <cloos@jhcloos.com>
Signed-off-by: Etienne Millon <me@emillon.org>

Change default email address

As discussed in [1], user@rss2email.invalid is less verbose and simpler to
understand.

[1]: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=464077

Reported-by: Noah Slater <nslater@bytesexual.org>
Signed-off-by: Etienne Millon <me@emillon.org>

COPYING: whitespace changes to match the new gnu.org download

No sense in preserving differences between this branch and the version
in the `license` branch.

Signed-off-by: W. Trevor King <wking@tremily.us>

CONTRIBUTING.md: describe rss2email's GPLv{2,3}

We want people using s-o-b to be very clear about which licenses they
should use for rss2email submissions.

Signed-off-by: W. Trevor King <wking@tremily.us>

Merge remote-tracking branch 's-o-b/contributing-github'

CONTRIBUTING.md: point to external docs on GitHub

This translates CONTRIBUTING (from the `contributing` branch) into
Markdown using a GitHub URL for the link.  Merging this into your
project will set it up to use GitHub's CONTRIBUTING infrastructure,
and will be used to notify users creating issues and pull requests
[1].

GitHub's blob URL syntax is [2]:

  https://github.com/<user>/<project>/blob/<commit-SHA-1>/Path/To/File

Like CONTRIBUTING, CONTRIBUTING.md is also released under the CC0
Universal license (see the `license` branch for full text).

[1]: https://github.com/blog/1184-contributing-guidelines
[2]: https://help.github.com/articles/how-do-i-get-a-permanent-link-from-file-view-to-permanent-blob-url

Signed-off-by: W. Trevor King <wking@tremily.us>

CONTRIBUTING: point to external docs (for non GPLv2= projects)

If a project wants to use the DCO/s-o-b workflow, but can't because of
license incompatibility, they can include this blurb pointing towards
the external documentation.  To avoid licensing issues with this
CONTRIBUTING file itself, I'm releasing it under the Creative Commons
CC0 1.0 Universal license (see the `license` branch for full text).

If you use this in your project, you'll probably want to adjust the
URL to point to somewhere more dependable.  It's annoyingly long, but
you should include the blob hash (or a higher level hash like the
commit hash) in your URL to make it absolutely clear which version of
the documentation you were using in your project at a particular time.

Signed-off-by: W. Trevor King <wking@tremily.us>

rss2email: raise error on import with Python < 3.2.

rss2email won't work with older Pythons.  Avoid user confusion due to
API-breakage error messages [1] by bailing explicitly up front.

[1]; http://forums.macrumors.com/showthread.php?t=1216694

CHANGELOG: summarize changes since v2.71

test: record sender as SENT BY (not SENT TO) in *.expected

test:gmane: add Gmane feed for RSS testing

The weird indentation is because Gmane wraps the descriptions in <pre>
tags (to preserve formatting in the initial email).  html2text is
converting the description to Markdown, so it inserts a leading 4
spaces for preformatted blocks.  The unindented initial line and
following blank are due to a bug in html2text, for which I've
submitted

  https://github.com/aaronsw/html2text/pull/63

CHANGELOG: strip trailing whitespace

setup.py: list dependencies in setup(requires=...)

setup.py: use mailing list address for maintenance

REAMDE: point to rss2email/config.py, not a line number in rss2email.py

README: use GitHub URL for git clone

README: use Gmane for example feed

README: add mailing list information (and link to Gmane)

main: fix logging imports

This should have happened in:

  commit 066602efa088b4a89d67e23011613b4459db3c92
  Author: W. Trevor King <wking@tremily.us>
  Date:   Tue Nov 13 09:09:00 2012 -0500

    rss2email: split massive package into modules

Run update-copyright.py

.update-copyright.conf: add copyright configuration.

Use my external update-copyright package to maintain copyright blurbs.

http://pypi.python.org/pypi/update-copyright/

.mailmap: map Lindsey's usernames to a canonical form

COPYING: add GPLv2 text

setup.py: add a comma to the end of the url kwarg

This should have happened in:

  commit cd5b8f30942c72a0fd1b82f4763f21cfaad3864b
  Author: W. Trevor King <wking@tremily.us>
  Date:   Mon Nov 12 15:59:09 2012 -0500

    Convert homepage/downloads from allthingsrss.com to GitHub

rss2email: split massive package into modules

test: fix tests to handle Message-IDs

This should have happened in:

  commit 29f8b8813e1f464b7171ea1830b6ed40ec24dac2
  Author: W. Trevor King <wking@tremily.us>
  Date:   Sat Oct 27 11:09:45 2012 -0400

    rss2email: add Message-IDs so I can link messages in Mutt

rss2email: convert infogami URL to GitHub URL

README: GitHub's markup renderer chokes on Unicode ellipses in code blocks

README.rst: add symlink for GitHub rendering

Convert homepage/downloads from allthingsrss.com to GitHub

rss2email: reorder NoValidEncodingError superclasses

This avoids:

  TypeError: NoValidEncodingError does not take keyword arguments

Merge Lindsey's recent advances with my master

Conflicts:
.gitignore    (use my master, dumping Lindsey's changes)
readme.html   (remove in favor of my README)
rss2email.py  (use my master, bringing in the following changes from
               Lindsey's branch)

  commit 42fa878f929c6ee39c8068d186de1ae7f4630638
  Author: Lindsey Smith <lindsey.smith@gmail.com>
  Date:   Mon Mar 14 09:18:42 2011 -0700

    Improved basic email validation

Incorperated into Feed._validate_email.

  commit 38b33a71e049f29743ce1805b82d4f048e466ce6
  Author: Lindsey Smith <lindsey.smith@gmail.com>
  Date:   Mon Mar 14 09:19:12 2011 -0700

    Initial revision

Incorperated into the Feed._validate_email doctest.

  commit a55809611f9706e7004791c060bd7e5a90a2dcb9
  Author: U-SEVEN\lindsey <lindsey.smith@gmail.com>
  Date:   Fri Jun 24 11:07:22 2011 -0700

    Better attribute handling. Factored out tag handling into getTags()

This wasn't an atomic commit.  I dropped the BeautifulSoup HTML
cleanup to avoid an additional dependency.  I skipped the r → fullfeed
change in getName because I'd already rewritten that function as
Feed._get_entry_name.  I tweaked Feed._get_entry_tags to also handle
termless-tags.

  commit db2ac2f7a76cf93022363ac103f17d7ec71927f9
  Author: U-SEVEN\lindsey <lindsey.smith@gmail.com>
  Date:   Fri Jun 24 11:08:19 2011 -0700

    Added tests for getTags()

Merged getName tests into the Feed._get_entry_name doctest and merged
tag tests into the Feed._get_entry_tags doctest.

The other commits in Lindsey's branch didn't have anything that is
still useful after my refactoring.

Merge Lindsey's tip (development since v2.71)

Merge Lindsey's v2.71 into my v2.71

I would just use Lindsey's repository directly, except my repository
contains more old releases (back to v2.65).

The conflicts were due to a few new lines in Lindsey's CHANGELOG, and
a number of whitespace differences due to line endings.

Conflicts:
CHANGELOG
config.py.example
r2e
r2e.bat
readme.html
rss2email.py

Change maintainer from Lindsey to Trevor.

I emailed Lindset on October 4th with some changes, and then again on
October 18th with a PyPI push suggestion.  I haven't heard back on
either count, so I'm assuming maintainership and pushing this to PyPI
myself.

Lindsey, I'm not attempting a hostile takeover ;).  If you get back
from a month-long vacation and want to resume maintainership, let me
know.

rss2email: allow config feed ordering to override datafile ordering

rss2email: add Message-IDs so I can link messages in Mutt

rss2email: fix Feed._validate_email signature to include self.

rss2email: fix e.__cause__ -> self.__cause__ typos in exception logging.

rss2email.py: don't create config-only feeds if they were in the datafile.

rss2email: add ability to load feeds from the config file only.

If a feed exists in the config file, but not in the data file, the
previous implementation would not load it.  This patch initializes
such feeds using only the information from the config file
(i.e. without dynamic data from the data file).  The patch also
creates missing data files on demand.  As an example use case, if you
keep a backup of your config file, but lose the data file, you can
restore the config file and an `r2e run` will create and repopulate
your data file.

rss2email: fix index->send argument typo in feed.run() call.

rss2email: add debug logging for smtp_send() and sendmail_send().

.gitignore: add `build`, a setup.py byproduct.

rss2email: work around pickle.load() messing with LOG.

I'm not sure why this is happening yet, but _pickle.load() is
duplicating the StreamHandlers in LOG and resetting the log level to
ERROR.  Work around that by saving the original level/handlers and
restoring them after the load() call.
I haven't figured out why this happens yet.

rss2email: add specific SAXParseException error message.

rss2email: add description to the general bozo warning.

r2e: use python in the sh-bang.

This is better than using Bash to call Python, because distutils can
make sh-bang adjustments on installation.

It drops the local --config/--data options, but that brings us into
compliance with the current README and man page.

Package with distutils.

README: move readme.html -> README and convert to reStructuredText.

This is in preparation for posting on PyPI.  It is also easier to read
rst source than it is to read HTML.  You can generate an html version
of the source with

  $ rst2html README > readme.html

I also restructured the README to avoid separate Windows/UNIX
sections, because almost all the advice applies to all systems.

r2e: use PYTHONPATH to find and run rss2email.

This should make it easier for r2e to work where several Python
version are installed on the same machine.

rss2email: add run() function for main program execution.

rss2email: fix pausing -> unpausing typo in unpause help string.

rss2email: change -c/--config option from nargs to append.

Now you should use

  $ rss2email.py -c path1 -c path2 ... comand

Instead of

  $ rss2email.py -c path1 path2 ... comand

The latter made

  $ rss2email.py -c path1 comand

look like a command-less call (`command' being interpreted as another
config path).

rss2email: don't create directories for files in the current directory.

This avoids:

  $ ./rss2email.py -d feeds.dat new
  ...
  OSError: [Errno 2] No such file or directory: ''

readme: add feed name in `r2e add` example.

r2e.1: update man page for configparser-based rss2email.

r2e.1: add man page from Debian package.

This man page was extracted from rss2email_2.65-1.diff.gz.

test: add a test suite and simple testing script.

It would probably be a good idea to use the unittest framework, but
this works as a first pass.

Convert message string to bytes for sendmail.

If we don't have a feed-specific section, use DEFAULT in Feed._send().

Fix configSMTP_SEND -> config.getboolean(section, 'use-smtp') typo.

Set default status to 200 (e.g. when loaded from a local file).

Fix CONFIG -> config typo in Feed.load_from_config().

Change default logging level back to ERROR.

Use kwargs consistently in s for diamond inheritance.

readme: convert configuration examples to the new format.

Update the r2e scripts to use -c/-d for locating config files.

Add myself to __contributors__.

Fix ___contributors__ -> __contributors__.

Spread cmd_run() logic out into Feed methods (under Feed.run()).

Rework commands to use argparse subparsers (cmd_run still needs work).

Cleanups to Feed and Feeds.

Fix ConfigParser option <-> Python conversion for Feed attributes.