aboutsummaryrefslogtreecommitdiffstats
path: root/lang/python/docs/dita/howto/part02
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--lang/python/docs/dita/howto/part02/c-api.dita17
-rw-r--r--lang/python/docs/dita/howto/part02/context.dita21
-rw-r--r--lang/python/docs/dita/howto/part02/daesh.dita20
-rw-r--r--lang/python/docs/dita/howto/part02/differences-to-others.dita11
-rw-r--r--lang/python/docs/dita/howto/part02/fundamentals.dita12
-rw-r--r--lang/python/docs/dita/howto/part02/gpgme-concepts.dita10
-rw-r--r--lang/python/docs/dita/howto/part02/installation.dita10
-rw-r--r--lang/python/docs/dita/howto/part02/installing.dita23
-rw-r--r--lang/python/docs/dita/howto/part02/no-pypi.dita19
-rw-r--r--lang/python/docs/dita/howto/part02/no-rest.dita20
-rw-r--r--lang/python/docs/dita/howto/part02/pyme.dita25
-rw-r--r--lang/python/docs/dita/howto/part02/python-bindings.dita16
-rw-r--r--lang/python/docs/dita/howto/part02/python-gnupg.dita22
-rw-r--r--lang/python/docs/dita/howto/part02/requirements.dita20
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>
generated by cgit v1.2.3 (git 2.25.1) at 2025-10-30 07:09:15 +0000