A C API

From f0063afa71bc7e71f19d174acc2fde26f0c11850 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 15 May 2018 13:13:16 +1000 Subject: docs: python bindings HOWTO - DITA XML version * Due to the org-babel bug which breaks Python source code examples beyond the most simple snippets, ported the HOWTO to a source format which I *know* for sure won't break it. * Details of the org-mode bug is in https://dev.gnupg.org/T3977 * DITA project uses DITA-OT 2.x (2.4 or 2.5, IIRC) with support for DITA 1.3. * source files were written with oXygenXML Editor 20.0, hence the oXygenXML project file in the directory; however only the .ditamap and .dita files are required to generate any output with the DITA-OT. Signed-off-by: Ben McGinnes --- lang/python/docs/dita/howto/part02/c-api.dita | 17 +++++++++++++++ lang/python/docs/dita/howto/part02/context.dita | 21 ++++++++++++++++++ lang/python/docs/dita/howto/part02/daesh.dita | 20 +++++++++++++++++ .../dita/howto/part02/differences-to-others.dita | 11 ++++++++++ .../docs/dita/howto/part02/fundamentals.dita | 12 +++++++++++ .../docs/dita/howto/part02/gpgme-concepts.dita | 10 +++++++++ .../docs/dita/howto/part02/installation.dita | 10 +++++++++ lang/python/docs/dita/howto/part02/installing.dita | 23 ++++++++++++++++++++ lang/python/docs/dita/howto/part02/no-pypi.dita | 19 ++++++++++++++++ lang/python/docs/dita/howto/part02/no-rest.dita | 20 +++++++++++++++++ lang/python/docs/dita/howto/part02/pyme.dita | 25 ++++++++++++++++++++++ .../docs/dita/howto/part02/python-bindings.dita | 16 ++++++++++++++ .../docs/dita/howto/part02/python-gnupg.dita | 22 +++++++++++++++++++ .../docs/dita/howto/part02/requirements.dita | 20 +++++++++++++++++ 14 files changed, 246 insertions(+) create mode 100644 lang/python/docs/dita/howto/part02/c-api.dita create mode 100644 lang/python/docs/dita/howto/part02/context.dita create mode 100644 lang/python/docs/dita/howto/part02/daesh.dita create mode 100644 lang/python/docs/dita/howto/part02/differences-to-others.dita create mode 100644 lang/python/docs/dita/howto/part02/fundamentals.dita create mode 100644 lang/python/docs/dita/howto/part02/gpgme-concepts.dita create mode 100644 lang/python/docs/dita/howto/part02/installation.dita create mode 100644 lang/python/docs/dita/howto/part02/installing.dita create mode 100644 lang/python/docs/dita/howto/part02/no-pypi.dita create mode 100644 lang/python/docs/dita/howto/part02/no-rest.dita create mode 100644 lang/python/docs/dita/howto/part02/pyme.dita create mode 100644 lang/python/docs/dita/howto/part02/python-bindings.dita create mode 100644 lang/python/docs/dita/howto/part02/python-gnupg.dita create mode 100644 lang/python/docs/dita/howto/part02/requirements.dita (limited to 'lang/python/docs/dita/howto/part02') 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 @@ + + + + + A C API + +

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.

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.

+ + + 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 @@ + + + + + Context + +

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).

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.

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.

+ + + 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 @@ + + + + + The gnupg package created and maintained by Isis Lovecruft + +

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 + subprocess to call the gpg or gpg2 + binaries, but did so somewhat more securely.

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.

The gnupg package is available under the GNU General Public License version 3.0 (or any + later version).

+ + + 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 @@ + + + + + Difference between the Python bindings and other GnuPG Python packages + +

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.

+ + + 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 @@ + + + + + Fundamentals + +

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.

+ + + 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 @@ + + + + + GPGME Concepts + +

+ + + 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 @@ + + + + + GPGME Python bindings installation + +

+ + + 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 @@ + + + + + Installing + +

Installing the Python bindings is effectively achieved by compiling and installing GPGME + itself.

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 $PATH.

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 $PATH. It + specifically checks for the python and python3 + executables first and then checks for specific version numbers.

For Python 2 it checks for these executables in this order: python, + python2 and python2.7.

For Python 3 it checks for these executables in this order: python3, + python3.6, python3.5 and + python3.4.

+ + + 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 @@ + + + + + No PyPI + +

Most third-party Python packages and modules are available and distributed through + the Python Package Installer, known as PyPI.

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.

This is because the bindings use SWIG to dynamically generate C bindings against + gpgme.h and gpgme.h is generated from + gpgme.h.in 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.

+ + + 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 @@ + + + + + No REST + +

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 not a + REST API. Nor indeed could it ever be one.

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.

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.

+ + + 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 @@ + + + + + The PyME package maintained by Martin Albrecht + +

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 + Short History documentShort_History.org and/or + Short_History.html. in the Python bindings docs/ + directory.The lang/python/docs/ directory in the GPGME + source.

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 python-gnupg or gnupg + packages.

The PyME package is only available for Python 2.6 and 2.7.

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.

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).

+ + + 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 @@ + + + + + Python Bindings + +

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.

The bindings are generated dynamically with SWIG and the copy of gpgme.h + generated when GPGME is compiled.

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 gpgme.h.

+ + + 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 @@ + + + + + The python-gnupg package maintained by Vinay Sajip + +

This is arguably the most popular means of integrating GPG with Python. The package + utilises the subprocess module to implement wrappers for the + gpg and gpg2 executables normally invoked on the command + line (gpg.exe and gpg2.exe on Windows).

The popularity of this package stemmed from its ease of use and capability in providing the + most commonly required features.

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 + subprocess 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.

The python-gnupg package is available under the MIT license.

+ + + 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 @@ + + + + + Requirements + +

The GPGME Python bindings only have three requirements:

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.
SWIG.
GPGME itself. Which also means that all of GPGME's dependencies must be installed + too.

+ + + -- cgit v1.2.3