pgp: force protocol/micalg ordering in doctest output.

[pgp-mime.git] / README

diff --git a/README b/README
index 18fed9a6f5cdcee13a9cfa76b3751db395bc566a..81219c5aaee8078b264c5a4d29f9eacfdf2d38d4 100644 (file)
--- a/README
+++ b/README
@@ -1,8 +1,8 @@
 Python module and tools for constructing and sending PGP/MIME email.
 
 The ``pgp_mime`` module makes it easy to construct and dispatch signed
-and/or encrypted email using PGP_ and :RFC:`3156`.  It uses GnuPG_ to
-perform the cryptography.
+and/or encrypted email using PGP_ and :RFC:`3156`.  It uses GnuPG_
+(via `gpgme-tool`_) to perform the cryptography.
 
 Installation
 ============
@@ -24,14 +24,21 @@ Dependencies
 ------------
 
 ``pgp-mime`` is a simple package with no external dependencies outside
-the Python 3 standard library.  There are a number of GnuPG_ wrappers
+the Python 3.3 standard library.  There are a number of GnuPG_ wrappers
 for python `out there`__, but none of them seem mature/stable enough
-to be worth installing.  Instead, we use the ``subprocess`` module to
-call ``gpg`` directly.  If this isn't working for you, you need only
-replace the ``*_bytes`` commands which handle the cryptography.
+to be worth installing.  Instead, we use the `pyassuan`_ module to
+talk to `gpgme-tool`_ over pipes or sockets.  If this isn't working
+for you, you need only replace the ``pgp_mime.crypt`` module to handle
+the cryptography.
 
 __ wrappers_
 
+It would be awkward to backport ``pgp-mime`` to earlier versions of
+Python, because versions before Python 3.3 lack sendmsg_ and recvmsg_,
+and Python 2.7 doesn't even have that pass_fds option for Popen.  This
+makes it much harder to pass file descriptors to the `gpgme-tool`
+process.
+
 Installing by hand
 ------------------
 
@@ -74,6 +81,10 @@ If you can convince your students to get PGP keys, you could also
 encrypt their grades by changing ``--mode sign`` to ``--mode
 sign-encrypt``.
 
+Of course, if you're interested in working with students and grades,
+you might also be interested in my `pygrader`_ package, which uses
+pgp-mime under the hood.
+
 Configuring the SMTP connection
 -------------------------------
 
@@ -81,7 +92,7 @@ Pgp-mime supports two methods for sending messages (via
 ``pgp_mime.mail``).  It can either call your system's ``sendmail``
 equivalent, or connect directly to an SMTP_ server using ``smtplib``.
 Since I imagine SMTP will be more common, you can easily configure
-your SMTP connection via ``~/.config/pgp-mime.conf``::
+your SMTP connection via ``~/.config/smtplib.conf``::
 
   [smtp]
   host: smtp.mail.uu.edu
@@ -109,7 +120,7 @@ Run the internal unit tests using nose_::
 If a Python-3-version of ``nosetests`` is not the default on your
 system, you may need to try something like::
 
-  $ nosetests-3.2 --with-doctest --doctest-tests pgp_mime
+  $ nosetests-3.3 --with-doctest --doctest-tests pgp_mime
 
 Licence
 =======
@@ -128,9 +139,16 @@ wking@tremily.us
 .. _layman: http://layman.sourceforge.net/
 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
 .. _wrappers: http://wiki.python.org/moin/GnuPrivacyGuard
+.. _pyassuan: http://blog.tremily.us/posts/pyassuan/
+.. _gpgme-tool:
+  http://git.gnupg.org/cgi-bin/gitweb.cgi?p=gpgme.git;a=blob;f=src/gpgme-tool.c;hb=HEAD
+.. _Popen: http://docs.python.org/py3k/library/subprocess.html#subprocess.Popen
+.. _sendmsg: http://docs.python.org/dev/library/socket.html#socket.socket.sendmsg
+.. _recvmsg: http://docs.python.org/dev/library/socket.html#socket.socket.recvmsg
 .. _Git: http://git-scm.com/
 .. _homepage: http://blog.tremily.us/posts/pgp-mime/
 .. _wrappers and pinentry program: http://blog.tremily.us/posts/gpg-agent/
+.. _pygrader: http://blog.tremily.us/posts/pygrader/
 .. _SMTP: http://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol
 .. _STARTTLS: http://en.wikipedia.org/wiki/STARTTLS
 .. _GnuPG: http://www.gnupg.org/