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.

2 files changed, 93 insertions, 2 deletions

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