docs: python bindings

* Tightened up the docs a little bit, updated the "what's new"
  section, dropped the "-draft" version in preparation for GPGME
  1.12.0's release.
* Exported another .texi version (and updated the draft copies to this
  commit (which ought to be 1.11.1-beta313).

Signed-off-by: Ben McGinnes <ben@adversary.org>

doc/gpgme-python-howto.texi

@@ -79,6 +79,7 @@ Known Issues
 * Multiple installations::
 * Won't Work With Windows::
 * CFFI is the Best™ and GPGME should use it instead of SWIG::
+* Virtualised Environments::
 
 Fundamentals
 
@@ -168,7 +169,7 @@ Copyright and Licensing
 @item Version:
 @tab 0.1.4
 @item GPGME Version:
-@tab 1.12.0-draft
+@tab 1.12.0
 @item Author:
 @tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org>
 @item Author GPG Key:
@@ -292,12 +293,20 @@ ProtonMail keyserver.
 @item
 Semi-formalised the location where @ref{Draft Editions of this HOWTO, , draft versions} of this HOWTO may
 periodically be accessible.  This is both for the reference of
-others and testing the publishing of the document itself.
+others and testing the publishing of the document itself.  Renamed
+the file at around the same time.
 @item
 Added a new section for @ref{Advanced or Experimental Use Cases, , advanced or experimental use}.
 @item
 Began the advanced use cases with @ref{C plus Python plus SWIG plus Cython, , a section} on using the module with
 @uref{http://cython.org/, Cython}.
+@item
+Added a number of new scripts to the @samp{example/howto/} directory;
+some of which may be in advance of their planned sections of the
+HOWTO (and some are just there because it seemed like a good idea at
+the time).
+@item
+Cleaned up a lot of things under the hood.
 @end itemize
 
 @node GPGME Concepts
@@ -487,6 +496,12 @@ quite high that at least the first one and maybe two of those will
 already be installed.
 @end enumerate
 
+Note that, as with Cython, some of the planned additions to the
+@ref{Advanced or Experimental Use Cases, , Advanced} section, 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.
+
 @node Installation
 @section Installation
 
@@ -533,6 +548,7 @@ they be encountered.
 * Multiple installations::
 * Won't Work With Windows::
 * CFFI is the Best™ and GPGME should use it instead of SWIG::
+* Virtualised Environments::
 @end menu
 
 @node Breaking Builds
@@ -727,6 +743,70 @@ 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.
 
+@node Virtualised Environments
+@subsection Virtualised Environments
+
+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 @samp{/usr/local} or
+@samp{/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 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
+@samp{sites.pth} file in the @samp{site-packages/} directory of a viertualenv
+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. @uref{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. @uref{https://www.virtualbox.org/, VirtualBox}), a
+hardware emulation layer (e.g. @uref{https://www.qemu.org/, QEMU}) or an application container
+(e.g. @uref{https://www.docker.com/why-docker, Docker}).
+
+Finally it should be noted that the limited tests conducted thus far
+have been using the @samp{virtualenv} command in a new directory to create
+the virtual python environment.  As opposed to the standard @samp{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 @samp{python3 -m virtualenv /path/to/install/virtual/thingy}
+instead.
+
 @node Fundamentals
 @chapter Fundamentals
 
@@ -875,6 +955,13 @@ print("""
 """.format(secnum, pubnum))
 @end example
 
+@strong{NOTE:} The @ref{C plus Python plus SWIG plus Cython, , Cython} introduction in the @ref{Advanced or Experimental Use Cases, , 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.
+
 @node Get key
 @section Get key
 
@@ -2826,6 +2913,12 @@ existing code and to detect Cython's use.  The latter comes from the
 @node Miscellaneous extras and work-arounds
 @chapter Miscellaneous extras and work-arounds
 
+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 @ref{Group lines, , group lines}.
+
 @menu
 * Group lines::
 * Keyserver access for Python::

lang/python/docs/gpgme-python-howto.org

@@ -16,7 +16,7 @@
   :END:
 
 | Version:        | 0.1.4                                    |
-| GPGME Version:  | 1.12.0-draft                             |
+| GPGME Version:  | 1.12.0                                   |
 | Author:         | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org>             |
 | Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
@@ -128,10 +128,16 @@ The bullet points of new additiions are:
   ProtonMail keyserver.
 - Semi-formalised the location where [[#draft-editions][draft versions]] of this HOWTO may
   periodically be accessible.  This is both for the reference of
-  others and testing the publishing of the document itself.
+  others and testing the publishing of the document itself.  Renamed
+  the file at around the same time.
 - Added a new section for [[#advanced-use][advanced or experimental use]].
 - Began the advanced use cases with [[#cython][a section]] on using the module with
   [[http://cython.org/][Cython]].
+- Added a number of new scripts to the =example/howto/= directory;
+  some of which may be in advance of their planned sections of the
+  HOWTO (and some are just there because it seemed like a good idea at
+  the time).
+- Cleaned up a lot of things under the hood.
 
 
 * GPGME Concepts
@@ -320,6 +326,12 @@ a significant advantage in some way.
    quite high that at least the first one and maybe two of those will
    already be installed.
 
+Note that, as with Cython, some of the planned additions to the
+[[#advanced-use][Advanced]] section, 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:
@@ -777,6 +789,13 @@ print("""
 """.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:
@@ -2770,6 +2789,12 @@ existing code and to detect Cython's use.  The latter comes from the
   :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: