python bindings howto: dita versionben/howto-dita

* Numerous updates to bring it back into sync with the official doc. * Especially important since it now looks like the babel thing is a real bug after all and not me doing something stupid.
author: Ben McGinnes <ben@adversary.org> 2018-07-13 22:08:42 +1000
committer: Ben McGinnes <ben@adversary.org> 2018-07-13 22:08:42 +1000
commit: 1e34141f6770cd8ca243048ec6f78d600bed4262 (patch)
tree: 7feaeb64a023a8bdd70033592d22be71b2ea612d
parent: dda54cc851490be045832d5ee0b03be082529d17 (diff)
download: gpgme-1e34141f6770cd8ca243048ec6f78d600bed4262.tar.gz
6 files changed, 80 insertions, 6 deletions
diff --git a/lang/python/docs/dita/gpgme-python-howto.ditamap b/lang/python/docs/dita/gpgme-python-howto.ditamap
index 1809acb3..10ba8a64 100644
--- a/lang/python/docs/dita/gpgme-python-howto.ditamap
+++ b/lang/python/docs/dita/gpgme-python-howto.ditamap
@@ -39,7 +39,7 @@
       <topicref id="python-bindings" href="howto/part02/python-bindings.dita"/>
       <topicref id="py-diffs" href="howto/part02/differences-to-others.dita">
         <topicref id="vinay-sajip" href="howto/part02/python-gnupg.dita"/>
-        <topicref id="isis-lovecruft" href="howto/part02/daesh.dita"/>
+        <topicref id="isis-lovecruft" href="howto/part02/isis-gnupg.dita"/>
         <topicref id="martin-albrecht" href="howto/part02/pyme.dita"/>
       </topicref>
     </topicref>
diff --git a/lang/python/docs/dita/howto/part02/installing.dita b/lang/python/docs/dita/howto/part02/installing.dita
index 879f6ca7..4ede496d 100644
--- a/lang/python/docs/dita/howto/part02/installing.dita
+++ b/lang/python/docs/dita/howto/part02/installing.dita
@@ -16,8 +16,8 @@
       <p>For Python 2 it checks for these executables in this order: <cmdname>python</cmdname>,
           <cmdname>python2</cmdname> and <cmdname>python2.7</cmdname>.</p>
       <p>For Python 3 it checks for these executables in this order: <cmdname>python3</cmdname>,
-          <cmdname>python3.6</cmdname>, <cmdname>python3.5</cmdname> and
-          <cmdname>python3.4</cmdname>.</p>
+          <cmdname>python3.6</cmdname>, <cmdname>python3.5</cmdname>, <cmdname>python3.4</cmdname>
+        and <cmdname>python3.7</cmdname>.</p>
     </body>
   </topic>
 </dita>
diff --git a/lang/python/docs/dita/howto/part02/daesh.dita b/lang/python/docs/dita/howto/part02/isis-gnupg.dita
index 8839710d..8839710d 100644
--- a/lang/python/docs/dita/howto/part02/daesh.dita
+++ b/lang/python/docs/dita/howto/part02/isis-gnupg.dita
diff --git a/lang/python/docs/dita/howto/part03/exporting-pubkeys.dita b/lang/python/docs/dita/howto/part03/exporting-pubkeys.dita
index 8ae4f5bd..f632eb6f 100644
--- a/lang/python/docs/dita/howto/part03/exporting-pubkeys.dita
+++ b/lang/python/docs/dita/howto/part03/exporting-pubkeys.dita
@@ -5,9 +5,9 @@
     <title>Exporting Public Keys</title>
     <body>
       <p>There are two methods of exporting public keys, both of which are very similar to the
-        other. The default method, <codeph>key_export()</codeph> will export a public key or keys
+        other. The default method, <codeph>key_export()</codeph>, will export a public key or keys
         matching a specified pattern as normal. The alternative, the
-          <codeph>key_export_minimal()</codeph> method will do the same thing except producing a
+          <codeph>key_export_minimal()</codeph> method, will do the same thing except producing a
         minimised output with extra signatures and third party signatures or certifications
         removed.</p>
       <p>
diff --git a/lang/python/docs/dita/howto/part03/importing-eff-keys.dita b/lang/python/docs/dita/howto/part03/importing-eff-keys.dita
new file mode 100644
index 00000000..124ebdac
--- /dev/null
+++ b/lang/python/docs/dita/howto/part03/importing-eff-keys.dita
@@ -0,0 +1,74 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita xml:lang="en-GB">
+  <topic id="eff-key-import">
+    <title>Importing Keys</title>
+    <shortdesc>DRAFT VERSION</shortdesc>
+    <body>
+      <p>Importing keys is possible with the <codeph>key_import()</codeph> method and takes one
+        argument which is a bytes literal object containing either the binary or ASCII armoured key
+        data for one or more keys.</p>
+      <p>In the following example a key will be retrieved from the SKS keyservers via the web using
+        the requests module. Since requests returns the content as a bytes literal object, we can
+        then use that directly to import the resulting data into our keybox. In order to demonstrate
+        multiple imports this example searches for all the keys of users at a particular domain
+        name. This time we're using the EFF, since they've always been such good supporters of
+        strong encryption and good security practices.</p>
+      <p>If this holds true then I would expect that some keys I already have will be updated and
+        some others will be added. Most of the keys created most recently and belonging to still
+        active people within the EFF should, if they are following their own recent statements, be
+        revoked. If they are not revoked then it would be best left to the reader to determine
+        whether or not the change in leadership at that organisation indicates a change in their
+        policy of supporting good security practices.</p>
+      <p>
+        <codeblock id="import-key-1" outputclass="language-python">import gpg
+import requests
+
+c = gpg.Context()
+url = "https://sks-keyservers.net/pks/lookup"
+pattern = input("Enter the pattern to search for key or user IDs: ")
+payload = { "op": "get", "search": pattern }
+
+r = requests.get(url, verify=True, params=payload)
+k = c.key_import(r.content)
+
+summary = """
+Total number of keys:   {0}
+Total number imported:  {1}
+Number of version 3 keys ignored:  {2}
+
+Number of imported key objects or updates:  {3}
+Number of unchanged keys:  {4}
+Number of new signatures:  {5}
+Number of revoked keys:    {6}
+""".format(k.considered, len(k.imports), k.skipped_v3_keys, k.imported,
+           k.unchanged, k.new_signatures, k.new_revocations)
+
+print(summary)</codeblock>
+      </p>
+      <p>The resulting output in that case, where the search pattern entered was
+          <codeph>@eff.org</codeph> was:</p>
+      <p>
+        <codeblock id="import-key-2" outputclass="language-bourne">Total number of keys:   272
+Total number imported:  249
+Number of version 3 keys ignored:  23
+
+Number of imported key objects or updates:  180
+Number of unchanged keys:  66
+Number of new signatures:  7
+Number of revoked keys:    0</codeblock>
+      </p>
+      <p>The 23 skipped keys all date back to the 1990s, some of which were made very shortly after
+        PGP 2 was first released.</p>
+      <p>
+        <note>Pretty Good Privacy version 2 and above are the only versions with any widespread use.
+          Pretty Good Privacy version 1 had a number of serious security problems, not least of
+          which being that it relied on an encryption algorithm called Bass-O-Matic which was
+          written by Phil Zimmermann. Following feedback on this algorithm, Zimmermann withdrew
+          version 1 and re-implemented version 2 using RSA and IDEA, even though both were subject
+          to software patents at the time (both of those software patents have long since
+          expired).</note>
+      </p>
+    </body>
+  </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/version-info.dita b/lang/python/docs/dita/howto/version-info.dita
index f9bb42aa..f07c1362 100644
--- a/lang/python/docs/dita/howto/version-info.dita
+++ b/lang/python/docs/dita/howto/version-info.dita
@@ -4,7 +4,7 @@
   <topic id="topic_vnz_nn2_vdb">
     <title>Documentation Version</title>
     <body>
-      <p><b>Version:</b> 0.1.2-DRAFT</p>
+      <p><b>Version:</b> 0.1.3-DRAFT</p>
       <p><b>Author:</b> Ben McGinnes &lt;<xref href="mailto:ben@gnupg.org" format="html"
           scope="external">ben@gnupg.org</xref>></p>
       <p><b>Author GPG Key ID:</b>
author	Ben McGinnes <ben@adversary.org>	2018-07-13 22:08:42 +1000
committer	Ben McGinnes <ben@adversary.org>	2018-07-13 22:08:42 +1000
commit	1e34141f6770cd8ca243048ec6f78d600bed4262 (patch)
tree	7feaeb64a023a8bdd70033592d22be71b2ea612d
parent	dda54cc851490be045832d5ee0b03be082529d17 (diff)
download	gpgme-1e34141f6770cd8ca243048ec6f78d600bed4262.tar.gz