14 files changed, 246 insertions, 0 deletions
diff --git a/lang/python/docs/dita/howto/part02/c-api.dita b/lang/python/docs/dita/howto/part02/c-api.dita
new file mode 100644
index 00000000..67736ab2
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/c-api.dita
@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_jrb_pxx_5db">
+        <title>A C API</title>
+        <body>
+            <p>Unlike many modern APIs with which programmers will be more familiar with these days,
+        the GPGME API is a C API. The API is intended for use by C coders who would be able to
+        access its features by including the =gpgme.h= header file with their own C source code and
+        then access its functions just as they would any other C headers.</p>
+      <p>This is a very effective method of gaining complete access to the API and in the most
+        efficient manner possible. It does, however, have the drawback that it cannot be directly
+        used by other languages without some means of providing an interface to those languages.
+        This is where the need for bindings in various languages stems.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/context.dita b/lang/python/docs/dita/howto/part02/context.dita
new file mode 100644
index 00000000..4b137af8
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/context.dita
@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_bpb_why_5db">
+        <title>Context</title>
+        <body>
+            <p>One of the reasons which prevents this API from being RESTful is that most operations
+        require more than one instruction to the API to perform the task. Sure, there are certain
+        functions which can be performed simultaneously, particularly if the result known or
+        strongly anticipated (e.g. selecting and encrypting to a key known to be in the public
+        keybox).</p>
+      <p>There are many more, however, which cannot be manipulated so readily: they must be
+        performed in a specific sequence and the result of one operation has a direct bearing on the
+        outcome of subsequent operations. Not merely by generating an error either.</p>
+      <p>When dealing with this type of persistent state on the web, full of both the RESTful and
+        REST-like, it's most commonly referred to as a session. In GPGME, however, it is called a
+        context and every operation type has one.</p>
+      <p/>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/daesh.dita b/lang/python/docs/dita/howto/part02/daesh.dita
new file mode 100644
index 00000000..0d02f45e
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/daesh.dita
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_ob2_yzx_5db">
+        <title>The gnupg package created and maintained by Isis Lovecruft</title>
+        <body>
+            <p>In 2015 Isis Lovecruft from the Tor Project forked and then re-implemented the
+        python-gnupg package as just gnupg. This new package also relied on
+          <codeph>subprocess</codeph> to call the <cmdname>gpg</cmdname> or <cmdname>gpg2</cmdname>
+        binaries, but did so somewhat more securely.</p>
+      <p>The naming and version numbering selected for this package, however, resulted in conflicts
+        with the original python-gnupg and since its functions were called in a different manner to
+        python-gnupg, the release of this package also resulted in a great deal of consternation
+        when people installed what they thought was an upgrade that subsequently broke the code
+        relying on it.</p>
+      <p>The gnupg package is available under the GNU General Public License version 3.0 (or any
+        later version).</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/differences-to-others.dita b/lang/python/docs/dita/howto/part02/differences-to-others.dita
new file mode 100644
index 00000000..dd3521f2
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/differences-to-others.dita
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_ecj_yyx_5db">
+        <title>Difference between the Python bindings and other GnuPG Python packages</title>
+        <body>
+            <p>There have been numerous attempts to add GnuPG support to Python over the years. Some
+        of the most well known are listed here, along with what differentiates them.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/fundamentals.dita b/lang/python/docs/dita/howto/part02/fundamentals.dita
new file mode 100644
index 00000000..a81faf50
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/fundamentals.dita
@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_xsp_ygy_5db">
+        <title>Fundamentals</title>
+        <body>
+            <p>Before we can get to the fun stuff, there are a few matters regarding GPGME's design
+        which hold true whether you're dealing with the C code directly or these Python
+        bindings.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/gpgme-concepts.dita b/lang/python/docs/dita/howto/part02/gpgme-concepts.dita
new file mode 100644
index 00000000..436111bf
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/gpgme-concepts.dita
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+  <topic id="topic_zm1_lxx_5db">
+    <title>GPGME Concepts</title>
+    <body>
+      <p/>
+    </body>
+  </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/installation.dita b/lang/python/docs/dita/howto/part02/installation.dita
new file mode 100644
index 00000000..4e35dc99
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/installation.dita
@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_isl_32y_5db">
+        <title>GPGME Python bindings installation</title>
+        <body>
+            <p></p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/installing.dita b/lang/python/docs/dita/howto/part02/installing.dita
new file mode 100644
index 00000000..91a0cf49
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/installing.dita
@@ -0,0 +1,23 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+  <topic id="topic_ivh_zfy_5db">
+    <title>Installing</title>
+    <body>
+      <p>Installing the Python bindings is effectively achieved by compiling and installing GPGME
+        itself.</p>
+      <p>Once SWIG is installed with Python and all the dependencies for GPGME are installed you
+        only need to confirm that the version(s) of Python you want the bindings installed for are
+        in your <codeph>$PATH</codeph>.</p>
+      <p>By default GPGME will attempt to install the bindings for the most recent or highest
+        version number of Python 2 and Python 3 it detects in <codeph>$PATH</codeph>. It
+        specifically checks for the <cmdname>python</cmdname> and <cmdname>python3</cmdname>
+        executables first and then checks for specific version numbers.</p>
+      <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>
+    </body>
+  </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/no-pypi.dita b/lang/python/docs/dita/howto/part02/no-pypi.dita
new file mode 100644
index 00000000..8f2b6013
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/no-pypi.dita
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_mss_p2y_5db">
+        <title>No PyPI</title>
+        <body>
+            <p>Most third-party Python packages and modules are available and distributed through
+        the Python Package Installer, known as PyPI.</p>
+      <p>Due to the nature of what these bindings are and how they work, it is infeasible to install
+        the GPGME Python bindings in the same way.</p>
+      <p>This is because the bindings use SWIG to dynamically generate C bindings against
+          <codeph>gpgme.h</codeph> and <codeph>gpgme.h</codeph> is generated from
+          <codeph>gpgme.h.in</codeph> at compile time when GPGME is built from source. Thus to
+        include a package in PyPI which actually built correctly would require either statically
+        built libraries for every architecture bundled with it or a full implementation of C for
+        each architecture.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/no-rest.dita b/lang/python/docs/dita/howto/part02/no-rest.dita
new file mode 100644
index 00000000..82cf8e80
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/no-rest.dita
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_wmg_2hy_5db">
+        <title>No REST</title>
+        <body>
+            <p>The first part of which is or will be fairly blatantly obvious upon viewing the first
+        example, but it's worth reiterating anyway. That being that this API is <b><i>not</i></b> a
+        REST API. Nor indeed could it ever be one.</p>
+      <p>Most, if not all, Python programmers (and not just Python programmers) know how easy it is
+        to work with a RESTful API. In fact they've become so popular that many other APIs attempt
+        to emulate REST-like behaviour as much as they are able. Right down to the use of JSON
+        formatted output to facilitate the use of their API without having to retrain
+        developers.</p>
+      <p>This API does not do that. It would not be able to do that and also provide access to the
+        entire C API on which it's built. It does, however, provide a very pythonic interface on top
+        of the direct bindings and it's this pythonic layer with which this HOWTO deals with.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/pyme.dita b/lang/python/docs/dita/howto/part02/pyme.dita
new file mode 100644
index 00000000..3ced2dc5
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/pyme.dita
@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+  <topic id="topic_oy4_zcy_5db">
+    <title>The PyME package maintained by Martin Albrecht</title>
+    <body>
+      <p>This package is the origin of these bindings, though they are somewhat different now. For
+        details of when and how the PyME package was folded back into GPGME itself see the
+          <cite>Short History</cite> document<fn><codeph>Short_History.org</codeph> and/or
+            <codeph>Short_History.html</codeph>.</fn> in the Python bindings <codeph>docs/</codeph>
+          directory.<fn>The <filepath>lang/python/docs/</filepath> directory in the GPGME
+          source.</fn></p>
+      <p>The PyME package was first released in 2002 and was also the first attempt to implement a
+        low level binding to GPGME. In doing so it provided access to considerably more
+        functionality than either the <codeph>python-gnupg</codeph> or <codeph>gnupg</codeph>
+        packages.</p>
+      <p>The PyME package is only available for Python 2.6 and 2.7.</p>
+      <p>Porting the PyME package to Python 3.4 in 2015 is what resulted in it being folded into the
+        GPGME project and the current bindings are the end result of that effort.</p>
+      <p>The PyME package is available under the same dual licensing as GPGME itself: the GNU
+        General Public License version 2.0 (or any later version) and the GNU Lesser General Public
+        License version 2.1 (or any later version).</p>
+    </body>
+  </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/python-bindings.dita b/lang/python/docs/dita/howto/part02/python-bindings.dita
new file mode 100644
index 00000000..6590fee4
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/python-bindings.dita
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_g4z_wxx_5db">
+        <title>Python Bindings</title>
+        <body>
+            <p>The Python bindings for GPGME provide a higher level means of accessing the complete
+        feature set of GPGME itself. It also provides a more pythonic means of calling these API
+        functions.</p>
+      <p>The bindings are generated dynamically with SWIG and the copy of <codeph>gpgme.h</codeph>
+        generated when GPGME is compiled.</p>
+      <p>This means that a version of the Python bindings is fundamentally tied to the exact same
+        version of GPGME used to generate that copy of <codeph>gpgme.h</codeph>.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/python-gnupg.dita b/lang/python/docs/dita/howto/part02/python-gnupg.dita
new file mode 100644
index 00000000..f083a7a6
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/python-gnupg.dita
@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_llw_kzx_5db">
+        <title>The python-gnupg package maintained by Vinay Sajip</title>
+        <body>
+            <p>This is arguably the most popular means of integrating GPG with Python. The package
+        utilises the <codeph>subprocess</codeph> module to implement wrappers for the
+          <cmdname>gpg</cmdname> and <cmdname>gpg2</cmdname> executables normally invoked on the command
+        line (<cmdname>gpg.exe</cmdname> and <cmdname>gpg2.exe</cmdname> on Windows).</p>
+      <p>The popularity of this package stemmed from its ease of use and capability in providing the
+        most commonly required features.</p>
+      <p>Unfortunately it has been beset by a number of security issues in the past; most of which
+        stemmed from using unsafe methods of accessing the command line via the
+          <codeph>subprocess</codeph> calls. While some effort has been made over the last two to
+        three years (as of 2018) to mitigate this, particularly by no longer providing shell access
+        through those subprocess calls, the wrapper is still somewhat limited in the scope of its
+        GnuPG features coverage.</p>
+      <p>The python-gnupg package is available under the MIT license.</p>
+        </body>
+    </topic>
+</dita>
diff --git a/lang/python/docs/dita/howto/part02/requirements.dita b/lang/python/docs/dita/howto/part02/requirements.dita
new file mode 100644
index 00000000..584219d5
--- /dev/null
+++ b/lang/python/docs/dita/howto/part02/requirements.dita
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE dita PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
+<dita>
+    <topic id="topic_zqn_nfy_5db">
+        <title>Requirements</title>
+        <body>
+            <p>The GPGME Python bindings only have three requirements:</p>
+      <p>
+        <ol id="ol_rbw_qfy_5db">
+          <li>A suitable version of Python 2 or Python 3. With Python 2 that means Python 2.7 and
+            with Python 3 that means Python 3.4 or higher.</li>
+          <li>SWIG.</li>
+          <li>GPGME itself. Which also means that all of GPGME's dependencies must be installed
+            too.</li>
+        </ol>
+      </p>
+      <p/>
+        </body>
+    </topic>
+</dita>