docs: python bindings howto

* Confirmed that updates to the tests have significant'y improved that
  output.
* Updated some of the additional notes for the section on hkp4py.
** This is in anticipation adding at least import examples using that
   module as well.  It may also include adding examples of exporting a
   key and uploading it to the keyservers.

Tested-by: Ben McGinnes <[email protected]>
Signed-off-by: Ben McGinnes <[email protected]>

1 files changed, 18 insertions, 1 deletions

diff --git a/doc/gpgme-python-howto.texi b/doc/gpgme-python-howto.texi
index 85a8dcfd..e78c6f85 100644
--- a/doc/gpgme-python-howto.texi
+++ b/doc/gpgme-python-howto.texi
@@ -2265,7 +2265,7 @@ support for Python 2.7 as well and is available via PyPI.
 
 Since it rewrites the @samp{hkp} protocol prefix as @samp{http} and @samp{hkps} as
 @samp{https}, the module is able to be used even with servers which do not
-support the full scope of keyserver functions.  It will work quite
+support the full scope of keyserver functions.  It also works quite
 readily when incorporated into a @ref{C plus Python plus SWIG plus Cython, , Cython} generated and compiled version
 of any code.
 
@@ -2281,6 +2281,23 @@ The hkp4py module returns key data via requests as string literals
 the retrurned key data must be encoded to UTF-8 when importing that
 key material using a @samp{gpg.Context().key_import()} method.
 
+For this reason an alternative method has been added to the @samp{search}
+function of @samp{hkp4py.KeyServer()} which returns the key in the correct
+format as expected by @samp{key_import}.  When importing using this module,
+it is now possible to import with this:
+
+@example
+for key in keys:
+    if key.revoked is False:
+        gpg.Context().key_import(key.key_blob)
+    else:
+        pass
+@end example
+
+Without that recent addition it would have been necessary to encode
+the contents of each @samp{hkp4py.KeyServer().search()[i].key} in
+@samp{hkp4py.KeyServer().search()} before trying to import it.
+
 @node Copyright and Licensing
 @chapter Copyright and Licensing