python: docs update

* Added documentation for the new methods added to gpgme.version.
* Removed the Flask based advanced use case from the what-is-new
  section as that type of code will not be added here.

6 files changed, 287 insertions, 24 deletions

diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst
index 4cbb929a..6a22ce2b 100644
--- a/lang/python/doc/rst/gpgme-python-howto.rst
+++ b/lang/python/doc/rst/gpgme-python-howto.rst
@@ -6,7 +6,7 @@ Introduction
 +-----------------------------------+-----------------------------------+
 | Version:                          | 0.1.4                             |
 +-----------------------------------+-----------------------------------+
-| GPGME Version:                    | 1.12.0                            |
+| GPGME Version:                    | 1.12.1                            |
 +-----------------------------------+-----------------------------------+
 | Author:                           | `Ben                              |
 |                                   | McGinnes <https://gnupg.org/peopl |
@@ -19,7 +19,7 @@ Introduction
 | Language:                         | Australian English, British       |
 |                                   | English                           |
 +-----------------------------------+-----------------------------------+
-| xml:lang:                         | en-AU, en-GB, en                  |
+| Language codes:                   | en-AU, en-GB, en                  |
 +-----------------------------------+-----------------------------------+
 
 This document provides basic instruction in how to use the GPGME Python
@@ -2823,6 +2823,95 @@ 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-check:
+
+GPGME version checking
+----------------------
+
+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 ``gpgme-config --version``, 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:
+
+.. code:: python
+
+   import gpg
+   import subprocess
+   import sys
+
+   gpgme_version_call = subprocess.Popen(["gpgme-config", "--version"],
+                                         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.")
+
+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:
+
+.. code:: python
+
+   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)
+
+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-license:
 
 Copyright and Licensing
@@ -2859,10 +2948,6 @@ the author at any of the following URLs:
    SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.rst>`__
 -  `GPGME Python Bindings HOWTO draft (reST file AWS S3 no
    SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.rst>`__
--  `GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3
-   SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.xml>`__
--  `GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 no
-   SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.xml>`__
 
 All of these draft versions except for one have been generated from this
 document via Emacs `Org mode <https://orgmode.org/>`__ and `GNU
@@ -2878,8 +2963,8 @@ either of the following two commands:
 
 .. code:: shell
 
-   pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto.org
-   pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto
+   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
 
 In addition to these there is a significantly less frequently updated
 version as a HTML `WebHelp
diff --git a/lang/python/doc/rst/what-is-new.rst b/lang/python/doc/rst/what-is-new.rst
index 9332fb67..0fca98f2 100644
--- a/lang/python/doc/rst/what-is-new.rst
+++ b/lang/python/doc/rst/what-is-new.rst
@@ -33,10 +33,11 @@ New in GPGME 1·13·0
 
 Additions since GPGME 1.12.0 include:
 
--  An advanced HOWTO on using the bindings with web interfaces,
-   specifically Flask.
 -  Moving the *What\'s New* section out of the basic
    `HOWTO <gpgme-python-howto.org>`__ document and into its own file so
    as to more readily include other documents beyond that HOWTO.
 -  Moving the preceding, archival, segments into `another
    file <what-was-new.org>`__.
+-  Added ``gpg.version.versionintlist`` to make it easier for Python
+   developers to check for a specific version number, even with beta
+   versions (it will drop the \"-betaN\" part).
diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto
index 7cc9770c..11fb1e25 100644
--- a/lang/python/doc/src/gpgme-python-howto
+++ b/lang/python/doc/src/gpgme-python-howto
@@ -2893,6 +2893,96 @@ 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 =gpgme-config --version=, 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(["gpgme-config", "--version"],
+                                      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
diff --git a/lang/python/doc/src/what-is-new b/lang/python/doc/src/what-is-new
index 4ca8ea89..5bcb5aeb 100644
--- a/lang/python/doc/src/what-is-new
+++ b/lang/python/doc/src/what-is-new
@@ -35,9 +35,10 @@ considerably.
 
 Additions since GPGME 1.12.0 include:
 
-- An advanced HOWTO on using the bindings with web interfaces,
-  specifically Flask.
 - Moving the /What's New/ section out of the basic [[file:gpgme-python-howto.org][HOWTO]] document and
   into its own file so as to more readily include other documents
   beyond that HOWTO.
 - Moving the preceding, archival, segments into [[file:what-was-new.org][another file]].
+- Added =gpg.version.versionintlist= to make it easier for Python
+  developers to check for a specific version number, even with beta
+  versions (it will drop the "-betaN" part).
diff --git a/lang/python/doc/texinfo/gpgme-python-howto.texi b/lang/python/doc/texinfo/gpgme-python-howto.texi
index 4f10bc5b..3ac26d69 100644
--- a/lang/python/doc/texinfo/gpgme-python-howto.texi
+++ b/lang/python/doc/texinfo/gpgme-python-howto.texi
@@ -149,6 +149,7 @@ Miscellaneous extras and work-arounds
 
 * Group lines::
 * Keyserver access for Python::
+* GPGME version checking::
 
 Keyserver access for Python
 
@@ -170,14 +171,14 @@ Copyright and Licensing
 @item Version:
 @tab 0.1.4
 @item GPGME Version:
-@tab 1.12.0
+@tab 1.12.1
 @item Author:
 @tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org>
 @item Author GPG Key:
 @tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
 @item Language:
 @tab Australian English, British English
-@item xml:lang:
+@item Language codes:
 @tab en-AU, en-GB, en
 @end multitable
 
@@ -2887,6 +2888,7 @@ especially true of the first of these, dealing with @ref{Group lines, , group li
 @menu
 * Group lines::
 * Keyserver access for Python::
+* GPGME version checking::
 @end menu
 
 @node Group lines
@@ -3005,6 +3007,93 @@ HOWTO and the corresponding executable version of that example is
 available in the @samp{lang/python/examples/howto} directory as normal; the
 executable version is the @samp{import-keys-hkp.py} file.
 
+@node GPGME version checking
+@section GPGME version checking
+
+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 @samp{gpg.version.versionstr} and
+@samp{gpg.version.versionlist} methods have been quite sufficient.  The
+former returns the same string as @samp{gpgme-config --version}, 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:
+
+@example
+import gpg
+import subprocess
+import sys
+
+gpgme_version_call = subprocess.Popen(["gpgme-config", "--version"],
+                                      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 example
+
+For many developers, however, the preferred checking means checking
+for a minimum version or point release.  This is now readily available
+via the @samp{gpg.version.versionintlist} method (added in version
+@samp{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:
+
+@example
+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 example
+
+The points where @samp{pass} is used in the above example will most likely
+also produce an @samp{Exception} error since those results should only
+occur in versions which do not have the @samp{gpgme.version.is_beta} and
+@samp{gpgme.version.versionintlist} methods available.
+
 @node Copyright and Licensing
 @chapter Copyright and Licensing
 
@@ -3044,10 +3133,6 @@ from the author at any of the following URLs:
 @uref{https://files.au.adversary.org/crypto/gpgme-python-howto.rst, GPGME Python Bindings HOWTO draft (reST file AWS S3 SSL)}
 @item
 @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.rst, GPGME Python Bindings HOWTO draft (reST file AWS S3 no SSL)}
-@item
-@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.xml, GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 SSL)}
-@item
-@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.xml, GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 no SSL)}
 @end itemize
 
 All of these draft versions except for one have been generated from
@@ -3060,8 +3145,8 @@ using the latest version of Pandoc from the Org mode source file using
 either of the following two commands:
 
 @example
-pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto.org
-pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto
+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 example
 
 In addition to these there is a significantly less frequently updated
@@ -3089,4 +3174,4 @@ WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
 implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 PURPOSE.
 
-@bye
+@bye
\ No newline at end of file
diff --git a/lang/python/doc/texinfo/what-is-new.texi b/lang/python/doc/texinfo/what-is-new.texi
index 6233cac8..0b70d215 100644
--- a/lang/python/doc/texinfo/what-is-new.texi
+++ b/lang/python/doc/texinfo/what-is-new.texi
@@ -66,14 +66,15 @@ Additions since GPGME 1.12.0 include:
 
 @itemize
 @item
-An advanced HOWTO on using the bindings with web interfaces,
-specifically Flask.
-@item
 Moving the @emph{What's New} section out of the basic @uref{gpgme-python-howto.org, HOWTO} document and
 into its own file so as to more readily include other documents
 beyond that HOWTO.
 @item
 Moving the preceding, archival, segments into @uref{what-was-new.org, another file}.
+@item
+Added @samp{gpg.version.versionintlist} to make it easier for Python
+developers to check for a specific version number, even with beta
+versions (it will drop the "-betaN" part).
 @end itemize
 
 @bye
\ No newline at end of file