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.
This commit is contained in:
Ben McGinnes
parent
de6bb23279
commit
c87155e6eb
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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).
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
Loading…
Reference in New Issue
Block a user