python: Remove Python bindings

* README: Update.
* configure.ac: Remove checks, variables and file generations related to
the Python bindings. Remove python from available_languages and
default_languages.
* lang/Makefile.am (DIST_SUBDIRS): Remove python.
* lang/python: Remove.
* m4/ax_pkg_swig.m4, m4/ax_python_devel.m4, m4/python.m4: Remove.
--

The Python bindings have been moved to a separate Git repository:
gpgmepy.

GnuPG-bug-id: 7262

1 files changed, 0 insertions, 3379 deletions

diff --git a/lang/python/doc/src/gpgme-python-howto.org b/lang/python/doc/src/gpgme-python-howto.org
deleted file mode 100644
index c40e2249..00000000
--- a/lang/python/doc/src/gpgme-python-howto.org
+++ /dev/null
@@ -1,3379 +0,0 @@
-# -*- mode: org -*-
-#+TITLE: GNU Privacy Guard (GnuPG) Made Easy Python Bindings HOWTO (English)
-#+AUTHOR: Ben McGinnes
-#+LATEX_COMPILER: xelatex
-#+LATEX_CLASS: article
-#+LATEX_CLASS_OPTIONS: [12pt]
-#+LATEX_HEADER: \usepackage{xltxtra}
-#+LATEX_HEADER: \usepackage[margin=1in]{geometry}
-#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
-#+LATEX_HEADER: \author{Ben McGinnes <[email protected]>}
-
-
-* Introduction
-  :PROPERTIES:
-  :CUSTOM_ID: intro
-  :END:
-
-| Version:        | 0.1.5                                    |
-| GPGME Version:  | 1.13.0                                   |
-| Author:         | Ben McGinnes <[email protected]>             |
-| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
-| Language:       | Australian English, British English      |
-| Language codes: | en-AU, en-GB, en                         |
-
-This document provides basic instruction in how to use the GPGME
-Python bindings to programmatically leverage the GPGME library.
-
-
-** Python 2 versus Python 3
-   :PROPERTIES:
-   :CUSTOM_ID: py2-vs-py3
-   :END:
-
-Though the GPGME Python bindings themselves provide support for both
-Python 2 and 3, the focus is unequivocally on Python 3 and
-specifically from Python 3.4 and above.  As a consequence all the
-examples and instructions in this guide use Python 3 code.
-
-Much of it will work with Python 2, but much of it also deals with
-Python 3 byte literals, particularly when reading and writing data.
-Developers concentrating on Python 2.7, and possibly even 2.6, will
-need to make the appropriate modifications to support the older string
-and unicode types as opposed to bytes.
-
-There are multiple reasons for concentrating on Python 3; some of
-which relate to the immediate integration of these bindings, some of
-which relate to longer term plans for both GPGME and the python
-bindings and some of which relate to the impending EOL period for
-Python 2.7.  Essentially, though, there is little value in tying the
-bindings to a version of the language which is a dead end and the
-advantages offered by Python 3 over Python 2 make handling the data
-types with which GPGME deals considerably easier.
-
-
-** Examples
-   :PROPERTIES:
-   :CUSTOM_ID: howto-python3-examples
-   :END:
-
-All of the examples found in this document can be found as Python 3
-scripts in the =lang/python/examples/howto= directory.
-
-
-** Unofficial Drafts
-   :PROPERTIES:
-   :CUSTOM_ID: unofficial-drafts
-   :END:
-
-In addition to shipping with each release of GPGME, there is a section
-on locations to read or download [[#draft-editions][draft editions]] of this document from
-at the end of it.  These are unofficial versions produced in between
-major releases.
-
-
-** What's New
-   :PROPERTIES:
-   :CUSTOM_ID: new-stuff
-   :END:
-
-Full details of what is new are now available in the [[file:what-is-new.org][What's New]] file
-and archives of the preceding /What's New/ sections are available in
-the [[file:what-was-new][What Was New]] file.
-
-
-*** New in GPGME 1·13·0
-    :PROPERTIES:
-    :CUSTOM_ID: new-stuff-1-13-0
-    :END:
-
-See the [[file:what-is-new#new-stuff-1-13-0][What's New]] document for what is new in version 1.13.0.
-
-
-*** New in GPGME 1·12·0
-    :PROPERTIES:
-    :CUSTOM_ID: new-stuff-1-12-0
-    :END:
-
-See the [[file:what-was-new#new-stuff-1-12-0][What Was New]] document for what was new in version 1.12.0.
-
-
-* GPGME Concepts
-  :PROPERTIES:
-  :CUSTOM_ID: gpgme-concepts
-  :END:
-
-
-** A C API
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-c-api
-   :END:
-
-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.
-
-
-** Python bindings
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-python-bindings
-   :END:
-
-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=.
-
-
-** Difference between the Python bindings and other GnuPG Python packages
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-python-bindings-diffs
-   :END:
-
-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.
-
-
-*** The python-gnupg package maintained by Vinay Sajip
-    :PROPERTIES:
-    :CUSTOM_ID: diffs-python-gnupg
-    :END:
-
-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.
-
-
-*** The gnupg package created and maintained by Isis Lovecruft
-    :PROPERTIES:
-    :CUSTOM_ID: diffs-isis-gnupg
-    :END:
-
-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).
-
-
-*** The PyME package maintained by Martin Albrecht
-    :PROPERTIES:
-    :CUSTOM_ID: diffs-pyme
-    :END:
-
-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 [[file:short-history.org][Short History]] document.[fn:1]
-
-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).
-
-
-* GPGME Python bindings installation
-  :PROPERTIES:
-  :CUSTOM_ID: gpgme-python-install
-  :END:
-
-
-** No PyPI
-   :PROPERTIES:
-   :CUSTOM_ID: do-not-use-pypi
-   :END:
-
-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.
-
-See the additional notes regarding [[#snafu-cffi][CFFI and SWIG]] at the end of this
-section for further details.
-
-
-** Requirements
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-python-requirements
-   :END:
-
-The GPGME Python bindings only have three requirements:
-
-1. A suitable version of Python 2 or Python 3.  With Python 2 that
-   means CPython 2.7 and with Python 3 that means CPython 3.4 or
-   higher.
-2. [[https://www.swig.org][SWIG]].
-3. GPGME itself.  Which also means that all of GPGME's dependencies
-   must be installed too.
-
-
-*** Recommended Additions
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-python-recommendations
-   :END:
-
-Though none of the following are absolute requirements, they are all
-recommended for use with the Python bindings.  In some cases these
-recommendations refer to which version(s) of CPython to use the
-bindings with, while others refer to third party modules which provide
-a significant advantage in some way.
-
-1. If possible, use Python 3 instead of 2.
-2. Favour a more recent version of Python since even 3.4 is due to
-   reach EOL soon.  In production systems and services, Python 3.6
-   should be robust enough to be relied on.
-3. If possible add the following Python modules which are not part of
-   the standard library: [[http://docs.python-requests.org/en/latest/index.html][Requests]], [[https://cython.org/][Cython]], [[https://pendulum.eustace.io/][Pendulum]] and [[https://github.com/Selfnet/hkp4py][hkp4py]].
-
-Chances are quite high that at least the first one and maybe two of
-those will already be installed.
-
-Note that, as with Cython, some of advanced use case scenarios will
-bring with them additional requirements.  Most of these will be fairly
-well known and commonly installed ones, however, which are in many
-cases likely to have already been installed on many systems or be
-familiar to Python programmers.
-
-
-** Installation
-   :PROPERTIES:
-   :CUSTOM_ID: installation
-   :END:
-
-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.7=, =python3.6=, =python3.5= and =python3.4=.[fn:2]
-
-On systems where =python= is actually =python3= and not =python2= it
-may be possible that =python2= may be overlooked, but there have been
-no reports of that actually occurring as yet.
-
-In the three months or so since the release of Python 3.7.0 there has
-been extensive testing and work with these bindings with no issues
-specifically relating to the new version of Python or any of the new
-features of either the language or the bindings.  This has also been
-the case with Python 3.7.1rc1.  With that in mind and given the
-release of Python 3.7.1 is scheduled for around the same time as GPGME
-1.12.0, the order of preferred Python versions has been changed to
-move Python 3.7 ahead of Python 3.6.
-
-
-*** Installing GPGME
-    :PROPERTIES:
-    :CUSTOM_ID: install-gpgme
-    :END:
-
-See the GPGME =README= file for details of how to install GPGME from
-source.
-
-
-** Known Issues
-   :PROPERTIES:
-   :CUSTOM_ID: snafu
-   :END:
-
-There are a few known issues with the current build process and the
-Python bindings.  For the most part these are easily addressed should
-they be encountered.
-
-
-*** Breaking Builds
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-a-swig-of-this-builds-character
-    :END:
-
-Occasionally when installing GPGME with the Python bindings included
-it may be observed that the =make= portion of that process induces a
-large very number of warnings and, eventually errors which end that
-part of the build process.  Yet following that with =make check= and
-=make install= appears to work seamlessly.
-
-The cause of this is related to the way SWIG needs to be called to
-dynamically generate the C bindings for GPGME in the first place.  So
-the entire process will always produce =lang/python/python2-gpg/= and
-=lang/python/python3-gpg/= directories.  These should contain the
-build output generated during compilation, including the complete
-bindings and module installed into =site-packages=.
-
-Occasionally the errors in the early part or some other conflict
-(e.g. not installing as */root/* or */su/*) may result in nothing
-being installed to the relevant =site-packages= directory and the
-build directory missing a lot of expected files.  Even when this
-occurs, the solution is actually quite simple and will always work.
-
-That solution is simply to run the following commands as either the
-*root* user or prepended with =sudo -H=[fn:3] in the =lang/python/=
-directory:
-
-#+BEGIN_SRC shell
-  /path/to/pythonX.Y setup.py build
-  /path/to/pythonX.Y setup.py build
-  /path/to/pythonX.Y setup.py install
-#+END_SRC
-
-Yes, the build command does need to be run twice.  Yes, you still need
-to run the potentially failing or incomplete steps during the
-=configure=, =make= and =make install= steps with installing GPGME.
-This is because those steps generate a lot of essential files needed,
-both by and in order to create, the bindings (including both the
-=setup.py= and =gpgme.h= files).
-
-
-**** IMPORTANT Note
-     :PROPERTIES:
-     :CUSTOM_ID: snafu-swig-build-note
-     :END:
-
-If specifying a selected number of languages to create bindings for,
-try to leave Python last.  Currently the majority of the other
-language bindings are also preceding Python of either version when
-listed alphabetically (not counting the Qt bindings).
-
-If Python is set to precede one of the other languages then it is
-possible that the errors described here may interrupt the build
-process before generating bindings for those other languages.  In
-these cases it may be preferable to configure all preferred language
-bindings separately with alternative =configure= steps for GPGME using
-the =--enable-languages=$LANGUAGE= option.
-
-Alternatively =make= (or =gmake=, depending on your platform) may be
-run with the the =-k= option, which tells make to keep going even if
-errors are encountered.  In that case the failure of one language's
-set of bindings to build should not hamper another language's bindings
-to build.
-
-
-*** Reinstalling Responsibly
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-lessons-for-the-lazy
-    :END:
-
-Regardless of whether you're installing for one version of Python or
-several, there will come a point where reinstallation is required.
-With most Python module installations, the installed files go into the
-relevant site-packages directory and are then forgotten about.  Then
-the module is upgraded, the new files are copied over the old and
-that's the end of the matter.
-
-While the same is true of these bindings, there have been intermittent
-issues observed on some platforms which have benefited significantly
-from removing all the previous installations of the bindings before
-installing the updated versions.
-
-Removing the previous version(s) is simply a matter of changing to the
-relevant =site-packages= directory for the version of Python in
-question and removing the =gpg/= directory and any accompanying
-egg-info files for that module.
-
-In most cases this will require root or administration privileges on
-the system, but the same is true of installing the module in the first
-place.
-
-
-*** Multiple installations
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-the-full-monty
-    :END:
-
-For a variety of reasons it may be either necessary or just preferable
-to install the bindings to alternative installed Python versions which
-meet the requirements of these bindings.
-
-On POSIX systems this will generally be most simply achieved by
-running the manual installation commands (build, build, install) as
-described in the previous section for each Python installation the
-bindings need to be installed to.
-
-As per the SWIG documentation: the compilers, libraries and runtime
-used to build GPGME and the Python Bindings *must* match those used to
-compile Python itself, including the version number(s) (at least going
-by major version numbers and probably minor numbers too).
-
-On most POSIX systems, including OS X, this will very likely be the
-case in most, if not all, cases.
-
-Note that from GPGME [[https://dev.gnupg.org/rMff6ff616aea6f59b7f2ce1176492850ecdf3851e][1.12.1]] the default installation installs to each
-version of Python it can find first.  That is that it will currently
-install for the first copies of Python versions 2.7, 3.4, 3.5, and so on
-up until the current dev branch that it finds.  Usually this will be in the
-same prefix as GPGME itself, but is dictated by the =$PATH= when the
-installation is performed.  The above instructions can still be
-performed on other python installations which the installer does not
-find, including alternative prefixes.
-
-
-
-*** Won't Work With Windows
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-runtime-not-funtime
-    :END:
-
-There are semi-regular reports of Windows users having considerable
-difficulty in installing and using the Python bindings at all.  Very
-often, possibly even always, these reports come from Cygwin users
-and/or MinGW users and/or Msys2 users.  Though not all of them have
-been confirmed, it appears that these reports have also come from
-people who installed Python using the Windows installer files from the
-[[https://python.org][Python website]] (i.e. mostly MSI installers, sometimes self-extracting
-=.exe= files).
-
-The Windows versions of Python are not built using Cygwin, MinGW or
-Msys2; they're built using Microsoft Visual Studio.  Furthermore the
-version used is /considerably/ more advanced than the version which
-MinGW obtained a small number of files from many years ago in order to
-be able to compile anything at all.  Not only that, but there are
-changes to the version of Visual Studio between some micro releases,
-though that is is particularly the case with Python 2.7, since it has
-been kept around far longer than it should have been.
-
-There are two theoretical solutions to this issue:
-
- 1. Compile and install the GnuPG stack, including GPGME and the
-    Python bindings using the same version of Microsoft Visual Studio
-    used by the Python Foundation to compile the version of Python
-    installed.
-
-    If there are multiple versions of Python then this will need to be
-    done with each different version of Visual Studio used for those
-    versions of Python.
-
- 2. Compile and install Python using the same tools used by choice,
-    such as MinGW or Msys2.
-
-Do *not* use the official Windows installer for Python unless
-following the first method.
-
-In this type of situation it may even be for the best to accept that
-there are less limitations on permissive software than free software
-and simply opt to use a recent version of the Community Edition of
-Microsoft Visual Studio to compile and build all of it, no matter
-what.
-
-Investigations into the extent or the limitations of this issue are
-ongoing.
-
-The following table lists the version of Microsoft Visual Studio which
-needs to be used when compiling GPGME and the Python bindings with
-each version of the CPython binary released [[https://www.python.org/downloads/windows/][for Windows]]:
-
-| CPython | Microsoft product name | runtime filename |
-|  2.7.6  |   Visual Studio 2008   |   MSVCR90.DLL    |
-|  3.4.0  |   Visual Studio 2010   |   MSVCR100.DLL   |
-|  3.5.0  |   Visual Studio 2015   |   *see below*    |
-|  3.6.0  |   Visual Studio 2015   |   *see below*    |
-|  3.7.0  |   Visual Studio 2017*  |   *see below*    |
-
-It is important to note that MingW and Msys2 ship with the Visual C
-runtime from Microsoft Visual Studio 2005 and are thus *incompatible*
-with all the versions of CPython which can be used with the GPGME
-Python bindings.
-
-It is also important to note that from CPython 3.5 onwards, the Python
-Foundation has adopted the reworking of the Visual C runtime which was
-performed for Visual Studio 2015 and aimed at resolving many of these
-kinds of issues.  Much greater detail on these issues and the correct
-file(s) to link to are available from Matthew Brett's invaluable page,
-[[https://matthew-brett.github.io/pydagogue/python_msvc.html][Using Microsoft Visual C with Python]].  It is also worth reading the
-Microsoft Developer Network blog post on [[http://blogs.msdn.com/b/vcblog/archive/2015/03/03/introducing-the-universal-crt.aspx][the universal CRT]] and Steve
-Dower's blog posts on Python extensions ([[http://stevedower.id.au/blog/building-for-python-3-5][part 1]] and [[http://stevedower.id.au/blog/building-for-python-3-5-part-two][part 2]]).
-
-The second of those two posts by Steve Dower contains the details of
-specific configuration options required for compiling anything to be
-used with official CPython releases.  In addition to those
-configuration and compiler settings to use, the versions of Visual
-Studio prior to Visual Studio 2015 did not support 64-bit systems by
-default.  So compiling a 64-bit version of these bindings for a 64-bit
-version of CPython 2.7 or 3.4 requires additional work.
-
-In addition to the blog posts, the [[https://wiki.python.org/moin/WindowsCompilers][Windows compilers]] wiki page on the
-CPython wiki is another essential reference on the relevant versions
-of Visual Studio to use and the degree of compatibility with CPython
-releases.
-
-Eventually someone will ask why there isn't an installable binary for
-Windows, which the GPGME of the licenses do not preclude as long as
-the source code is available in conjunction with such a release.
-
-The sheer number of versions of Visual Studio in conjunction with
-differing configuration options depending on the target Windows
-version and whether the architecture is 64-bit or 32-bit makes it
-difficult to provide a correct binary installer for Windows users.  At
-the bare minimum doing so would require the GnuPG project compile ten
-different versions of the bindings with each release; both 32-bit and
-64-bit versions for CPython 2.7 and 3.4, with 64-bit versions for both
-x86-64 (i.e. Intel and AMD) and ARM architectures for CPython 3.5,
-3.6, 3.7 and later releases.  That's the bare *minimum*, it'd probably
-be higher.
-
-Additionally, with only a binary installation used in conjunction with
-the CPython installer from =python.org= the advanced options available
-which utilise [[#cython][Cython]] will not be able to be used at all.  Cython
-depends on being able to compile the C code it generates and that too
-would need to utilise a matching runtime to both the installed version
-of CPython and these bindings in order to work with the bindings.
-
-Considering all of that, what do we recommend?
-
- 1. Use a recent version of CPython; at least 3.5, but ideally 3.6 or
-    later.
-
- 2. Use Visual Studio 2015 or the standalone build tools for Visual
-    Studio 2017 (or later).
-
- 3. Compile both CPython and GPGME with these bindings using the tools
-    selected in step 2.
-
- 4. Ignore MingW, Msys2 and the official CPython binary installers.
-
- 5. Be thankful the answer to this question wasn't simply to say
-    something like, “install Linux” or “install FreeBSD” (or even
-    Apple's OS X).
-
-
-*** CFFI is the Best™ and GPGME should use it instead of SWIG
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-cffi
-    :END:
-
-There are many reasons for favouring [[https://cffi.readthedocs.io/en/latest/overview.html][CFFI]] and proponents of it are
-quite happy to repeat these things as if all it would take to switch
-from SWIG to CFFI is repeating that list as if it were a new concept.
-
-The fact is that there are things which Python's CFFI implementation
-cannot handle in the GPGME C code.  Beyond that there are features of
-SWIG which are simply not available with CFFI at all.  SWIG generates
-the bindings to Python using the =gpgme.h= file, but that file is not
-a single version shipped with each release, it too is generated when
-GPGME is compiled.
-
-CFFI is currently unable to adapt to such a potentially mutable
-codebase.  If there were some means of applying SWIG's dynamic code
-generation to produce the Python/CFFI API modes of accessing the GPGME
-libraries (or the source source code directly), but such a thing does
-not exist yet either and it currently appears that work is needed in
-at least one of CFFI's dependencies before any of this can be
-addressed.
-
-So if you're a massive fan of CFFI; that's great, but if you want this
-project to switch to CFFI then rather than just insisting that it
-should, I'd suggest you volunteer to bring CFFI up to the level this
-project needs.
-
-If you're actually seriously considering doing so, then I'd suggest
-taking the =gpgme-tool.c= file in the GPGME =src/= directory and
-getting that to work with any of the CFFI API methods (not the ABI
-methods, they'll work with pretty much anything).  When you start
-running into trouble with "ifdefs" then you'll know what sort of
-things are lacking.  That doesn't even take into account the amount of
-work saved via SWIG's code generation techniques either.
-
-
-*** Virtualised Environments
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-venv
-    :END:
-
-It is fairly common practice amongst Python developers to, as much as
-possible, use packages like virtualenv to keep various things that are
-to be installed from interfering with each other.  Given how much of
-the GPGME bindings is often at odds with the usual pythonic way of
-doing things, it stands to reason that this would be called into
-question too.
-
-As it happens the answer as to whether or not the bindings can be used
-with virtualenv, the answer is both yes and no.
-
-In general we recommend installing to the relevant path and matching
-prefix of GPGME itself.  Which means that when GPGME, and ideally the
-rest of the GnuPG stack, is installed to a prefix like =/usr/local= or
-=/opt/local= then the bindings would need to be installed to the main
-Python installation and not a virtualised abstraction.  Attempts to
-separate the two in the past have been known to cause weird and
-intermittent errors ranging from minor annoyances to complete failures
-in the build process.
-
-As a consequence we only recommend building with and installing to the
-main Python installations within the same prefix as GPGME is installed
-to or which are found by GPGME's configuration stage immediately prior
-to running the make commands.  Which is exactly what the compiling and
-installing process of GPGME does by default.
-
-Once that is done, however, it appears that a copy of the compiled
-module may be installed into a virtualenv of the same major and minor
-version matching the build.  Alternatively it is possible to utilise a
-=sites.pth= file in the =site-packages/= directory of a virtualenv
-installation, which links back to the system installations
-corresponding directory in order to import anything installed system
-wide.  This may or may not be appropriate on a case by case basis.
-
-Though extensive testing of either of these options is not yet
-complete, preliminary testing of them indicates that both are viable
-as long as the main installation is complete.  Which means that
-certain other options normally restricted to virtual environments are
-also available, including integration with pythonic test suites
-(e.g. [[https://docs.pytest.org/en/latest/index.html][pytest]]) and other large projects.
-
-That said, it is worth reiterating the warning regarding non-standard
-installations.  If one were to attempt to install the bindings only to
-a virtual environment without somehow also including the full GnuPG
-stack (or enough of it as to include GPGME) then it is highly likely
-that errors would be encountered at some point and more than a little
-likely that the build process itself would break.
-
-If a degree of separation from the main operating system is still
-required in spite of these warnings, then consider other forms of
-virtualisation.  Either a virtual machine (e.g. [[https://www.virtualbox.org/][VirtualBox]]), a
-hardware emulation layer (e.g. [[https://www.qemu.org/][QEMU]]) or an application container
-(e.g. [[https://www.docker.com/why-docker][Docker]]).
-
-Finally it should be noted that the limited tests conducted thus far
-have been using the =virtualenv= command in a new directory to create
-the virtual python environment.  As opposed to the standard =python3
--m venv= and it is possible that this will make a difference depending
-on the system and version of Python in use.  Another option is to run
-the command =python3 -m virtualenv /path/to/install/virtual/thingy=
-instead.
-
-
-*** Post installation
-    :PROPERTIES:
-    :CUSTOM_ID: snafu-docs
-    :END:
-
-Following installation it is recommended to move the
-=post_installer.py= script from the =lang/python/examples/howto/=
-directory to the =lang/python/= directory and run it.  This will fix
-or restore files needed by Sphinx which may be removed during a
-distribution build for release.  It will also generate reST files from
-Org mode files with Pandoc and generate Texinfo files from Org mode
-files with GNU Emacs and Org mode (in batch mode).  Additionally it
-will fix the UTF-8 declaration line in the Texinfo files (Emacs
-expects "UTF-8" to be "utf-8").
-
-
-* Fundamentals
-  :PROPERTIES:
-  :CUSTOM_ID: howto-fund-a-mental
-  :END:
-
-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.
-
-
-** No REST
-   :PROPERTIES:
-   :CUSTOM_ID: no-rest-for-the-wicked
-   :END:
-
-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 that this HOWTO deals with.
-
-
-** Context
-   :PROPERTIES:
-   :CUSTOM_ID: howto-get-context
-   :END:
-
-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.
-
-
-* Working with keys
-  :PROPERTIES:
-  :CUSTOM_ID: howto-keys
-  :END:
-
-
-** Key selection
-   :PROPERTIES:
-   :CUSTOM_ID: howto-keys-selection
-   :END:
-
-Selecting keys to encrypt to or to sign with will be a common
-occurrence when working with GPGMe and the means available for doing
-so are quite simple.
-
-They do depend on utilising a Context; however once the data is
-recorded in another variable, that Context does not need to be the
-same one which subsequent operations are performed.
-
-The easiest way to select a specific key is by searching for that
-key's key ID or fingerprint, preferably the full fingerprint without
-any spaces in it.  A long key ID will probably be okay, but is not
-advised and short key IDs are already a problem with some being
-generated to match specific patterns.  It does not matter whether the
-pattern is upper or lower case.
-
-So this is the best method:
-
-#+BEGIN_SRC python -i
-import gpg
-
-k = gpg.Context().keylist(pattern="258E88DCBD3CD44D8E7AB43F6ECB6AF0DEADBEEF")
-keys = list(k)
-#+END_SRC
-
-This is passable and very likely to be common:
-
-#+BEGIN_SRC python -i
-import gpg
-
-k = gpg.Context().keylist(pattern="0x6ECB6AF0DEADBEEF")
-keys = list(k)
-#+END_SRC
-
-And this is a really bad idea:
-
-#+BEGIN_SRC python -i
-import gpg
-
-k = gpg.Context().keylist(pattern="0xDEADBEEF")
-keys = list(k)
-#+END_SRC
-
-Alternatively it may be that the intention is to create a list of keys
-which all match a particular search string.  For instance all the
-addresses at a particular domain, like this:
-
-#+BEGIN_SRC python -i
-import gpg
-
-ncsc = gpg.Context().keylist(pattern="ncsc.mil")
-nsa = list(ncsc)
-#+END_SRC
-
-
-*** Counting keys
-    :PROPERTIES:
-    :CUSTOM_ID: howto-keys-counting
-    :END:
-
-Counting the number of keys in your public keybox (=pubring.kbx=), the
-format which has superseded the old keyring format (=pubring.gpg= and
-=secring.gpg=), or the number of secret keys is a very simple task.
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-seckeys = c.keylist(pattern=None, secret=True)
-pubkeys = c.keylist(pattern=None, secret=False)
-
-seclist = list(seckeys)
-secnum = len(seclist)
-
-publist = list(pubkeys)
-pubnum = len(publist)
-
-print("""
-  Number of secret keys:  {0}
-  Number of public keys:  {1}
-""".format(secnum, pubnum))
-#+END_SRC
-
-NOTE: The [[#cython][Cython]] introduction in the [[#advanced-use][Advanced and Experimental]]
-section uses this same key counting code with Cython to demonstrate
-some areas where Cython can improve performance even with the
-bindings.  Users with large public keyrings or keyboxes, for instance,
-should consider these options if they are comfortable with using
-Cython.
-
-
-** Get key
-   :PROPERTIES:
-   :CUSTOM_ID: howto-get-key
-   :END:
-
-An alternative method of getting a single key via its fingerprint is
-available directly within a Context with =Context().get_key=.  This is
-the preferred method of selecting a key in order to modify it, sign or
-certify it and for obtaining relevant data about a single key as a
-part of other functions; when verifying a signature made by that key,
-for instance.
-
-By default this method will select public keys, but it can select
-secret keys as well.
-
-This first example demonstrates selecting the current key of Werner
-Koch, which is due to expire at the end of 2018:
-
-#+BEGIN_SRC python -i
-import gpg
-
-fingerprint = "80615870F5BAD690333686D0F2AD85AC1E42B367"
-key = gpg.Context().get_key(fingerprint)
-#+END_SRC
-
-Whereas this example demonstrates selecting the author's current key
-with the =secret= key word argument set to =True=:
-
-#+BEGIN_SRC python -i
-import gpg
-
-fingerprint = "DB4724E6FA4286C92B4E55C4321E4E2373590E5D"
-key = gpg.Context().get_key(fingerprint, secret=True)
-#+END_SRC
-
-It is, of course, quite possible to select expired, disabled and
-revoked keys with this function, but only to effectively display
-information about those keys.
-
-It is also possible to use both unicode or string literals and byte
-literals with the fingerprint when getting a key in this way.
-
-
-** Importing keys
-   :PROPERTIES:
-   :CUSTOM_ID: howto-import-key
-   :END:
-
-Importing keys is possible with the =key_import()= 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.
-
-The following example retrieves one or more keys 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.
-
-#+BEGIN_SRC python -i
-import gpg
-import os.path
-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)
-result = c.key_import(r.content)
-
-if result is not None and hasattr(result, "considered") is False:
-    print(result)
-elif result is not None and hasattr(result, "considered") is True:
-    num_keys = len(result.imports)
-    new_revs = result.new_revocations
-    new_sigs = result.new_signatures
-    new_subs = result.new_sub_keys
-    new_uids = result.new_user_ids
-    new_scrt = result.secret_imported
-    nochange = result.unchanged
-    print("""
-  The total number of keys considered for import was:  {0}
-
-     Number of keys revoked:  {1}
-   Number of new signatures:  {2}
-      Number of new subkeys:  {3}
-     Number of new user IDs:  {4}
-  Number of new secret keys:  {5}
-   Number of unchanged keys:  {6}
-
-  The key IDs for all considered keys were:
-""".format(num_keys, new_revs, new_sigs, new_subs, new_uids, new_scrt,
-           nochange))
-    for i in range(num_keys):
-        print("{0}\n".format(result.imports[i].fpr))
-else:
-    pass
-#+END_SRC
-
-NOTE: When searching for a key ID of any length or a fingerprint
-(without spaces), the SKS servers require the the leading =0x=
-indicative of hexadecimal be included.  Also note that the old short
-key IDs (e.g. =0xDEADBEEF=) should no longer be used due to the
-relative ease by which such key IDs can be reproduced, as demonstrated
-by the Evil32 Project in 2014 (which was subsequently exploited in
-2016).
-
-Testing for whether a string in any given search is or may be a
-hexadecimal value which may be missing the leading =0x= is a simple
-matter of using a try/except statement which attempts to convert the
-string as hex to an integer and then back to hex; then using that to
-search with.  Raising a ValueError simply results in treating the
-string as a string.  This is the method and logic utilised in the
-=import-keys-hkp.py= script (see below).
-
-
-*** Working with ProtonMail
-    :PROPERTIES:
-    :CUSTOM_ID: import-protonmail
-    :END:
-
-Here is a variation on the example above which checks the constrained
-ProtonMail keyserver for ProtonMail public keys.
-
-#+BEGIN_SRC python -i
-import gpg
-import requests
-import sys
-
-print("""
-This script searches the ProtonMail key server for the specified key and
-imports it.
-""")
-
-c = gpg.Context(armor=True)
-url = "https://api.protonmail.ch/pks/lookup"
-ksearch = []
-
-if len(sys.argv) >= 2:
-    keyterm = sys.argv[1]
-else:
-    keyterm = input("Enter the key ID, UID or search string: ")
-
-if keyterm.count("@") == 2 and keyterm.startswith("@") is True:
-    ksearch.append(keyterm[1:])
-    ksearch.append(keyterm[1:])
-    ksearch.append(keyterm[1:])
-elif keyterm.count("@") == 1 and keyterm.startswith("@") is True:
-    ksearch.append("{0}@protonmail.com".format(keyterm[1:]))
-    ksearch.append("{0}@protonmail.ch".format(keyterm[1:]))
-    ksearch.append("{0}@pm.me".format(keyterm[1:]))
-elif keyterm.count("@") == 0:
-    ksearch.append("{0}@protonmail.com".format(keyterm))
-    ksearch.append("{0}@protonmail.ch".format(keyterm))
-    ksearch.append("{0}@pm.me".format(keyterm))
-elif keyterm.count("@") == 2 and keyterm.startswith("@") is False:
-    uidlist = keyterm.split("@")
-    for uid in uidlist:
-        ksearch.append("{0}@protonmail.com".format(uid))
-        ksearch.append("{0}@protonmail.ch".format(uid))
-        ksearch.append("{0}@pm.me".format(uid))
-elif keyterm.count("@") > 2:
-    uidlist = keyterm.split("@")
-    for uid in uidlist:
-        ksearch.append("{0}@protonmail.com".format(uid))
-        ksearch.append("{0}@protonmail.ch".format(uid))
-        ksearch.append("{0}@pm.me".format(uid))
-else:
-    ksearch.append(keyterm)
-
-for k in ksearch:
-    payload = {"op": "get", "search": k}
-    try:
-        r = requests.get(url, verify=True, params=payload)
-        if r.ok is True:
-            result = c.key_import(r.content)
-        elif r.ok is False:
-            result = r.content
-    except Exception as e:
-        result = None
-
-    if result is not None and hasattr(result, "considered") is False:
-        print("{0} for {1}".format(result.decode(), k))
-    elif result is not None and hasattr(result, "considered") is True:
-        num_keys = len(result.imports)
-        new_revs = result.new_revocations
-        new_sigs = result.new_signatures
-        new_subs = result.new_sub_keys
-        new_uids = result.new_user_ids
-        new_scrt = result.secret_imported
-        nochange = result.unchanged
-        print("""
-The total number of keys considered for import was:  {0}
-
-With UIDs wholely or partially matching the following string:
-
-        {1}
-
-   Number of keys revoked:  {2}
- Number of new signatures:  {3}
-    Number of new subkeys:  {4}
-   Number of new user IDs:  {5}
-Number of new secret keys:  {6}
- Number of unchanged keys:  {7}
-
-The key IDs for all considered keys were:
-""".format(num_keys, k, new_revs, new_sigs, new_subs, new_uids, new_scrt,
-           nochange))
-        for i in range(num_keys):
-            print(result.imports[i].fpr)
-        print("")
-    elif result is None:
-        print(e)
-#+END_SRC
-
-Both the above example, [[../examples/howto/pmkey-import.py][pmkey-import.py]], and a version which prompts
-for an alternative GnuPG home directory, [[../examples/howto/pmkey-import-alt.py][pmkey-import-alt.py]], are
-available with the other examples and are executable scripts.
-
-Note that while the ProtonMail servers are based on the SKS servers,
-their server is related more to their API and is not feature complete
-by comparison to the servers in the SKS pool.  One notable difference
-being that the ProtonMail server does not permit non ProtonMail users
-to update their own keys, which could be a vector for attacking
-ProtonMail users who may not receive a key's revocation if it had been
-compromised.
-
-
-*** Importing with HKP for Python
-    :PROPERTIES:
-    :CUSTOM_ID: import-hkp4py
-    :END:
-
-Performing the same tasks with the [[https://github.com/Selfnet/hkp4py][hkp4py module]] (available via PyPI)
-is not too much different, but does provide a number of options of
-benefit to end users.  Not least of which being the ability to perform
-some checks on a key before importing it or not.  For instance it may
-be the policy of a site or project to only import keys which have not
-been revoked.  The hkp4py module permits such checks prior to the
-importing of the keys found.
-
-#+BEGIN_SRC python -i
-import gpg
-import hkp4py
-import sys
-
-c = gpg.Context()
-server = hkp4py.KeyServer("hkps://hkps.pool.sks-keyservers.net")
-results = []
-keys = []
-
-if len(sys.argv) > 2:
-    pattern = " ".join(sys.argv[1:])
-elif len(sys.argv) == 2:
-    pattern = sys.argv[1]
-else:
-    pattern = input("Enter the pattern to search for keys or user IDs: ")
-
-
-if pattern is not None:
-    try:
-        key = server.search(hex(int(pattern, 16)))
-        keyed = True
-    except ValueError as ve:
-        key = server.search(pattern)
-        keyed = False
-
-    if key is not None:
-        keys.append(key[0])
-        if keyed is True:
-            try:
-                fob = server.search(pattern)
-            except:
-                fob = None
-            if fob is not None:
-                keys.append(fob[0])
-        else:
-            pass
-    else:
-        pass
-
-    for logrus in pattern.split():
-        try:
-            key = server.search(hex(int(logrus, 16)))
-            hexed = True
-        except ValueError as ve:
-            key = server.search(logrus)
-            hexed = False
-
-        if key is not None:
-            keys.append(key[0])
-            if hexed is True:
-                try:
-                    fob = server.search(logrus)
-                except:
-                    fob = None
-                if fob is not None:
-                    keys.append(fob[0])
-            else:
-                pass
-        else:
-            pass
-
-
-if len(keys) > 0:
-    for key in keys:
-        import_result = c.key_import(key.key_blob)
-        results.append(import_result)
-
-for result in results:
-    if result is not None and hasattr(result, "considered") is False:
-        print(result)
-    elif result is not None and hasattr(result, "considered") is True:
-        num_keys = len(result.imports)
-        new_revs = result.new_revocations
-        new_sigs = result.new_signatures
-        new_subs = result.new_sub_keys
-        new_uids = result.new_user_ids
-        new_scrt = result.secret_imported
-        nochange = result.unchanged
-        print("""
-The total number of keys considered for import was:  {0}
-
-   Number of keys revoked:  {1}
- Number of new signatures:  {2}
-    Number of new subkeys:  {3}
-   Number of new user IDs:  {4}
-Number of new secret keys:  {5}
- Number of unchanged keys:  {6}
-
-The key IDs for all considered keys were:
-""".format(num_keys, new_revs, new_sigs, new_subs, new_uids, new_scrt,
-           nochange))
-        for i in range(num_keys):
-            print(result.imports[i].fpr)
-        print("")
-    else:
-        pass
-#+END_SRC
-
-Since the hkp4py module handles multiple keys just as effectively as
-one (=keys= is a list of responses per matching key), the example
-above is able to do a little bit more with the returned data before
-anything is actually imported.
-
-
-*** Importing from ProtonMail with HKP for Python
-    :PROPERTIES:
-    :CUSTOM_ID: import-protonmail-hkp4py
-    :END:
-
-Though this can provide certain benefits even when working with
-ProtonMail, the scope is somewhat constrained there due to the
-limitations of the ProtonMail keyserver.
-
-For instance, searching the SKS keyserver pool for the term "gnupg"
-produces hundreds of results from any time the word appears in any
-part of a user ID.  Performing the same search on the ProtonMail
-keyserver returns zero results, even though there are at least two
-test accounts which include it as part of the username.
-
-The cause of this discrepancy is the deliberate configuration of that
-server by ProtonMail to require an exact match of the full email
-address of the ProtonMail user whose key is being requested.
-Presumably this is intended to reduce breaches of privacy of their
-users as an email address must already be known before a key for that
-address can be obtained.
-
-
-**** Import from ProtonMail via HKP for Python Example no. 1
-     :PROPERTIES:
-     :CUSTOM_ID: import-hkp4py-pm1
-     :END:
-
-The following script is available with the rest of the examples under
-the somewhat less than original name, =pmkey-import-hkp.py=.
-
-#+BEGIN_SRC python -i
-import gpg
-import hkp4py
-import os.path
-import sys
-
-print("""
-This script searches the ProtonMail key server for the specified key and
-imports it.
-
-Usage:  pmkey-import-hkp.py [search strings]
-""")
-
-c = gpg.Context(armor=True)
-server = hkp4py.KeyServer("hkps://api.protonmail.ch")
-keyterms = []
-ksearch = []
-allkeys = []
-results = []
-paradox = []
-homeless = None
-
-if len(sys.argv) > 2:
-    keyterms = sys.argv[1:]
-elif len(sys.argv) == 2:
-    keyterm = sys.argv[1]
-    keyterms.append(keyterm)
-else:
-    key_term = input("Enter the key ID, UID or search string: ")
-    keyterms = key_term.split()
-
-for keyterm in keyterms:
-    if keyterm.count("@") == 2 and keyterm.startswith("@") is True:
-        ksearch.append(keyterm[1:])
-        ksearch.append(keyterm[1:])
-        ksearch.append(keyterm[1:])
-    elif keyterm.count("@") == 1 and keyterm.startswith("@") is True:
-        ksearch.append("{0}@protonmail.com".format(keyterm[1:]))
-        ksearch.append("{0}@protonmail.ch".format(keyterm[1:]))
-        ksearch.append("{0}@pm.me".format(keyterm[1:]))
-    elif keyterm.count("@") == 0:
-        ksearch.append("{0}@protonmail.com".format(keyterm))
-        ksearch.append("{0}@protonmail.ch".format(keyterm))
-        ksearch.append("{0}@pm.me".format(keyterm))
-    elif keyterm.count("@") == 2 and keyterm.startswith("@") is False:
-        uidlist = keyterm.split("@")
-        for uid in uidlist:
-            ksearch.append("{0}@protonmail.com".format(uid))
-            ksearch.append("{0}@protonmail.ch".format(uid))
-            ksearch.append("{0}@pm.me".format(uid))
-    elif keyterm.count("@") > 2:
-        uidlist = keyterm.split("@")
-        for uid in uidlist:
-            ksearch.append("{0}@protonmail.com".format(uid))
-            ksearch.append("{0}@protonmail.ch".format(uid))
-            ksearch.append("{0}@pm.me".format(uid))
-    else:
-        ksearch.append(keyterm)
-
-for k in ksearch:
-    print("Checking for key for: {0}".format(k))
-    try:
-        keys = server.search(k)
-        if isinstance(keys, list) is True:
-            for key in keys:
-                allkeys.append(key)
-                try:
-                    import_result = c.key_import(key.key_blob)
-                except Exception as e:
-                    import_result = c.key_import(key.key)
-        else:
-            paradox.append(keys)
-            import_result = None
-    except Exception as e:
-        import_result = None
-    results.append(import_result)
-
-for result in results:
-    if result is not None and hasattr(result, "considered") is False:
-        print("{0} for {1}".format(result.decode(), k))
-    elif result is not None and hasattr(result, "considered") is True:
-        num_keys = len(result.imports)
-        new_revs = result.new_revocations
-        new_sigs = result.new_signatures
-        new_subs = result.new_sub_keys
-        new_uids = result.new_user_ids
-        new_scrt = result.secret_imported
-        nochange = result.unchanged
-        print("""
-The total number of keys considered for import was:  {0}
-
-With UIDs wholely or partially matching the following string:
-
-        {1}
-
-   Number of keys revoked:  {2}
- Number of new signatures:  {3}
-    Number of new subkeys:  {4}
-   Number of new user IDs:  {5}
-Number of new secret keys:  {6}
- Number of unchanged keys:  {7}
-
-The key IDs for all considered keys were:
-""".format(num_keys, k, new_revs, new_sigs, new_subs, new_uids, new_scrt,
-           nochange))
-        for i in range(num_keys):
-            print(result.imports[i].fpr)
-        print("")
-    elif result is None:
-        pass
-#+END_SRC
-
-
-**** Import from ProtonMail via HKP for Python Example no. 2
-     :PROPERTIES:
-     :CUSTOM_ID: import-hkp4py-pm2
-     :END:
-
-Like its counterpart above, this script can also be found with the
-rest of the examples, by the name pmkey-import-hkp-alt.py.
-
-With this script a modicum of effort has been made to treat anything
-passed as a =homedir= which either does not exist or which is not a
-directory, as also being a pssible user ID to check for.  It's not
-guaranteed to pick up on all such cases, but it should cover most of
-them.
-
-#+BEGIN_SRC python -i
-import gpg
-import hkp4py
-import os.path
-import sys
-
-print("""
-This script searches the ProtonMail key server for the specified key and
-imports it.  Optionally enables specifying a different GnuPG home directory.
-
-Usage:  pmkey-import-hkp.py [homedir] [search string]
-   or:  pmkey-import-hkp.py [search string]
-""")
-
-c = gpg.Context(armor=True)
-server = hkp4py.KeyServer("hkps://api.protonmail.ch")
-keyterms = []
-ksearch = []
-allkeys = []
-results = []
-paradox = []
-homeless = None
-
-if len(sys.argv) > 3:
-    homedir = sys.argv[1]
-    keyterms = sys.argv[2:]
-elif len(sys.argv) == 3:
-    homedir = sys.argv[1]
-    keyterm = sys.argv[2]
-    keyterms.append(keyterm)
-elif len(sys.argv) == 2:
-    homedir = ""
-    keyterm = sys.argv[1]
-    keyterms.append(keyterm)
-else:
-    keyterm = input("Enter the key ID, UID or search string: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-    keyterms.append(keyterm)
-
-if len(homedir) == 0:
-    homedir = None
-    homeless = False
-
-if homedir is not None:
-    if homedir.startswith("~"):
-        if os.path.exists(os.path.expanduser(homedir)) is True:
-            if os.path.isdir(os.path.expanduser(homedir)) is True:
-                c.home_dir = os.path.realpath(os.path.expanduser(homedir))
-            else:
-                homeless = True
-        else:
-            homeless = True
-    elif os.path.exists(os.path.realpath(homedir)) is True:
-        if os.path.isdir(os.path.realpath(homedir)) is True:
-            c.home_dir = os.path.realpath(homedir)
-        else:
-            homeless = True
-    else:
-        homeless = True
-
-# First check to see if the homedir really is a homedir and if not, treat it as
-# a search string.
-if homeless is True:
-    keyterms.append(homedir)
-    c.home_dir = None
-else:
-    pass
-
-for keyterm in keyterms:
-    if keyterm.count("@") == 2 and keyterm.startswith("@") is True:
-        ksearch.append(keyterm[1:])
-        ksearch.append(keyterm[1:])
-        ksearch.append(keyterm[1:])
-    elif keyterm.count("@") == 1 and keyterm.startswith("@") is True:
-        ksearch.append("{0}@protonmail.com".format(keyterm[1:]))
-        ksearch.append("{0}@protonmail.ch".format(keyterm[1:]))
-        ksearch.append("{0}@pm.me".format(keyterm[1:]))
-    elif keyterm.count("@") == 0:
-        ksearch.append("{0}@protonmail.com".format(keyterm))
-        ksearch.append("{0}@protonmail.ch".format(keyterm))
-        ksearch.append("{0}@pm.me".format(keyterm))
-    elif keyterm.count("@") == 2 and keyterm.startswith("@") is False:
-        uidlist = keyterm.split("@")
-        for uid in uidlist:
-            ksearch.append("{0}@protonmail.com".format(uid))
-            ksearch.append("{0}@protonmail.ch".format(uid))
-            ksearch.append("{0}@pm.me".format(uid))
-    elif keyterm.count("@") > 2:
-        uidlist = keyterm.split("@")
-        for uid in uidlist:
-            ksearch.append("{0}@protonmail.com".format(uid))
-            ksearch.append("{0}@protonmail.ch".format(uid))
-            ksearch.append("{0}@pm.me".format(uid))
-    else:
-        ksearch.append(keyterm)
-
-for k in ksearch:
-    print("Checking for key for: {0}".format(k))
-    try:
-        keys = server.search(k)
-        if isinstance(keys, list) is True:
-            for key in keys:
-                allkeys.append(key)
-                try:
-                    import_result = c.key_import(key.key_blob)
-                except Exception as e:
-                    import_result = c.key_import(key.key)
-        else:
-            paradox.append(keys)
-            import_result = None
-    except Exception as e:
-        import_result = None
-    results.append(import_result)
-
-for result in results:
-    if result is not None and hasattr(result, "considered") is False:
-        print("{0} for {1}".format(result.decode(), k))
-    elif result is not None and hasattr(result, "considered") is True:
-        num_keys = len(result.imports)
-        new_revs = result.new_revocations
-        new_sigs = result.new_signatures
-        new_subs = result.new_sub_keys
-        new_uids = result.new_user_ids
-        new_scrt = result.secret_imported
-        nochange = result.unchanged
-        print("""
-The total number of keys considered for import was:  {0}
-
-With UIDs wholely or partially matching the following string:
-
-        {1}
-
-   Number of keys revoked:  {2}
- Number of new signatures:  {3}
-    Number of new subkeys:  {4}
-   Number of new user IDs:  {5}
-Number of new secret keys:  {6}
- Number of unchanged keys:  {7}
-
-The key IDs for all considered keys were:
-""".format(num_keys, k, new_revs, new_sigs, new_subs, new_uids, new_scrt,
-           nochange))
-        for i in range(num_keys):
-            print(result.imports[i].fpr)
-        print("")
-    elif result is None:
-        pass
-#+END_SRC
-
-
-** Exporting keys
-   :PROPERTIES:
-   :CUSTOM_ID: howto-export-key
-   :END:
-
-Exporting keys remains a reasonably simple task, but has been
-separated into three different functions for the OpenPGP cryptographic
-engine.  Two of those functions are for exporting public keys and the
-third is for exporting secret keys.
-
-
-*** Exporting public keys
-    :PROPERTIES:
-    :CUSTOM_ID: howto-export-public-key
-    :END:
-
-There are two methods of exporting public keys, both of which are very
-similar to the other.  The default method, =key_export()=, will export
-a public key or keys matching a specified pattern as normal.  The
-alternative, the =key_export_minimal()= method, will do the same thing
-except producing a minimised output with extra signatures and third
-party signatures or certifications removed.
-
-#+BEGIN_SRC python -i
-import gpg
-import os.path
-import sys
-
-print("""
-This script exports one or more public keys.
-""")
-
-c = gpg.Context(armor=True)
-
-if len(sys.argv) >= 4:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = sys.argv[3]
-elif len(sys.argv) == 3:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-elif len(sys.argv) == 2:
-    keyfile = sys.argv[1]
-    logrus = input("Enter the UID matching the key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-else:
-    keyfile = input("Enter the path and filename to save the secret key to: ")
-    logrus = input("Enter the UID matching the key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-
-if homedir.startswith("~"):
-    if os.path.exists(os.path.expanduser(homedir)) is True:
-        c.home_dir = os.path.expanduser(homedir)
-    else:
-        pass
-elif os.path.exists(homedir) is True:
-    c.home_dir = homedir
-else:
-    pass
-
-try:
-    result = c.key_export(pattern=logrus)
-except:
-    result = c.key_export(pattern=None)
-
-if result is not None:
-    with open(keyfile, "wb") as f:
-        f.write(result)
-else:
-    pass
-#+END_SRC
-
-It should be noted that the result will only return =None= when a
-search pattern has been entered, but has not matched any keys.  When
-the search pattern itself is set to =None= this triggers the exporting
-of the entire public keybox.
-
-#+BEGIN_SRC python -i
-import gpg
-import os
-import os.path
-import sys
-
-print("""
-This script exports one or more public keys in minimised form.
-""")
-
-def open_0o600(path, flags):
-    return os.open(path, flags, mode=0o600)
-
-c = gpg.Context(armor=True)
-
-if len(sys.argv) >= 4:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = sys.argv[3]
-elif len(sys.argv) == 3:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-elif len(sys.argv) == 2:
-    keyfile = sys.argv[1]
-    logrus = input("Enter the UID matching the key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-else:
-    keyfile = input("Enter the path and filename to save the secret key to: ")
-    logrus = input("Enter the UID matching the key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-
-if homedir.startswith("~"):
-    if os.path.exists(os.path.expanduser(homedir)) is True:
-        c.home_dir = os.path.expanduser(homedir)
-    else:
-        pass
-elif os.path.exists(homedir) is True:
-    c.home_dir = homedir
-else:
-    pass
-
-try:
-    result = c.key_export_minimal(pattern=logrus)
-except:
-    result = c.key_export_minimal(pattern=None)
-
-if result is not None:
-    with open(keyfile, "wb", opener=open_0o600) as f:
-        f.write(result)
-else:
-    pass
-#+END_SRC
-
-
-*** Exporting secret keys
-    :PROPERTIES:
-    :CUSTOM_ID: howto-export-secret-key
-    :END:
-
-Exporting secret keys is, functionally, very similar to exporting
-public keys; save for the invocation of =pinentry= via =gpg-agent= in
-order to securely enter the key's passphrase and authorise the export.
-
-The following example exports the secret key to a file which is then
-set with the same permissions as the output files created by the
-command line secret key export options.
-
-#+BEGIN_SRC python -i
-import gpg
-import os
-import os.path
-import sys
-
-print("""
-This script exports one or more secret keys.
-
-The gpg-agent and pinentry are invoked to authorise the export.
-""")
-
-def open_0o600(path, flags):
-    return os.open(path, flags, mode=0o600)
-
-c = gpg.Context(armor=True)
-
-if len(sys.argv) >= 4:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = sys.argv[3]
-elif len(sys.argv) == 3:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-elif len(sys.argv) == 2:
-    keyfile = sys.argv[1]
-    logrus = input("Enter the UID matching the secret key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-else:
-    keyfile = input("Enter the path and filename to save the secret key to: ")
-    logrus = input("Enter the UID matching the secret key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-
-if len(homedir) == 0:
-    homedir = None
-elif homedir.startswith("~"):
-    userdir = os.path.expanduser(homedir)
-    if os.path.exists(userdir) is True:
-        homedir = os.path.realpath(userdir)
-    else:
-        homedir = None
-else:
-    homedir = os.path.realpath(homedir)
-
-if os.path.exists(homedir) is False:
-    homedir = None
-else:
-    if os.path.isdir(homedir) is False:
-        homedir = None
-    else:
-        pass
-
-if homedir is not None:
-    c.home_dir = homedir
-else:
-    pass
-
-try:
-    result = c.key_export_secret(pattern=logrus)
-except:
-    result = c.key_export_secret(pattern=None)
-
-if result is not None:
-    with open(keyfile, "wb", opener=open_0o600)) as f:
-        f.write(result)
-else:
-    pass
-#+END_SRC
-
-Alternatively the approach of the following script can be used.  This
-longer example saves the exported secret key(s) in files in the GnuPG
-home directory, in addition to setting the file permissions as only
-readable and writable by the user.  It also exports the secret key(s)
-twice in order to output both GPG binary (=.gpg=) and ASCII armoured
-(=.asc=) files.
-
-#+BEGIN_SRC python -i
-import gpg
-import os
-import os.path
-import subprocess
-import sys
-
-print("""
-This script exports one or more secret keys as both ASCII armored and binary
-file formats, saved in files within the user's GPG home directory.
-
-The gpg-agent and pinentry are invoked to authorise the export.
-""")
-
-if sys.platform == "win32":
-    gpgconfcmd = "gpgconf.exe --list-dirs homedir"
-else:
-    gpgconfcmd = "gpgconf --list-dirs homedir"
-
-a = gpg.Context(armor=True)
-b = gpg.Context()
-c = gpg.Context()
-
-if len(sys.argv) >= 4:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = sys.argv[3]
-elif len(sys.argv) == 3:
-    keyfile = sys.argv[1]
-    logrus = sys.argv[2]
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-elif len(sys.argv) == 2:
-    keyfile = sys.argv[1]
-    logrus = input("Enter the UID matching the secret key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-else:
-    keyfile = input("Enter the filename to save the secret key to: ")
-    logrus = input("Enter the UID matching the secret key(s) to export: ")
-    homedir = input("Enter the GPG configuration directory path (optional): ")
-
-if len(homedir) == 0:
-    homedir = None
-elif homedir.startswith("~"):
-    userdir = os.path.expanduser(homedir)
-    if os.path.exists(userdir) is True:
-        homedir = os.path.realpath(userdir)
-    else:
-        homedir = None
-else:
-    homedir = os.path.realpath(homedir)
-
-if os.path.exists(homedir) is False:
-    homedir = None
-else:
-    if os.path.isdir(homedir) is False:
-        homedir = None
-    else:
-        pass
-
-if homedir is not None:
-    c.home_dir = homedir
-else:
-    pass
-
-if c.home_dir is not None:
-    if c.home_dir.endswith("/"):
-        gpgfile = "{0}{1}.gpg".format(c.home_dir, keyfile)
-        ascfile = "{0}{1}.asc".format(c.home_dir, keyfile)
-    else:
-        gpgfile = "{0}/{1}.gpg".format(c.home_dir, keyfile)
-        ascfile = "{0}/{1}.asc".format(c.home_dir, keyfile)
-else:
-    if os.path.exists(os.environ["GNUPGHOME"]) is True:
-        hd = os.environ["GNUPGHOME"]
-    else:
-        try:
-            hd = subprocess.getoutput(gpgconfcmd)
-        except:
-            process = subprocess.Popen(gpgconfcmd.split(),
-                                       stdout=subprocess.PIPE)
-            procom = process.communicate()
-            if sys.version_info[0] == 2:
-                hd = procom[0].strip()
-            else:
-                hd = procom[0].decode().strip()
-    gpgfile = "{0}/{1}.gpg".format(hd, keyfile)
-    ascfile = "{0}/{1}.asc".format(hd, keyfile)
-
-try:
-    a_result = a.key_export_secret(pattern=logrus)
-    b_result = b.key_export_secret(pattern=logrus)
-except:
-    a_result = a.key_export_secret(pattern=None)
-    b_result = b.key_export_secret(pattern=None)
-
-if a_result is not None:
-    with open(ascfile, "wb") as f:
-        f.write(a_result)
-    os.chmod(ascfile, 0o600)
-else:
-    pass
-
-if b_result is not None:
-    with open(gpgfile, "wb") as f:
-        f.write(b_result)
-    os.chmod(gpgfile, 0o600)
-else:
-    pass
-#+END_SRC
-
-
-*** Sending public keys to the SKS Keyservers
-    :PROPERTIES:
-    :CUSTOM_ID: howto-send-public-key
-    :END:
-
-As with the previous section on importing keys, the =hkp4py= module
-adds another option with exporting keys in order to send them to the
-public keyservers.
-
-The following example demonstrates how this may be done.
-
-#+BEGIN_SRC python -i
-import gpg
-import hkp4py
-import os.path
-import sys
-
-print("""
-This script sends one or more public keys to the SKS keyservers and is
-essentially a slight variation on the export-key.py script.
-""")
-
-c = gpg.Context(armor=True)
-server = hkp4py.KeyServer("hkps://hkps.pool.sks-keyservers.net")
-
-if len(sys.argv) > 2:
-    logrus = " ".join(sys.argv[1:])
-elif len(sys.argv) == 2:
-    logrus = sys.argv[1]
-else:
-    logrus = input("Enter the UID matching the key(s) to send: ")
-
-if len(logrus) > 0:
-    try:
-        export_result = c.key_export(pattern=logrus)
-    except Exception as e:
-        print(e)
-        export_result = None
-else:
-    export_result = c.key_export(pattern=None)
-
-if export_result is not None:
-    try:
-        try:
-            send_result = server.add(export_result)
-        except:
-            send_result = server.add(export_result.decode())
-        if send_result is not None:
-            print(send_result)
-        else:
-            pass
-    except Exception as e:
-        print(e)
-else:
-    pass
-#+END_SRC
-
-An expanded version of this script with additional functions for
-specifying an alternative homedir location is in the examples
-directory as =send-key-to-keyserver.py=.
-
-The =hkp4py= module appears to handle both string and byte literal text
-data equally well, but the GPGME bindings deal primarily with byte
-literal data only and so this script sends in that format first, then
-tries the string literal form.
-
-
-* Basic Functions
-  :PROPERTIES:
-  :CUSTOM_ID: howto-the-basics
-  :END:
-
-The most frequently called features of any cryptographic library will
-be the most fundamental tasks for encryption software.  In this
-section we will look at how to programmatically encrypt data, decrypt
-it, sign it and verify signatures.
-
-
-** Encryption
-   :PROPERTIES:
-   :CUSTOM_ID: howto-basic-encryption
-   :END:
-
-Encrypting is very straight forward.  In the first example below the
-message, =text=, is encrypted to a single recipient's key.  In the
-second example the message will be encrypted to multiple recipients.
-
-
-*** Encrypting to one key
-    :PROPERTIES:
-    :CUSTOM_ID: howto-basic-encryption-single
-    :END:
-
-Once the the Context is set the main issues with encrypting data is
-essentially reduced to key selection and the keyword arguments
-specified in the =gpg.Context().encrypt()= method.
-
-Those keyword arguments are: =recipients=, a list of keys encrypted to
-(covered in greater detail in the following section); =sign=, whether
-or not to sign the plaintext data, see subsequent sections on signing
-and verifying signatures below (defaults to =True=); =sink=, to write
-results or partial results to a secure sink instead of returning it
-(defaults to =None=); =passphrase=, only used when utilising symmetric
-encryption (defaults to =None=); =always_trust=, used to override the
-trust model settings for recipient keys (defaults to =False=);
-=add_encrypt_to=, utilises any preconfigured =encrypt-to= or
-=default-key= settings in the user's =gpg.conf= file (defaults to
-=False=); =prepare=, prepare for encryption (defaults to =False=);
-=expect_sign=, prepare for signing (defaults to =False=); =compress=,
-compresses the plaintext prior to encryption (defaults to =True=).
-
-#+BEGIN_SRC python -i
-import gpg
-
-a_key = "0x12345678DEADBEEF"
-text = b"""Some text to test with.
-
-Since the text in this case must be bytes, it is most likely that
-the input form will be a separate file which is opened with "rb"
-as this is the simplest method of obtaining the correct data format.
-"""
-
-c = gpg.Context(armor=True)
-rkey = list(c.keylist(pattern=a_key, secret=False))
-ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, sign=False)
-
-with open("secret_plans.txt.asc", "wb") as afile:
-    afile.write(ciphertext)
-#+END_SRC
-
-Though this is even more likely to be used like this; with the
-plaintext input read from a file, the recipient keys used for
-encryption regardless of key trust status and the encrypted output
-also encrypted to any preconfigured keys set in the =gpg.conf= file:
-
-#+BEGIN_SRC python -i
-import gpg
-
-a_key = "0x12345678DEADBEEF"
-
-with open("secret_plans.txt", "rb") as afile:
-    text = afile.read()
-
-c = gpg.Context(armor=True)
-rkey = list(c.keylist(pattern=a_key, secret=False))
-ciphertext, result, sign_result = c.encrypt(text, recipients=rkey, sign=True,
-                                            always_trust=True,
-                                            add_encrypt_to=True)
-
-with open("secret_plans.txt.asc", "wb") as afile:
-    afile.write(ciphertext)
-#+END_SRC
-
-If the =recipients= parameter is empty then the plaintext is encrypted
-symmetrically.  If no =passphrase= is supplied as a parameter or via a
-callback registered with the =Context()= then an out-of-band prompt
-for the passphrase via pinentry will be invoked.
-
-
-*** Encrypting to multiple keys
-    :PROPERTIES:
-    :CUSTOM_ID: howto-basic-encryption-multiple
-    :END:
-
-Encrypting to multiple keys essentially just expands upon the key
-selection process and the recipients from the previous examples.
-
-The following example encrypts a message (=text=) to everyone with an
-email address on the =gnupg.org= domain,[fn:4] but does /not/ encrypt
-to a default key or other key which is configured to normally encrypt
-to.
-
-#+BEGIN_SRC python -i
-import gpg
-
-text = b"""Oh look, another test message.
-
-The same rules apply as with the previous example and more likely
-than not, the message will actually be drawn from reading the
-contents of a file or, maybe, from entering data at an input()
-prompt.
-
-Since the text in this case must be bytes, it is most likely that
-the input form will be a separate file which is opened with "rb"
-as this is the simplest method of obtaining the correct data
-format.
-"""
-
-c = gpg.Context(armor=True)
-rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
-logrus = []
-
-for i in range(len(rpattern)):
-    if rpattern[i].can_encrypt == 1:
-        logrus.append(rpattern[i])
-
-ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
-                                            sign=False, always_trust=True)
-
-with open("secret_plans.txt.asc", "wb") as afile:
-    afile.write(ciphertext)
-#+END_SRC
-
-All it would take to change the above example to sign the message
-and also encrypt the message to any configured default keys would
-be to change the =c.encrypt= line to this:
-
-#+BEGIN_SRC python -i
-ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
-                                            always_trust=True,
-                                            add_encrypt_to=True)
-#+END_SRC
-
-The only keyword arguments requiring modification are those for which
-the default values are changing.  The default value of =sign= is
-=True=, the default of =always_trust= is =False=, the default of
-=add_encrypt_to= is =False=.
-
-If =always_trust= is not set to =True= and any of the recipient keys
-are not trusted (e.g. not signed or locally signed) then the
-encryption will raise an error.  It is possible to mitigate this
-somewhat with something more like this:
-
-#+BEGIN_SRC python -i
-import gpg
-
-with open("secret_plans.txt.asc", "rb") as afile:
-    text = afile.read()
-
-c = gpg.Context(armor=True)
-rpattern = list(c.keylist(pattern="@gnupg.org", secret=False))
-logrus = []
-
-for i in range(len(rpattern)):
-    if rpattern[i].can_encrypt == 1:
-        logrus.append(rpattern[i])
-
-    try:
-        ciphertext, result, sign_result = c.encrypt(text, recipients=logrus,
-                                                    add_encrypt_to=True)
-    except gpg.errors.InvalidRecipients as e:
-        for i in range(len(e.recipients)):
-            for n in range(len(logrus)):
-                if logrus[n].fpr == e.recipients[i].fpr:
-                    logrus.remove(logrus[n])
-                else:
-                    pass
-        try:
-            ciphertext, result, sign_result = c.encrypt(text,
-                                                        recipients=logrus,
-                                                        add_encrypt_to=True)
-            with open("secret_plans.txt.asc", "wb") as afile:
-                afile.write(ciphertext)
-        except:
-            pass
-#+END_SRC
-
-This will attempt to encrypt to all the keys searched for, then remove
-invalid recipients if it fails and try again.
-
-
-** Decryption
-   :PROPERTIES:
-   :CUSTOM_ID: howto-basic-decryption
-   :END:
-
-Decrypting something encrypted to a key in one's secret keyring is
-fairly straight forward.
-
-In this example code, however, preconfiguring either =gpg.Context()=
-or =gpg.core.Context()= as =c= is unnecessary because there is no need
-to modify the Context prior to conducting the decryption and since the
-Context is only used once, setting it to =c= simply adds lines for no
-gain.
-
-#+BEGIN_SRC python -i
-import gpg
-
-ciphertext = input("Enter path and filename of encrypted file: ")
-newfile = input("Enter path and filename of file to save decrypted data to: ")
-
-with open(ciphertext, "rb") as cfile:
-    try:
-        plaintext, result, verify_result = gpg.Context().decrypt(cfile)
-    except gpg.errors.GPGMEError as e:
-        plaintext = None
-        print(e)
-
-if plaintext is not None:
-    with open(newfile, "wb") as nfile:
-	    nfile.write(plaintext)
-    else:
-        pass
-#+END_SRC
-
-The data available in =plaintext= in this example is the decrypted
-content as a byte object, the recipient key IDs and algorithms in
-=result= and the results of verifying any signatures of the data in
-=verify_result=.
-
-If =gpg.Context().decrypt(cfile, verify=False)= is called instead,
-then =verify_result= will be returned as =None= and the rest remains
-as described here.
-
-
-** Signing text and files
-   :PROPERTIES:
-   :CUSTOM_ID: howto-basic-signing
-   :END:
-
-The following sections demonstrate how to specify keys to sign with.
-
-
-*** Signing key selection
-    :PROPERTIES:
-    :CUSTOM_ID: howto-basic-signing-signers
-    :END:
-
-By default GPGME and the Python bindings will use the default key
-configured for the user invoking the GPGME API.  If there is no
-default key specified and there is more than one secret key available
-it may be necessary to specify the key or keys with which to sign
-messages and files.
-
-#+BEGIN_SRC python -i
-import gpg
-
-logrus = input("Enter the email address or string to match signing keys to: ")
-hancock = gpg.Context().keylist(pattern=logrus, secret=True)
-sig_src = list(hancock)
-#+END_SRC
-
-The signing examples in the following sections include the explicitly
-designated =signers= parameter in two of the five examples; once where
-the resulting signature would be ASCII armoured and once where it
-would not be armoured.
-
-While it would be possible to enter a key ID or fingerprint here to
-match a specific key, it is not possible to enter two fingerprints and
-match two keys since the patten expects a string, bytes or None and
-not a list.  A string with two fingerprints won't match any single
-key.
-
-
-*** Normal or default signing messages or files
-    :PROPERTIES:
-    :CUSTOM_ID: howto-basic-signing-normal
-    :END:
-
-The normal or default signing process is essentially the same as is
-most often invoked when also encrypting a message or file.  So when
-the encryption component is not utilised, the result is to produce an
-encoded and signed output which may or may not be ASCII armoured and
-which may or may not also be compressed.
-
-By default compression will be used unless GnuPG detects that the
-plaintext is already compressed.  ASCII armouring will be determined
-according to the value of =gpg.Context().armor=.
-
-The compression algorithm is selected in much the same way as the
-symmetric encryption algorithm or the hash digest algorithm is when
-multiple keys are involved; from the preferences saved into the key
-itself or by comparison with the preferences with all other keys
-involved.
-
-#+BEGIN_SRC python -i
-import gpg
-
-text0 = """Declaration of ... something.
-
-"""
-text = text0.encode()
-
-c = gpg.Context(armor=True, signers=sig_src)
-signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.NORMAL)
-
-with open("/path/to/statement.txt.asc", "w") as afile:
-    afile.write(signed_data.decode())
-#+END_SRC
-
-Though everything in this example is accurate, it is more likely that
-reading the input data from another file and writing the result to a
-new file will be performed more like the way it is done in the next
-example.  Even if the output format is ASCII armoured.
-
-#+BEGIN_SRC python -i
-import gpg
-
-with open("/path/to/statement.txt", "rb") as tfile:
-    text = tfile.read()
-
-c = gpg.Context()
-signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.NORMAL)
-
-with open("/path/to/statement.txt.sig", "wb") as afile:
-    afile.write(signed_data)
-#+END_SRC
-
-
-*** Detached signing messages and files
-    :PROPERTIES:
-    :CUSTOM_ID: howto-basic-signing-detached
-    :END:
-
-Detached signatures will often be needed in programmatic uses of
-GPGME, either for signing files (e.g. tarballs of code releases) or as
-a component of message signing (e.g. PGP/MIME encoded email).
-
-#+BEGIN_SRC python -i
-import gpg
-
-text0 = """Declaration of ... something.
-
-"""
-text = text0.encode()
-
-c = gpg.Context(armor=True)
-signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.DETACH)
-
-with open("/path/to/statement.txt.asc", "w") as afile:
-    afile.write(signed_data.decode())
-#+END_SRC
-
-As with normal signatures, detached signatures are best handled as
-byte literals, even when the output is ASCII armoured.
-
-#+BEGIN_SRC python -i
-import gpg
-
-with open("/path/to/statement.txt", "rb") as tfile:
-    text = tfile.read()
-
-c = gpg.Context(signers=sig_src)
-signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.DETACH)
-
-with open("/path/to/statement.txt.sig", "wb") as afile:
-    afile.write(signed_data)
-#+END_SRC
-
-
-*** Clearsigning messages or text
-    :PROPERTIES:
-    :CUSTOM_ID: howto-basic-signing-clear
-    :END:
-
-Though PGP/in-line messages are no longer encouraged in favour of
-PGP/MIME, there is still sometimes value in utilising in-line
-signatures.  This is where clear-signed messages or text is of value.
-
-#+BEGIN_SRC python -i
-import gpg
-
-text0 = """Declaration of ... something.
-
-"""
-text = text0.encode()
-
-c = gpg.Context()
-signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.CLEAR)
-
-with open("/path/to/statement.txt.asc", "w") as afile:
-    afile.write(signed_data.decode())
-#+END_SRC
-
-In spite of the appearance of a clear-signed message, the data handled
-by GPGME in signing it must still be byte literals.
-
-#+BEGIN_SRC python -i
-import gpg
-
-with open("/path/to/statement.txt", "rb") as tfile:
-    text = tfile.read()
-
-c = gpg.Context()
-signed_data, result = c.sign(text, mode=gpg.constants.sig.mode.CLEAR)
-
-with open("/path/to/statement.txt.asc", "wb") as afile:
-    afile.write(signed_data)
-#+END_SRC
-
-
-** Signature verification
-   :PROPERTIES:
-   :CUSTOM_ID: howto-basic-verification
-   :END:
-
-Essentially there are two principal methods of verification of a
-signature.  The first of these is for use with the normal or default
-signing method and for clear-signed messages.  The second is for use
-with files and data with detached signatures.
-
-The following example is intended for use with the default signing
-method where the file was not ASCII armoured:
-
-#+BEGIN_SRC python -i
-import gpg
-import time
-
-filename = "statement.txt"
-gpg_file = "statement.txt.gpg"
-
-c = gpg.Context()
-
-try:
-    data, result = c.verify(open(gpg_file))
-    verified = True
-except gpg.errors.BadSignatures as e:
-    verified = False
-    print(e)
-
-if verified is True:
-    for i in range(len(result.signatures)):
-        sign = result.signatures[i]
-        print("""Good signature from:
-{0}
-with key {1}
-made at {2}
-""".format(c.get_key(sign.fpr).uids[0].uid, sign.fpr,
-           time.ctime(sign.timestamp)))
-else:
-    pass
-#+END_SRC
-
-Whereas this next example, which is almost identical would work with
-normal ASCII armoured files and with clear-signed files:
-
-#+BEGIN_SRC python -i
-import gpg
-import time
-
-filename = "statement.txt"
-asc_file = "statement.txt.asc"
-
-c = gpg.Context()
-
-try:
-    data, result = c.verify(open(asc_file))
-    verified = True
-except gpg.errors.BadSignatures as e:
-    verified = False
-    print(e)
-
-if verified is True:
-    for i in range(len(result.signatures)):
-        sign = result.signatures[i]
-        print("""Good signature from:
-{0}
-with key {1}
-made at {2}
-""".format(c.get_key(sign.fpr).uids[0].uid, sign.fpr,
-           time.ctime(sign.timestamp)))
-else:
-    pass
-#+END_SRC
-
-In both of the previous examples it is also possible to compare the
-original data that was signed against the signed data in =data= to see
-if it matches with something like this:
-
-#+BEGIN_SRC python -i
-with open(filename, "rb") as afile:
-    text = afile.read()
-
-if text == data:
-    print("Good signature.")
-else:
-    pass
-#+END_SRC
-
-The following two examples, however, deal with detached signatures.
-With his method of verification the data that was signed does not get
-returned since it is already being explicitly referenced in the first
-argument of =c.verify=.  So =data= is =None= and only the information
-in =result= is available.
-
-#+BEGIN_SRC python -i
-import gpg
-import time
-
-filename = "statement.txt"
-sig_file = "statement.txt.sig"
-
-c = gpg.Context()
-
-try:
-    data, result = c.verify(open(filename), open(sig_file))
-    verified = True
-except gpg.errors.BadSignatures as e:
-    verified = False
-    print(e)
-
-if verified is True:
-    for i in range(len(result.signatures)):
-        sign = result.signatures[i]
-        print("""Good signature from:
-{0}
-with key {1}
-made at {2}
-""".format(c.get_key(sign.fpr).uids[0].uid, sign.fpr,
-           time.ctime(sign.timestamp)))
-else:
-    pass
-#+END_SRC
-
-#+BEGIN_SRC python -i
-import gpg
-import time
-
-filename = "statement.txt"
-asc_file = "statement.txt.asc"
-
-c = gpg.Context()
-
-try:
-    data, result = c.verify(open(filename), open(asc_file))
-    verified = True
-except gpg.errors.BadSignatures as e:
-    verified = False
-    print(e)
-
-if verified is True:
-    for i in range(len(result.signatures)):
-        sign = result.signatures[i]
-        print("""Good signature from:
-{0}
-with key {1}
-made at {2}
-""".format(c.get_key(sign.fpr).uids[0].uid, sign.fpr,
-           time.ctime(sign.timestamp)))
-else:
-    pass
-#+END_SRC
-
-
-* Creating keys and subkeys
-  :PROPERTIES:
-  :CUSTOM_ID: key-generation
-  :END:
-
-The one thing, aside from GnuPG itself, that GPGME depends on, of
-course, is the keys themselves.  So it is necessary to be able to
-generate them and modify them by adding subkeys, revoking or disabling
-them, sometimes deleting them and doing the same for user IDs.
-
-In the following examples a key will be created for the world's
-greatest secret agent, Danger Mouse.  Since Danger Mouse is a secret
-agent he needs to be able to protect information to =SECRET= level
-clearance, so his keys will be 3072-bit keys.
-
-The pre-configured =gpg.conf= file which sets cipher, digest and other
-preferences contains the following configuration parameters:
-
-#+BEGIN_SRC conf
-  expert
-  allow-freeform-uid
-  allow-secret-key-import
-  trust-model tofu+pgp
-  tofu-default-policy unknown
-  enable-large-rsa
-  enable-dsa2
-  cert-digest-algo SHA512
-  default-preference-list TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1 ZLIB BZIP2 ZIP Uncompressed
-  personal-cipher-preferences TWOFISH CAMELLIA256 AES256 CAMELLIA192 AES192 CAMELLIA128 AES BLOWFISH IDEA CAST5 3DES
-  personal-digest-preferences SHA512 SHA384 SHA256 SHA224 RIPEMD160 SHA1
-  personal-compress-preferences ZLIB BZIP2 ZIP Uncompressed
-#+END_SRC
-
-
-** Primary key
-   :PROPERTIES:
-   :CUSTOM_ID: keygen-primary
-   :END:
-
-Generating a primary key uses the =create_key= method in a Context.
-It contains multiple arguments and keyword arguments, including:
-=userid=, =algorithm=, =expires_in=, =expires=, =sign=, =encrypt=,
-=certify=, =authenticate=, =passphrase= and =force=.  The defaults for
-all of those except =userid=, =algorithm=, =expires_in=, =expires= and
-=passphrase= is =False=.  The defaults for =algorithm= and
-=passphrase= is =None=.  The default for =expires_in= is =0=.  The
-default for =expires= is =True=.  There is no default for =userid=.
-
-If =passphrase= is left as =None= then the key will not be generated
-with a passphrase, if =passphrase= is set to a string then that will
-be the passphrase and if =passphrase= is set to =True= then gpg-agent
-will launch pinentry to prompt for a passphrase.  For the sake of
-convenience, these examples will keep =passphrase= set to =None=.
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-
-c.home_dir = "~/.gnupg-dm"
-userid = "Danger Mouse <[email protected]>"
-
-dmkey = c.create_key(userid, algorithm="rsa3072", expires_in=31536000,
-                     sign=True, certify=True)
-#+END_SRC
-
-One thing to note here is the use of setting the =c.home_dir=
-parameter.  This enables generating the key or keys in a different
-location.  In this case to keep the new key data created for this
-example in a separate location rather than adding it to existing and
-active key store data.  As with the default directory, =~/.gnupg=, any
-temporary or separate directory needs the permissions set to only
-permit access by the directory owner.  On posix systems this means
-setting the directory permissions to 700.
-
-The =temp-homedir-config.py= script in the HOWTO examples directory
-will create an alternative homedir with these configuration options
-already set and the correct directory and file permissions.
-
-The successful generation of the key can be confirmed via the returned
-=GenkeyResult= object, which includes the following data:
-
-#+BEGIN_SRC python -i
-print("""
- Fingerprint:  {0}
- Primary Key:  {1}
-  Public Key:  {2}
-  Secret Key:  {3}
- Sub Key:  {4}
-User IDs:  {5}
-""".format(dmkey.fpr, dmkey.primary, dmkey.pubkey, dmkey.seckey, dmkey.sub,
-           dmkey.uid))
-#+END_SRC
-
-Alternatively the information can be confirmed using the command line
-program:
-
-#+BEGIN_SRC shell
-  bash-4.4$ gpg --homedir ~/.gnupg-dm -K
-  ~/.gnupg-dm/pubring.kbx
-  ----------------------
-  sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
-	177B7C25DB99745EE2EE13ED026D2F19E99E63AA
-  uid           [ultimate] Danger Mouse <[email protected]>
-
-  bash-4.4$
-#+END_SRC
-
-As with generating keys manually, to preconfigure expanded preferences
-for the cipher, digest and compression algorithms, the =gpg.conf= file
-must contain those details in the home directory in which the new key
-is being generated.  I used a cut down version of my own =gpg.conf=
-file in order to be able to generate this:
-
-#+BEGIN_SRC shell
-  bash-4.4$ gpg --homedir ~/.gnupg-dm --edit-key 177B7C25DB99745EE2EE13ED026D2F19E99E63AA showpref quit
-  Secret key is available.
-
-  sec  rsa3072/026D2F19E99E63AA
-       created: 2018-03-15  expires: 2019-03-15  usage: SC
-       trust: ultimate      validity: ultimate
-  [ultimate] (1). Danger Mouse <[email protected]>
-
-  [ultimate] (1). Danger Mouse <[email protected]>
-       Cipher: TWOFISH, CAMELLIA256, AES256, CAMELLIA192, AES192, CAMELLIA128, AES, BLOWFISH, IDEA, CAST5, 3DES
-       Digest: SHA512, SHA384, SHA256, SHA224, RIPEMD160, SHA1
-       Compression: ZLIB, BZIP2, ZIP, Uncompressed
-       Features: MDC, Keyserver no-modify
-
-  bash-4.4$
-#+END_SRC
-
-
-** Subkeys
-   :PROPERTIES:
-   :CUSTOM_ID: keygen-subkeys
-   :END:
-
-Adding subkeys to a primary key is fairly similar to creating the
-primary key with the =create_subkey= method.  Most of the arguments
-are the same, but not quite all.  Instead of the =userid= argument
-there is now a =key= argument for selecting which primary key to add
-the subkey to.
-
-In the following example an encryption subkey will be added to the
-primary key.  Since Danger Mouse is a security conscious secret agent,
-this subkey will only be valid for about six months, half the length
-of the primary key.
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-c.home_dir = "~/.gnupg-dm"
-
-key = c.get_key(dmkey.fpr, secret=True)
-dmsub = c.create_subkey(key, algorithm="rsa3072", expires_in=15768000,
-                        encrypt=True)
-#+END_SRC
-
-As with the primary key, the results here can be checked with:
-
-#+BEGIN_SRC python -i
-print("""
- Fingerprint:  {0}
- Primary Key:  {1}
-  Public Key:  {2}
-  Secret Key:  {3}
- Sub Key:  {4}
-User IDs:  {5}
-""".format(dmsub.fpr, dmsub.primary, dmsub.pubkey, dmsub.seckey, dmsub.sub,
-           dmsub.uid))
-#+END_SRC
-
-As well as on the command line with:
-
-#+BEGIN_SRC shell
-  bash-4.4$ gpg --homedir ~/.gnupg-dm -K
-  ~/.gnupg-dm/pubring.kbx
-  ----------------------
-  sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
-	177B7C25DB99745EE2EE13ED026D2F19E99E63AA
-  uid           [ultimate] Danger Mouse <[email protected]>
-  ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
-
-  bash-4.4$
-#+END_SRC
-
-
-** User IDs
-   :PROPERTIES:
-   :CUSTOM_ID: keygen-uids
-   :END:
-
-
-*** Adding User IDs
-    :PROPERTIES:
-    :CUSTOM_ID: keygen-uids-add
-    :END:
-
-By comparison to creating primary keys and subkeys, adding a new user
-ID to an existing key is much simpler.  The method used to do this is
-=key_add_uid= and the only arguments it takes are for the =key= and
-the new =uid=.
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-c.home_dir = "~/.gnupg-dm"
-
-dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-key = c.get_key(dmfpr, secret=True)
-uid = "Danger Mouse <[email protected]>"
-
-c.key_add_uid(key, uid)
-#+END_SRC
-
-Unsurprisingly the result of this is:
-
-#+BEGIN_SRC shell
-  bash-4.4$ gpg --homedir ~/.gnupg-dm -K
-  ~/.gnupg-dm/pubring.kbx
-  ----------------------
-  sec   rsa3072 2018-03-15 [SC] [expires: 2019-03-15]
-	177B7C25DB99745EE2EE13ED026D2F19E99E63AA
-  uid           [ultimate] Danger Mouse <[email protected]>
-  uid           [ultimate] Danger Mouse <[email protected]>
-  ssb   rsa3072 2018-03-15 [E] [expires: 2018-09-13]
-
-  bash-4.4$
-#+END_SRC
-
-
-*** Revoking User IDs
-    :PROPERTIES:
-    :CUSTOM_ID: keygen-uids-revoke
-    :END:
-
-Revoking a user ID is a fairly similar process, except that it uses
-the =key_revoke_uid= method.
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-c.home_dir = "~/.gnupg-dm"
-
-dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-key = c.get_key(dmfpr, secret=True)
-uid = "Danger Mouse <[email protected]>"
-
-c.key_revoke_uid(key, uid)
-#+END_SRC
-
-
-** Key certification
-   :PROPERTIES:
-   :CUSTOM_ID: key-sign
-   :END:
-
-Since key certification is more frequently referred to as key signing,
-the method used to perform this function is =key_sign=.
-
-The =key_sign= method takes four arguments: =key=, =uids=,
-=expires_in= and =local=.  The default value of =uids= is =None= and
-which results in all user IDs being selected.  The default value of
-both =expires_in= and =local= is =False=; which results in the
-signature never expiring and being able to be exported.
-
-The =key= is the key being signed rather than the key doing the
-signing.  To change the key doing the signing refer to the signing key
-selection above for signing messages and files.
-
-If the =uids= value is not =None= then it must either be a string to
-match a single user ID or a list of strings to match multiple user
-IDs.  In this case the matching of those strings must be precise and
-it is case sensitive.
-
-To sign Danger Mouse's key for just the initial user ID with a
-signature which will last a little over a month, do this:
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-uid = "Danger Mouse <[email protected]>"
-
-dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-key = c.get_key(dmfpr, secret=True)
-c.key_sign(key, uids=uid, expires_in=2764800)
-#+END_SRC
-
-
-*** Verifying key certifications
-    :PROPERTIES:
-    :CUSTOM_ID: key-sign-verify
-    :END:
-
-#+BEGIN_SRC python -i
-import gpg
-import time
-
-c = gpg.Context()
-dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-keys = list(c.keylist(pattern=dmuid, mode=gpg.constants.keylist.mode.SIGS))
-key = keys[0]
-
-for user in key.uids:
-    for sig in user.signatures:
-        print("0x{0}".format(sig.keyid), "", time.ctime(sig.timestamp), "",
-              sig.uid)
-#+END_SRC
-
-Which for Danger Mouse displays the following:
-
-#+BEGIN_EXAMPLE
-  0x92E3F6115435C65A  Thu Mar 15 13:17:44 2018  Danger Mouse <[email protected]>
-  0x321E4E2373590E5D  Mon Nov 26 12:46:05 2018  Ben McGinnes <[email protected]>
-#+END_EXAMPLE
-
-The two key signatures listed are for the self-certification of Danger
-Mouse's key made when the key was created in March, 2018; and the
-second is a signature made by the author and set to expire at the end
-of the year.  Note that the second signature was made with the
-following code (including the preceding code to display the output of
-the certifications or key signatures):
-
-#+BEGIN_SRC python -i
-import gpg
-import math
-import pendulum
-import time
-
-hd = "/home/dm/.gnupg"
-c = gpg.Context()
-d = gpg.Context(home_dir=hd)
-dmfpr = "177B7C25DB99745EE2EE13ED026D2F19E99E63AA"
-dmuid = "Danger Mouse <[email protected]>"
-dkeys = list(c.keylist(pattern=dmuid))
-dmkey = dkeys[0]
-
-c.key_import(d.key_export(pattern=None))
-
-tp = pendulum.period(pendulum.now(tz="local"), pendulum.datetime(2019, 1, 1))
-ts = tp.total_seconds()
-total_secs = math.ceil(ts)
-c.key_sign(dmkey, uids=dmuid, expires_in=total_secs)
-
-d.key_import(c.key_export(pattern=dmuid))
-keys = list(c.keylist(pattern=dmuid, mode=gpg.constants.keylist.mode.SIGS))
-key = keys[0]
-
-for user in key.uids:
-    for sig in user.signatures:
-        print("0x{0}".format(sig.keyid), "", time.ctime(sig.timestamp), "",
-              sig.uid)
-#+END_SRC
-
-Note that this final code block includes the use of a module which is
-/not/ part of Python's standard library, the [[https://pendulum.eustace.io/][pendulum module]].  Unlike
-the standard datetime module, pendulum makes working with dates and
-times significantly easier in Python; just as the requests module
-makes working with HTTP and HTTPS easier than the builtin modules do.
-
-Though neither requests nor pendulum are required modules for using
-the GPGME Python bindings, they are both highly recommended more
-generally.
-
-
-* Advanced or Experimental Use Cases
-  :PROPERTIES:
-  :CUSTOM_ID: advanced-use
-  :END:
-
-
-** C plus Python plus SWIG plus Cython
-   :PROPERTIES:
-   :CUSTOM_ID: cython
-   :END:
-
-In spite of the apparent incongruence of using Python bindings to a C
-interface only to generate more C from the Python; it is in fact quite
-possible to use the GPGME bindings with [[http://docs.cython.org/en/latest/index.html][Cython]].  Though in many cases
-the benefits may not be obvious since the most computationally
-intensive work never leaves the level of the C code with which GPGME
-itself is interacting with.
-
-Nevertheless, there are some situations where the benefits are
-demonstrable.  One of the better and easier examples being the one of
-the early examples in this HOWTO, the [[#howto-keys-counting][key counting]] code.  Running that
-example as an executable Python script, =keycount.py= (available in
-the =examples/howto/= directory), will take a noticeable amount of time
-to run on most systems where the public keybox or keyring contains a
-few thousand public keys.
-
-Earlier in the evening, prior to starting this section, I ran that
-script on my laptop; as I tend to do periodically and timed it using
-=time= utility, with the following results:
-
-#+BEGIN_SRC shell
-  bash-4.4$ time keycount.py
-
-  Number of secret keys:  23
-  Number of public keys:  12112
-
-
-  real	11m52.945s
-  user	0m0.913s
-  sys	0m0.752s
-
-  bash-4.4$
-#+END_SRC
-
-Sometime after that I imported another key and followed it with a
-little test of Cython.  This test was kept fairly basic, essentially
-lifting the material from the [[http://docs.cython.org/en/latest/src/tutorial/cython_tutorial.html][Cython Basic Tutorial]] to demonstrate
-compiling Python code to C.  The first step was to take the example
-key counting code quoted previously, essentially from the importing of
-the =gpg= module to the end of the script:
-
-#+BEGIN_SRC python -i
-import gpg
-
-c = gpg.Context()
-seckeys = c.keylist(pattern=None, secret=True)
-pubkeys = c.keylist(pattern=None, secret=False)
-
-seclist = list(seckeys)
-secnum = len(seclist)
-
-publist = list(pubkeys)
-pubnum = len(publist)
-
-print("""
-    Number of secret keys:  {0}
-    Number of public keys:  {1}
-
-""".format(secnum, pubnum))
-#+END_SRC
-
-Save that into a file called =keycount.pyx= and then create a
-=setup.py= file which contains this:
-
-#+BEGIN_SRC python -i
-from setuptools import setup
-from Cython.Build import cythonize
-
-setup(
-    ext_modules = cythonize("keycount.pyx")
-)
-#+END_SRC
-
-Compile it:
-
-#+BEGIN_SRC shell
-  bash-4.4$ python setup.py build_ext --inplace
-  bash-4.4$
-#+END_SRC
-
-Then run it in a similar manner to =keycount.py=:
-
-#+BEGIN_SRC shell
-  bash-4.4$ time python3.7 -c "import keycount"
-
-  Number of secret keys:  23
-  Number of public keys:  12113
-
-
-  real	6m47.905s
-  user	0m0.785s
-  sys	0m0.331s
-
-  bash-4.4$
-#+END_SRC
-
-Cython turned =keycount.pyx= into an 81KB =keycount.o= file in the
-=build/= directory, a 24KB =keycount.cpython-37m-darwin.so= file to be
-imported into Python 3.7 and a 113KB =keycount.c= generated C source
-code file of nearly three thousand lines.  Quite a bit bigger than the
-314 bytes of the =keycount.pyx= file or the full 1,452 bytes of the
-full executable =keycount.py= example script.
-
-On the other hand it ran in nearly half the time; taking 6 minutes and
-47.905 seconds to run.  As opposed to the 11 minutes and 52.945 seconds
-which the CPython script alone took.
-
-The =keycount.pyx= and =setup.py= files used to generate this example
-have been added to the =examples/howto/advanced/cython/= directory
-The example versions include some additional options to annotate the
-existing code and to detect Cython's use.  The latter comes from the
-[[http://docs.cython.org/en/latest/src/tutorial/pure.html#magic-attributes-within-the-pxd][Magic Attributes]] section of the Cython documentation.
-
-
-* Miscellaneous extras and work-arounds
-  :PROPERTIES:
-  :CUSTOM_ID: cheats-and-hacks
-  :END:
-
-Most of the things in the following sections are here simply because
-there was no better place to put them, even though some are only
-peripherally related to the GPGME Python bindings.  Some are also
-workarounds for functions not integrated with GPGME as yet.  This is
-especially true of the first of these, dealing with [[#group-lines][group lines]].
-
-
-** Group lines
-   :PROPERTIES:
-   :CUSTOM_ID: group-lines
-   :END:
-
-There is not yet an easy way to access groups configured in the
-gpg.conf file from within GPGME.  As a consequence these central
-groupings of keys cannot be shared amongst multiple programs, such as
-MUAs readily.
-
-The following code, however, provides a work-around for obtaining this
-information in Python.
-
-#+BEGIN_SRC python -i
-import subprocess
-import sys
-
-if sys.platform == "win32":
-    gpgconfcmd = "gpgconf.exe --list-options gpg"
-else:
-    gpgconfcmd = "gpgconf --list-options gpg"
-
-process = subprocess.Popen(gpgconfcmd.split(), stdout=subprocess.PIPE)
-procom = process.communicate()
-
-if sys.version_info[0] == 2:
-    lines = procom[0].splitlines()
-else:
-    lines = procom[0].decode().splitlines()
-
-for line in lines:
-    if line.startswith("group") is True:
-        break
-
-groups = line.split(":")[-1].replace('"', '').split(',')
-
-group_lines = []
-group_lists = []
-
-for group in groups:
-    group_lines.append(group.split("="))
-    group_lists.append(group.split("="))
-
-for glist in group_lists:
-    glist[1] = glist[1].split()
-#+END_SRC
-
-The result of that code is that =group_lines= is a list of lists where
-=group_lines[i][0]= is the name of the group and =group_lines[i][1]=
-is the key IDs of the group as a string.
-
-The =group_lists= result is very similar in that it is a list of
-lists.  The first part, =group_lists[i][0]= matches
-=group_lines[i][0]= as the name of the group, but =group_lists[i][1]=
-is the key IDs of the group as a list.
-
-A demonstration of using the =groups.py= module is also available in
-the form of the executable =mutt-groups.py= script.  This second
-script reads all the group entries in a user's =gpg.conf= file and
-converts them into crypt-hooks suitable for use with the Mutt and
-Neomutt mail clients.
-
-
-** Keyserver access for Python
-   :PROPERTIES:
-   :CUSTOM_ID: hkp4py
-   :END:
-
-The [[https://github.com/Selfnet/hkp4py][hkp4py]] module by Marcel Fest was originally a port of the old
-[[https://github.com/dgladkov/python-hkp][python-hkp]] module from Python 2 to Python 3 and updated to use the
-[[http://docs.python-requests.org/en/latest/index.html][requests]] module instead.  It has since been modified to provide
-support for Python 2.7 as well and is available via PyPI.
-
-Since it rewrites the =hkp= protocol prefix as =http= and =hkps= as
-=https=, the module is able to be used even with servers which do not
-support the full scope of keyserver functions.[fn:5]  It also works quite
-readily when incorporated into a [[#cython][Cython]] generated and compiled version
-of any code.
-
-
-*** Key import format
-    :PROPERTIES:
-    :CUSTOM_ID: hkp4py-strings
-    :END:
-
-The hkp4py module returns key data via requests as string literals
-(=r.text=) instead of byte literals (=r.content=).  This means that
-the retrurned key data must be encoded to UTF-8 when importing that
-key material using a =gpg.Context().key_import()= method.
-
-For this reason an alternative method has been added to the =search=
-function of =hkp4py.KeyServer()= which returns the key in the correct
-format as expected by =key_import=.  When importing using this module,
-it is now possible to import with this:
-
-#+BEGIN_SRC python -i
-for key in keys:
-    if key.revoked is False:
-        gpg.Context().key_import(key.key_blob)
-    else:
-        pass
-#+END_SRC
-
-Without that recent addition it would have been necessary to encode
-the contents of each =hkp4py.KeyServer().search()[i].key= in
-=hkp4py.KeyServer().search()= before trying to import it.
-
-An example of this is included in the [[#howto-import-key][Importing Keys]] section of this
-HOWTO and the corresponding executable version of that example is
-available in the =lang/python/examples/howto= directory as normal; the
-executable version is the =import-keys-hkp.py= file.
-
-
-** GPGME version checking
-   :PROPERTIES:
-   :CUSTOM_ID: gpgme-version-check
-   :END:
-
-For various reasons it may be necessary to check which version of
-GPGME the bindings have been built against; including whether a
-minimum required version of GPGME is in use.
-
-For the most part the =gpg.version.versionstr= and
-=gpg.version.versionlist= methods have been quite sufficient.  The
-former returns the same string as =pkg-config gpgme --modversion=, while the
-latter returns the major, minor and patch values in a list.
-
-To check if the installed bindings have actually been built against
-the current installed libgpgme version, this check can be performed:
-
-#+BEGIN_SRC python -i
-import gpg
-import subprocess
-import sys
-
-gpgme_version_call = subprocess.Popen(["pkg-config", "gpgme", "--modversion"],
-                                      stdout=subprocess.PIPE,
-                                      stderr=subprocess.PIPE)
-gpgme_version_str = gpgme_version_call.communicate()
-
-if sys.version_info[0] == 2:
-    gpgme_version = gpgme_version_str[0].strip()
-elif sys.version_info[0] >= 3:
-    gpgme_version = gpgme_version_str[0].decode().strip()
-else:
-    gpgme_version = None
-
-if gpgme_version is not None:
-    if gpgme_version == gpg.version.versionstr:
-        print("The GPGME Python bindings match libgpgme.")
-    else:
-        print("The GPGME Python bindings do NOT match libgpgme.")
-else:
-    print("Upgrade Python and reinstall the GPGME Python bindings.")
-#+END_SRC
-
-For many developers, however, the preferred checking means checking
-for a minimum version or point release.  This is now readily available
-via the =gpg.version.versionintlist= method (added in version
-=1.12.1-beta79=).  It is also now possible to easily check whether the
-installed GPGME Python bindings were built from a development or beta
-branch of the GPGME source code.
-
-The following code demonstrates how both of those methods may be used:
-
-#+BEGIN_SRC python -i
-import gpg
-
-try:
-    if gpg.version.is_beta is True:
-        print("The installed GPGME Python bindings were built from beta code.")
-    else:
-        print("The installed GPGME Python bindings are a released version.")
-except Exception as e:
-    print(e)
-
-try:
-    if gpg.version.versionintlist[0] == 1:
-        if gpg.version.versionintlist[1] == 12:
-            if gpg.version.versionintlist[2] == 1:
-                print("This is the minimum version for using versionintlist.")
-            elif gpg.version.versionintlist[2] > 1:
-                print("The versionintlist method is available.")
-            else:
-                pass
-        elif gpg.version.versionintlist[1] > 12:
-            print("The versionintlist method is available.")
-        else:
-            pass
-    elif gpg.version.versionintlist[0] > 1:
-        print("The versionintlist method is available.")
-    else:
-        pass
-except Exception as e:
-    print(e)
-#+END_SRC
-
-The points where =pass= is used in the above example will most likely
-also produce an =Exception= error since those results should only
-occur in versions which do not have the =gpgme.version.is_beta= and
-=gpgme.version.versionintlist= methods available.
-
-
-* Copyright and Licensing
-  :PROPERTIES:
-  :CUSTOM_ID: copyright-and-license
-  :END:
-
-
-** Copyright
-   :PROPERTIES:
-   :CUSTOM_ID: copyright
-   :END:
-
-Copyright © The GnuPG Project, 2018.
-
-
-** Draft Editions of this HOWTO
-   :PROPERTIES:
-   :CUSTOM_ID: draft-editions
-   :END:
-
-Draft editions of this HOWTO may be periodically available directly
-from the author at any of the following URLs:
-
-- [[https://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 SSL)]]
-- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 no SSL)]]
-- [[https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (HTML multiple files, AWS S3 SSL)]]
-- [[http://files.au.adversary.org/crypto/gpgme-python-howto/index.html][GPGME Python Bindings HOWTO draft (HTML multiple files, AWS S3 no SSL)]]
-
-These draft versions have been generated from this document via GNU
-Emacs [[https://orgmode.org/][Org mode]] to =.texi= and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]] to HTML.  Though it is
-likely that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server
-with the generated output formats.  Occasionally I may include the Org
-mode generated XHTML versions:
-
-- [[https://files.au.adversary.org/crypto/gpgme-python-howto.xhtml][GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 SSL)]]
-- [[http://files.au.adversary.org/crypto/gpgme-python-howto.xhtml][GPGME Python Bindings HOWTO draft (HTML single file, AWS S3 no SSL)]]
-
-That XHTML version, however, is exported in a way which inherits a
-colour scheme from [[https://github.com/holomorph/emacs-zenburn][the author's Emacs theme]] (which is a higher contrast
-version of [[http://kippura.org/zenburnpage/][Zenburn]] ported by [[https://github.com/holomorph][Holomorph]]).  So it's fine for people who
-prefer dark themed web pages, but not so great for everyone else.
-
-The GNU Texinfo and reStructured Text versions ship with the software,
-while the GNU Emacs Info version is generated from the Texinfo
-version using GNU Texinfo or GNU Makeinfo.  The Texinfo format is
-generated from the original Org mode source file in Org mode itself
-either within GNU Emacs or via the command line by invoking Emacs in
-batch mode:
-
-#+BEGIN_SRC shell
-  emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill
-  emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill
-#+END_SRC
-
-The reStructuredText format is also generated from the Org mode source
-file, except it is generated using [[https://pandoc.org][Pandoc]] with either of the following
-commands (depending on the filename):
-
-#+BEGIN_SRC shell
-  pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
-  pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto
-#+END_SRC
-
-Note that the Org mode source files are identified as such via a mode
-line at the top of each file and have had their =.org= file extensions
-dropped in order to make scripted generation of output formats easier
-and not require renaming files post-conversion.
-
-Due to a bug in Org mode's texinfo conversion method, the recommended
-steps for generating the Texinfo files for all the files in the
-=lang/python/doc/src/= directory are as follows:
-
-#+BEGIN_SRC shell
-  for x in * ; do
-      emacs $x --batch -f org-texinfo-export-to-texinfo --kill
-      cat $x.texi | sed -e 's/@documentencoding UTF-8/@documentencoding utf-8/g' > ../texinfo/$x.texi
-      pandoc -f org -t rst+smart -o ../rst/$x.rst $x
-  done ;
-  rm -fv *.texi
-  cd ../texinfo
-  mkdir info
-  mkdir html
-  for x in *.texi ; do
-      makeinfo -v $x
-      makeinfo --html --no-split $x
-  done ;
-  mv *.info info/
-  mv *.html html/
-#+END_SRC
-
-This code snippet includes the generation of the reStructuredText
-files and would be expected to be run from the =doc/src/= directory
-containing the Org mode source files.  It also assumes that the
-commands are being run on POSIX compliant systems with basic tools
-like sed, the Bourne shell and GNU Emacs[fn:6] available.  The code
-snippet also includes the steps for generating the Emacs Info files
-and HTML files from the Texinfo files.  Using reStructuredText files
-with Sphinx is best left for the documentation of that project.
-
-In addition to these there is a significantly less frequently updated
-version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python/dita/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
-source files, which can be found in [[https://dev.gnupg.org/source/gpgme/browse/ben%252Fhowto-dita/][an alternative branch]] of the GPGME
-git repository.
-
-Various generated output formats may occasionally be found in
-subdirectories of the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python][gpgme-python]] directory.  In particular within
-the [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/dita][DITA]], [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/rst][reStructuredText]] and [[https://s3.amazonaws.com/files.au.adversary.org/crypto/gpgme-python/texinfo][Texinfo]] subdirectories.  The =rst=
-directory contains output files generated with Sphinx and may include a
-considerable number of its possible output formats, but there are no
-guarantees as to how recent these are or even if they are present.
-
-These draft editions are not official documents and the version of
-documentation in the master branch or which ships with released
-versions is the only official documentation.  Nevertheless, these
-draft editions may occasionally be of use by providing more accessible
-web versions which are updated between releases.  They are provided on
-the understanding that they may contain errors or may contain content
-subject to change prior to an official release.
-
-
-** License GPL compatible
-   :PROPERTIES:
-   :CUSTOM_ID: license
-   :END:
-
-This file is free software; as a special exception the author gives
-unlimited permission to copy and/or distribute it, with or without
-modifications, as long as this notice is preserved.
-
-This file is distributed in the hope that it will be useful, but
-WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
-implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
-PURPOSE.
-
-
-* Footnotes
-
-[fn:1] =short-history= and/or =short-history.html=.
-
-[fn:2] With no issues reported specific to Python 3.7, the release of
-Python 3.7.1 at around the same time as GPGME 1.12.0 and the testing
-with Python 3.7.1rc1, there is no reason to delay moving 3.7 ahead of
-3.6 now.  Production environments with more conservative requirements
-will always enforce their own policies anyway and installation to each
-supported minor release is quite possible too.
-
-[fn:3] Yes, even if you use virtualenv with everything you do in
-Python.  If you want to install this module as just your user account
-then you will need to manually configure, compile and install the
-/entire/ GnuPG stack as that user as well.  This includes libraries
-which are not often installed that way.  It can be done and there are
-circumstances under which it is worthwhile, but generally only on
-POSIX systems which utilise single user mode (some even require it).
-
-[fn:4] You probably don't really want to do this.  Searching the
-keyservers for "gnupg.org" produces over 400 results, the majority of
-which aren't actually at the gnupg.org domain, but just included a
-comment regarding the project in their key somewhere.
-
-[fn:5] Such as with ProtonMail servers.  This also means that
-restricted servers which only advertise either HTTP or HTTPS end
-points and not HKP or HKPS end points must still be identified as as
-HKP or HKPS within the Python Code.  The =hkp4py= module will rewrite
-these appropriately when the connection is made to the server.
-
-[fn:6] Okay, Emacs might not necessarily qualify as a basic tool, but
-it is common enough that having it installed on a system isn't too
-great an expectation, nor is it difficult to add to most POSIX
-systems, even if the users of those systems do not personally use it.