python: Improve the documentation.

* lang/python/Makefile.am: Copy the README file.
* lang/python/README: Rename, convert to org, and update.
* lang/python/pyme/__init__.py: Move license out of the docstring,
update docstring.
* lang/python/pyme/core.py: Add and update docstrings.

Signed-off-by: Justus Winter <[email protected]>

5 files changed, 148 insertions, 102 deletions

diff --git a/lang/python/Makefile.am b/lang/python/Makefile.am
index 2c84f2b5..18005bf9 100644
--- a/lang/python/Makefile.am
+++ b/lang/python/Makefile.am
@@ -16,16 +16,21 @@
 # You should have received a copy of the GNU Lesser General Public
 # License along with this program; if not, see <http://www.gnu.org/licenses/>.
 
-EXTRA_DIST = README.rst
+EXTRA_DIST = README
 SUBDIRS = tests
 
+COPY_FILES = \
+	$(srcdir)/README \
+	$(srcdir)/pyme \
+	$(srcdir)/helpers.c $(srcdir)/helpers.h
+
 # Cleanup gpgme.h from deprecated functions and typedefs.
 gpgme.h: ../../src/gpgme.h $(srcdir)/gpgme-h-clean.py
 	$(PYTHON) $(srcdir)/gpgme-h-clean.py $< >$@
 
 # For VPATH builds we need to copy some files because Python's
 # distutils are not VPATH-aware.
-copystamp: $(srcdir)/pyme $(srcdir)/helpers.c $(srcdir)/helpers.h
+copystamp: $(COPY_FILES)
 	if test "$(srcdir)" != "$(builddir)" ; then cp -r $^ . ; fi
 	touch $@
 
diff --git a/lang/python/README b/lang/python/README
new file mode 100644
index 00000000..7ce8894b
--- /dev/null
+++ b/lang/python/README
@@ -0,0 +1,57 @@
+PyME - GPGME for Python          emacs, please switch to -*- org -*- mode
+=======================
+
+PyMe is a python interface to the GPGME library:
+https://www.gnupg.org/related_software/gpgme/
+
+PyMe uses SWIG to create wrapper functions with automatic type
+conversions.  This way most of the functions and types are converted
+from C into Python 3 automatically by SWIG, reducing the maintenance
+cost of the binginds.
+
+* Authors
+
+PyME has been created by John Goerzen, and maintained, developed, and
+cherished by Igor Belyi, Martin Albrecht, Ben McGinnes, and everyone
+who contributed to it in any way.
+
+In 2016 we merged a port of PyME to into the GPGME repository, and
+development will continue there.  Please see the VCS history for the
+list of contributors, and if you do find bugs, or want to contribute,
+please get in touch and help maintain PyME.
+
+Please see the section 'History' further down this document for
+references to previous versions.
+
+* Mailing List
+
+For general discussion and help see the gnupg-users mailing list:
+https://lists.gnupg.org/mailman/listinfo/gnupg-users
+
+For development see the gnupg-devel mailing list:
+https://lists.gnupg.org/mailman/listinfo/gnupg-devel
+
+* Bugs
+
+Please report bugs using our bug tracker using the category 'gpgme',
+and topic 'python':
+https://bugs.gnupg.org/gnupg/
+
+* History
+
+ - The bindings have been merged into the GPGME repository in 2016.
+
+ - The latest version of PyME for Python 3.2 and above (as of
+   May, 2015) is v0.9.1.
+   https://git.gnupg.org/gpgme.git/lang/py3-pyme
+
+ - The latest version of PyME for Python 2.6 and 2.7 (as of this
+   writing) is v0.9.0.  https://bitbucket.org/malb/pyme
+
+ - A previous version of PyME v0.8.0 can be found on sourceforge:
+   http://pyme.sourceforge.net/
+
+ - A previous version of PyME v0.5.1 which works with GPGME v0.3.15
+   can be found on John Goerzen's PyMe page:
+   http://quux.org/devel/pyme/
+   http://www.complete.org/JohnGoerzen
diff --git a/lang/python/README.rst b/lang/python/README.rst
deleted file mode 100644
index 57df1f29..00000000
--- a/lang/python/README.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-====
-PyME
-====
-
-PyMe is a python interface to the `GPGME
-<https://www.gnupg.org/related_software/gpgme/>`_ library.
-
-PyMe's development model is a `GPGME
-<https://www.gnupg.org/related_software/gpgme/>`_ + Python 3 + `SWIG
-<http://www.swig.org/>`_ combination which means that most of the functions and
-types are converted from C into Python 3 automatically by SWIG. In short, to be
-able to use PyMe you need to be `familiar with GPGME
-<https://www.gnupg.org/documentation/manuals/gpgme/>`_.
-
-
--------
-Authors
--------
-
-* John Goerzen, `Complete.Org <http://www.complete.org/JohnGoerzen>`_, 2002.
-* Igor Belyi, `PyME 0.8 <http://pyme.sourceforge.net/>`_, 2004-2008.
-* Martin Albrecht, `PyME 0.9+ <https://bitbucket.org/malb/pyme>`_, 2014 to present.
-* Ben McGinnes, `PyME Python 3 Port <https://git.gnupg.org/gpgme.git/lang/py3-pyme>`_, 2015 to present.
-
-
-------------
-Mailing List
-------------
-
-PyME's support and development `mailing list
-<http://sourceforge.net/p/pyme/mailman/pyme-help/>`_ is hosted by sourceforge.
-
-
--------
-History
--------
-
-* The latest version of PyME for Python 3.2 and above (as of May, 2015) is v0.9.1.
-  https://git.gnupg.org/gpgme.git/lang/py3-pyme
-
-* The latest version of PyME for Python 2.6 and 2.7 (as of this writing) is v0.9.0.
-  https://bitbucket.org/malb/pyme
-
-* A previous version of PyME v0.8.0 can be found on sourceforge:
-  http://pyme.sourceforge.net/
-
-* A previous version of PyME v0.5.1 which works with GPGME v0.3.15 can be found
-  on John Goerzen's PyMe page: http://quux.org/devel/pyme/
diff --git a/lang/python/pyme/__init__.py b/lang/python/pyme/__init__.py
index d06866a8..e377f595 100644
--- a/lang/python/pyme/__init__.py
+++ b/lang/python/pyme/__init__.py
@@ -1,36 +1,38 @@
-"""
-Pyme: GPGME Interface for Python
-Copyright (C) 2004 Igor Belyi <[email protected]>
-Copyright (C) 2002 John Goerzen <[email protected]>
-
-   This library is free software; you can redistribute it and/or
-   modify it under the terms of the GNU Lesser General Public
-   License as published by the Free Software Foundation; either
-   version 2.1 of the License, or (at your option) any later version.
-
-   This library is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-   Lesser General Public License for more details.
-
-   You should have received a copy of the GNU Lesser General Public
-   License along with this library; if not, write to the Free Software
-   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+# Copyright (C) 2016 g10 Code GmbH
+# Copyright (C) 2004 Igor Belyi <[email protected]>
+# Copyright (C) 2002 John Goerzen <[email protected]>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
+
+"""Pyme: GPGME Interface for Python
 
 Welcome to PyME, the GPGME Interface for Python.  "Pyme", when prounced,
 rhymes with "Pine".
 
 The latest release of this package may be obtained from
+https://www.gnupg.org
+
+Previous releases of this package for Python 2 can be obtained from
 http://pyme.sourceforge.net
-Previous releases of this package can be obtained from
-http://quux.org/devel/pyme/
 
 FEATURES
 --------
 
  * Feature-rich, full implementation of the GPGME library.  Supports
-   all GPGME features except interactive editing (coming soon).
-   Callback functions may be written in pure Python.
+   all GPGME features.  Callback functions may be written in pure
+   Python.  Exceptions raised in callbacks are properly propagated.
 
  * Ability to sign, encrypt, decrypt, and verify data.
 
@@ -50,9 +52,7 @@ defined here -- they correspond directly to certain object types in GPGME
 for C.  For instance, the following C code:
 
 gpgme_ctx_t context;
-
 gpgme_new(&context);
-
 ...
 gpgme_op_encrypt(context, recp, 1, plain, cipher);
 
@@ -130,8 +130,6 @@ Version information: pyme.version
 Utilities: pyme.util
 
 Base classes are documented at pyme.core.
-Classes of pyme.util usually are not instantiated by users
-directly but return by methods of base classes.
 
 """
 
diff --git a/lang/python/pyme/core.py b/lang/python/pyme/core.py
index 4b3e08a4..293df097 100644
--- a/lang/python/pyme/core.py
+++ b/lang/python/pyme/core.py
@@ -1,3 +1,4 @@
+# Copyright (C) 2016 g10 Code GmbH
 # Copyright (C) 2004,2008 Igor Belyi <[email protected]>
 # Copyright (C) 2002 John Goerzen <[email protected]>
 #
@@ -15,14 +16,25 @@
 #    License along with this library; if not, write to the Free Software
 #    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
 
+"""Core functionality
+
+Core functionality of GPGME wrapped in a object-oriented fashion.
+Provides the 'Context' class for performing cryptographic operations,
+and the 'Data' class describing buffers of data.
+
+"""
+
 import weakref
 from . import pygpgme
 from .errors import errorcheck, GPGMEError
 from . import errors
 
 class GpgmeWrapper(object):
-    """Base class all Pyme wrappers for GPGME functionality.  Not to be
-    instantiated directly."""
+    """Base wrapper class
+
+    Not to be instantiated directly.
+
+    """
 
     def __init__(self, wrapped):
         self._callback_excinfo = None
@@ -66,7 +78,7 @@ class GpgmeWrapper(object):
         raise NotImplementedError()
 
     def __getattr__(self, key):
-        """On-the-fly function generation."""
+        """On-the-fly generation of wrapper methods."""
         if key[0] == '_' or self._getnameprepend() == None:
             return None
         name = self._getnameprepend() + key
@@ -98,15 +110,17 @@ class GpgmeWrapper(object):
         return wrapper
 
 class Context(GpgmeWrapper):
-    """From the GPGME C documentation:
+    """Context for cryptographic operations
+
+    All cryptographic operations in GPGME are performed within a
+    context, which contains the internal state of the operation as
+    well as configuration parameters.  By using several contexts you
+    can run several cryptographic operations in parallel, with
+    different configuration.
 
-    * All cryptographic operations in GPGME are performed within a
-    * context, which contains the internal state of the operation as well as
-    * configuration parameters.  By using several contexts you can run
-    * several cryptographic operations in parallel, with different
-    * configuration.
+    Access to a context must be synchronized.
 
-    Thus, this is the place that you will usually start."""
+    """
 
     def _getctype(self):
         return 'gpgme_ctx_t'
@@ -348,18 +362,21 @@ class Context(GpgmeWrapper):
         errorcheck(result)
 
 class Data(GpgmeWrapper):
-    """From the GPGME C manual:
+    """Data buffer
 
-* A lot of data has to be exchanged between the user and the crypto
-* engine, like plaintext messages, ciphertext, signatures and information
-* about the keys.  The technical details about exchanging the data
-* information are completely abstracted by GPGME.  The user provides and
-* receives the data via `gpgme_data_t' objects, regardless of the
-* communication protocol between GPGME and the crypto engine in use.
+    A lot of data has to be exchanged between the user and the crypto
+    engine, like plaintext messages, ciphertext, signatures and
+    information about the keys.  The technical details about
+    exchanging the data information are completely abstracted by
+    GPGME.  The user provides and receives the data via `gpgme_data_t'
+    objects, regardless of the communication protocol between GPGME
+    and the crypto engine in use.
 
-        This Data class is the implementation of the GpgmeData objects.
+    This Data class is the implementation of the GpgmeData objects.
 
-        Please see the information about __init__ for instantiation."""
+    Please see the information about __init__ for instantiation.
+
+    """
 
     def _getctype(self):
         return 'gpgme_data_t'
@@ -393,15 +410,31 @@ class Data(GpgmeWrapper):
 
         (read_cb, write_cb, seek_cb, release_cb[, hook])
 
-        where func is a callback function taking two arguments (count,
-        hook) and returning a string of read data, or None on EOF.
-        This will supply the read() method for the system.
+        where the first four items are functions implementing reading,
+        writing, seeking the data, and releasing any resources once
+        the data object is deallocated.  The functions must match the
+        following prototypes:
+
+            def read(amount, hook=None):
+                return <a b"bytes" object>
+
+            def write(data, hook=None):
+                return <the number of bytes written>
+
+            def seek(offset, whence, hook=None):
+                return <the new file position>
+
+            def release(hook=None):
+                <return value and exceptions are ignored>
+
+        The functions may be bound methods.  In that case, you can
+        simply use the 'self' reference instead of using a hook.
 
         If file is specified without any other arguments, then
         it must be a filename, and the object will be initialized from
         that file.
 
-        Any other use will result in undefined or erroneous behavior."""
+        """
         super().__init__(None)
         self.data_cbs = None
 
@@ -488,9 +521,10 @@ class Data(GpgmeWrapper):
         """This wraps the GPGME gpgme_data_new_from_filepart() function.
         The argument "file" may be:
 
-        1. a string specifying a file name, or
-        3. a a file-like object. supporting the fileno() call and the mode
-           attribute."""
+        * a string specifying a file name, or
+        * a file-like object supporting the fileno() and the mode attribute.
+
+        """
 
         tmp = pygpgme.new_gpgme_data_t_p()
         filename = None