email: Fix typo '\\n' -> '\n' in _flatten docstring.

I seem to have forgotten that the docstring is raw (`r"""`) when I
wrote the original tests.

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

email: Make path to sendmail configurable

For example, Azer Koçulu has an rss2email fork that uses msmtp [1].

[1]: https://github.com/azer/rss2email

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

CHANGELOG: Update after the release of 3.0 and 3.1

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

Bump to version 3.1

Changes since 3.0:
* Import __url__, __author__, and __email__ in rss2email.error, which
  fixes bugs formatting a number of errors.

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

error: Import __*__ metadata (URL, author, email)

These are used to format some of the log messages.

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

setup.py: Use __url__ and __author__ from rss2email/__init__.py

Instead of duplicating those values locally.  This gives us one less
place to forget to update the next time we change the website or
maintainer.

Also, update __url__ to point to my GitHub repository and shift the
email address to rss2email.__email__.

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

Bump to version 3.0

Changes since 2.71:
* State storage split into a static configuration file (usually
  `~/.config/rss2email.cfg`) and a dynamic JSON data file (usually
  `~/.local/share/rss2email.json`).
* The static configuration file is parsed with Python's ConfigParser
  class, which allows for default settings that can be overridden on a
  global or per-feed basis.  You'll have to translate your old config
  to the new format by hand when you upgrade.
* Emailed messages now have Message-IDs.
* Feeds can be indexed by name as well as index (e.g.
  `r2e run my-feed`).
* Restructured as a package with submodules instead of a single
  module.  This makes dependencies between various portions of
  rss2email more explicit.
* Converted to Python >=3.2, for more consistent Unicode handling,
  exception chaining, and argparse (although argparse is also in 2.7).
* Packaged with setup.py and distutils, in case you want to install
  rss2email instead of running it from a Git checkout or unpacked
  tarball.
* Added a test suite (run with `./test/test.py`).
* Added a man page, based on the version in the Debian package.
* Require Signed-off-by lines in new commit messages, following the
  Linux and Git projects.
* Assorted cleanups and bug fixes.

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

command: In run(), save feeds even after errors

It's annoying to have a few feeds processed successfully and then have
one feed with a configuration error take down the process without
saving.  With this commit, we always safe the feeds, regardless of any
error.  We also catch and log any RSS2EmailError, not just the
NoToEmailAddress and ProcessingErrors we caught earlier.

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

config: Fix 'significan' -> 'significant' typo in a comment

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

email: Encode the body when we might use 8bit encoding

R. David Murray writes [1]:
> In 2.x that will work, and will give you the 8bit CTE at need, as
> long as you pass encoded text to MIMEText (as opposed to
> unicode...which it doesn't really handle correctly if I recall
> right).

See also, [2].

[1]: http://bugs.python.org/issue12552
     email.MIMEText overide BASE64 for utf8 charset
[2]: http://bugs.python.org/issue12553
     Add support for using a default CTE of '8bit' to MIMEText

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

email: Fix _flatten() implementation for non-ASCII bodies

The email header should be flattened to ASCII with funky encoded
headers [1], but the body may be encoded in a non-ASCII-compatible
charset (e.g. UTF-16-LE).  The old _flatten() implementation used the
body charset to encode the entire message, which could garble the
header.  This patch uses BytesGenerator, which takes advantage of
email.charset.Charset's separate fields for the header encoding and
body encoding.

[1]: http://docs.python.org/3/library/email.header.html

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

email: Add a failing UTF-16 _flatten example

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

email: Factor message-to-bytes formatting out into _flatten()

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

email: Use Charsets to set the Content-Transfer-Encoding

This ensures that payload encoding/decoding happens appropriately, and
allows 7-bit-clean data to be sent with a 7bit CTE, even when the
use-8bit setting is on.

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

email: Alphabetize imports (swap email.mime and email.header)

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

main: Show traceback when we're extra verbose

Adding --verbose (or -V) flags moves the logger from ERROR to WARNING
(-V), INFO (-VV), and DEBUG (-VVV).  Additional increments were
ignored, but I don't like always masking tracebacks.  This patch sets
an additional verbosity level (-VVVV) which logs at DEBUG and
additionally prints exception tracebacks instead of hiding them.

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

feed: Convert missing/extra key errors to InvalidFeedConfig

This way we get the message and not a full traceback, to avoid scaring
users who aren't familiar with Python tracebacks.  Theres not much
information to go on in the new message, but if you crank up the
verbosity, you get:

  $ PYTHONPATH=. ./r2e -c conf -d data -VVV list
  load feed configuration from ['conf']
  loaded configuration from ['conf']
  load feed data from data
  extra configuration key: use_8bit

which seems good enough for me.

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

email: When setting an 8bit CTE, remove the old header

From the docs [1]:

  Note that this does not overwrite or delete any existing header with
  the same name. If you want to ensure that the new header is the only
  one present in the message with field name name, delete the field
  first, e.g.:

    del msg['subject']
    msg['subject'] = 'Python roolz!'

[1]: http://docs.python.org/3/library/email.message.html#email.message.Message.__setitem__

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

test/bbc-chinese: Add tests for use-8bit

The BBC's Chinese feed should have a few non-ASCII characters in it
;).

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

config: Rename use_8bit to use-8bit for uniformity

We use hyphens in all the other config settings.

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

feed: Pass config and section arguments to get_message()

Otherwise it will always use the default config.

Also add section fallback code to get_message in case the
feed-specific section is not in the config file.  This is useful for
testing, although in production every feed should have a section to
hold it's URL.

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

Add use of `sender' parameter in `sendmail_send'.

Signed-off-by: Dmitry Bogatov <KAction@gnu.org>

Add 8bit Content-Transfer-Encoding support.

Signed-off-by: Dmitry Bogatov <KAction@gnu.org>

feeds: Raise an RSS2EmailError on invalid Feeds.index() arguments

Don't confuse non-Python folks by giving a traceback for this usage
error.

Reported-by: Dmitry Bogatov <KAction@gnu.org>
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.