dpcs: python howto
* More updates to the docs themselves and the versions to be available with the next release. * .texi and .rst copies of the HOWTO and the short history of (this part) of the project.
This commit is contained in:
Ben McGinnes
parent
2151b9828a
commit
962dfca9b8
3001
lang/python/docs/rst/gpgme-python-howto.rst
Normal file
3001
lang/python/docs/rst/gpgme-python-howto.rst
Normal file
File diff suppressed because it is too large
Load Diff
152
lang/python/docs/rst/short-history.rst
Normal file
152
lang/python/docs/rst/short-history.rst
Normal file
@ -0,0 +1,152 @@
|
||||
Overview
|
||||
========
|
||||
|
||||
The GPGME Python bindings passed through many hands and numerous phases
|
||||
before, after a fifteen year journey, coming full circle to return to
|
||||
the source. This is a short explanation of that journey.
|
||||
|
||||
.. _in-the-begining:
|
||||
|
||||
In the beginning
|
||||
----------------
|
||||
|
||||
In 2002 John Goerzen released PyME; Python bindings for the GPGME module
|
||||
which utilised the current release of Python of the time and SWIG. [1]_
|
||||
Shortly after creating it and ensuring it worked he stopped supporting
|
||||
it, though he left his work available on his Gopher site.
|
||||
|
||||
Keeping the flame alive
|
||||
-----------------------
|
||||
|
||||
A couple of years later the project was picked up by Igor Belyi and
|
||||
actively developed and maintained by him from 2004 to 2008. Igor\'s
|
||||
whereabouts at the time of this document\'s creation are unknown, but
|
||||
the current authors do hope he is well. We\'re assuming (or hoping) that
|
||||
life did what life does and made continuing untenable.
|
||||
|
||||
Passing the torch
|
||||
-----------------
|
||||
|
||||
In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
|
||||
discovered the absence of Igor. Following a discussion on the PyME
|
||||
mailing list he became the new maintainer for PyME, releasing version
|
||||
0.9.0 in May of that year. He remains the maintainer of the original
|
||||
PyME release in Python 2.6 and 2.7 (available via PyPI).
|
||||
|
||||
.. _ouroboros:
|
||||
|
||||
Coming full circle
|
||||
------------------
|
||||
|
||||
In 2015 Ben McGinnes approached Martin about a Python 3 version, while
|
||||
investigating how complex a task this would be the task ended up being
|
||||
completed. A subsequent discussion with Werner Koch led to the decision
|
||||
to fold the Python 3 port back into the original GPGME release in the
|
||||
languages subdirectory for non-C bindings under the module name of
|
||||
``pyme3``.
|
||||
|
||||
In 2016 this PyME module was integrated back into the GPGME project by
|
||||
Justus Winter. During the course of this work Justus adjusted the port
|
||||
to restore limited support for Python 2, but not as many minor point
|
||||
releases as the original PyME package supports. During the course of
|
||||
this integration the package was renamed to more accurately reflect its
|
||||
status as a component of GPGME. The ``pyme3`` module was renamed to
|
||||
``gpg`` and adopted by the upstream GnuPG team.
|
||||
|
||||
In 2017 Justus departed G10code and the GnuPG team. Following this Ben
|
||||
returned to maintain of gpgme Python bindings and continue building them
|
||||
from that point.
|
||||
|
||||
.. _relics-past:
|
||||
|
||||
Relics of the past
|
||||
==================
|
||||
|
||||
There are a few things, in addition to code specific factors, such as
|
||||
SWIG itself, which are worth noting here.
|
||||
|
||||
The Annoyances of Git
|
||||
---------------------
|
||||
|
||||
As anyone who has ever worked with git knows, submodules are horrible
|
||||
way to deal with pretty much anything. In the interests of avoiding
|
||||
migraines, that was skipped with addition of the PyME code to GPGME.
|
||||
|
||||
Instead the files were added to a subdirectory of the ``lang/``
|
||||
directory, along with a copy of the entire git log up to that point as a
|
||||
separate file within the ``lang/python/docs/`` directory. [2]_ As the
|
||||
log for PyME is nearly 100KB and the log for GPGME is approximately 1MB,
|
||||
this would cause considerable bloat, as well as some confusion, should
|
||||
the two be merged.
|
||||
|
||||
Hence the unfortunate, but necessary, step to simply move the files. A
|
||||
regular repository version has been maintained should it be possible to
|
||||
implement this better in the future.
|
||||
|
||||
The Perils of PyPI
|
||||
------------------
|
||||
|
||||
The early port of the Python 2 ``pyme`` module as ``pyme3`` was never
|
||||
added to PyPI while the focus remained on development and testing during
|
||||
2015 and early 2016. Later in 2016, however, when Justus completed his
|
||||
major integration work and subsequently renamed the module from
|
||||
``pyme3`` to ``gpg``, some prior releases were also provided through
|
||||
PyPI.
|
||||
|
||||
Since these bindings require a matching release of the GPGME libraries
|
||||
in order to function, it was determined that there was little benefit in
|
||||
also providing a copy through PyPI since anyone obtaining the GPGME
|
||||
source code would obtain the Python bindings source code at the same
|
||||
time. Whereas there was the potential to sew confusion amongst Python
|
||||
users installing the module from PyPI, only to discover that without the
|
||||
relevant C files, header files or SWIG compiled binaries, the Python
|
||||
module did them little good.
|
||||
|
||||
There are only two files on PyPI which might turn up in a search for
|
||||
this module or a sample of its content:
|
||||
|
||||
#. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
|
||||
#. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
|
||||
|
||||
.. _pypi-gpgme-180:
|
||||
|
||||
GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is the most recent version to reach PyPI and is the version of the
|
||||
official Pyhon bindings which shipped with GPGME 1.8.0. If you have
|
||||
GPGME 1.8.0 installed and *only* 1.8.0 installed, then it is probably
|
||||
safe to use this copy from PyPI.
|
||||
|
||||
As there have been a lot of changes since the release of GPGME 1.8.0,
|
||||
the GnuPG Project recommends not using this version of the module and
|
||||
instead installing the current version of GPGME along with the Python
|
||||
bindings included with that package.
|
||||
|
||||
.. _pypi-gpgme-90:
|
||||
|
||||
PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This is the last release of the PyME bindings maintained by Martin
|
||||
Albrecht and is only compatible with Python 2, it will not work with
|
||||
Python 3. This is the version of the software from which the port from
|
||||
Python 2 to Python 3 code was made in 2015.
|
||||
|
||||
Users of the more recent Python bindings will recognise numerous points
|
||||
of similarity, but also significant differences. It is likely that the
|
||||
more recent official bindings will feel \"more pythonic.\"
|
||||
|
||||
For those using Python 2, there is essentially no harm in using this
|
||||
module, but it may lack a number of more recent features added to GPGME.
|
||||
|
||||
Footnotes
|
||||
=========
|
||||
|
||||
.. [1]
|
||||
In all likelihood thos would have been Python 2.2 or possibly Python
|
||||
2.3.
|
||||
|
||||
.. [2]
|
||||
The entire PyME git log and other preceding VCS logs are located in
|
||||
the ``gpgme/lang/python/docs/old-commits.log`` file.
|
||||
@ -131,7 +131,16 @@ The bullet points of new additiions are:
|
||||
- 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. Renamed
|
||||
the file at around the same time.
|
||||
this file at around the same time.
|
||||
- The Texinfo documentation build configuration has been replicated
|
||||
from the parent project in order to make to maintain consistency
|
||||
with that project (and actually ship with each release).
|
||||
- a reStructuredText (=.rst=) version is also generated for Python
|
||||
developers more used to and comfortable with that format as it is
|
||||
the standard Python documentation format and Python developers may
|
||||
wish to use it with Sphinx. Please note that there has been no
|
||||
testing of the reStructuredText version with Sphinx at all. The
|
||||
reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]].
|
||||
- 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]].
|
||||
@ -804,7 +813,7 @@ print("""
|
||||
""".format(secnum, pubnum))
|
||||
#+END_SRC
|
||||
|
||||
*NOTE:* The [[#cython][Cython]] introduction in the [[#advanced-use][Advanced and Experimental]]
|
||||
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,
|
||||
@ -911,7 +920,7 @@ else:
|
||||
pass
|
||||
#+END_SRC
|
||||
|
||||
*NOTE:* When searching for a key ID of any length or a fingerprint
|
||||
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
|
||||
@ -2958,13 +2967,23 @@ from the author at any of the following URLs:
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no SSL)]]
|
||||
- [[https://files.au.adversary.org/crypto/gpgme-python-howto.info][GPGME Python Bindings HOWTO draft (Info file AWS S3 SSL)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto.info][GPGME Python Bindings HOWTO draft (Info file AWS S3 no SSL)]]
|
||||
- [[https://files.au.adversary.org/crypto/gpgme-python-howto.rst][GPGME Python Bindings HOWTO draft (reST file AWS S3 SSL)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto.rst][GPGME Python Bindings HOWTO draft (reST file AWS S3 no SSL)]]
|
||||
- [[https://files.au.adversary.org/crypto/gpgme-python-howto.xml][GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 SSL)]]
|
||||
- [[http://files.au.adversary.org/crypto/gpgme-python-howto.xml][GPGME Python Bindings HOWTO draft (Docbook 4.2 AWS S3 no SSL)]]
|
||||
|
||||
All of these draft versions are generated from this document via Emacs
|
||||
[[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is likely that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto.org][file]]
|
||||
[[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with the generated output
|
||||
formats.
|
||||
All of these draft versions except for one have been generated from
|
||||
this document via Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is likely
|
||||
that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto.org][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with
|
||||
the generated output formats.
|
||||
|
||||
The one exception is the reStructuredText version, which was converted
|
||||
using the latest version of Pandoc from the Org mode source file using
|
||||
the following command:
|
||||
|
||||
#+BEGIN_SRC shell
|
||||
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
|
||||
#+END_SRC
|
||||
|
||||
In addition to these there is a significantly less frequently updated
|
||||
version as a HTML [[https://files.au.adversary.org/crypto/gpgme-python-howto/webhelp/index.html][WebHelp site]] (AWS S3 SSL); generated from DITA XML
|
||||
@ -2997,7 +3016,7 @@ PURPOSE.
|
||||
|
||||
* Footnotes
|
||||
|
||||
[fn:1] =Short_History.org= and/or =Short_History.html=.
|
||||
[fn:1] =short-history.org= and/or =short-history.html=.
|
||||
|
||||
[fn:2] The =lang/python/docs/= directory in the GPGME source.
|
||||
|
||||
|
||||
3156
lang/python/docs/texinfo/gpgme-python-howto.texi
Normal file
3156
lang/python/docs/texinfo/gpgme-python-howto.texi
Normal file
File diff suppressed because it is too large
Load Diff
209
lang/python/docs/texinfo/short-history.texi
Normal file
209
lang/python/docs/texinfo/short-history.texi
Normal file
@ -0,0 +1,209 @@
|
||||
\input texinfo @c -*- texinfo -*-
|
||||
@c %**start of header
|
||||
@setfilename short-history.info
|
||||
@settitle A Short History of the GPGME bindings for Python
|
||||
@documentencoding UTF-8
|
||||
@documentlanguage en
|
||||
@c %**end of header
|
||||
|
||||
@finalout
|
||||
@titlepage
|
||||
@title A Short History of the GPGME bindings for Python
|
||||
@author Ben McGinnes
|
||||
@end titlepage
|
||||
|
||||
@contents
|
||||
|
||||
@ifnottex
|
||||
@node Top
|
||||
@top A Short History of the GPGME bindings for Python
|
||||
@end ifnottex
|
||||
|
||||
@menu
|
||||
* Overview::
|
||||
* Relics of the past::
|
||||
|
||||
@detailmenu
|
||||
--- The Detailed Node Listing ---
|
||||
|
||||
Overview
|
||||
|
||||
* In the beginning::
|
||||
* Keeping the flame alive::
|
||||
* Passing the torch::
|
||||
* Coming full circle::
|
||||
|
||||
Relics of the past
|
||||
|
||||
* The Annoyances of Git::
|
||||
* The Perils of PyPI::
|
||||
|
||||
The Perils of PyPI
|
||||
|
||||
* GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library: GPG 180 - Python bindings for GPGME GnuPG cryptography library.
|
||||
* PyME 0.9.0 - Python support for GPGME GnuPG cryptography library: PyME 090 - Python support for GPGME GnuPG cryptography library.
|
||||
|
||||
@end detailmenu
|
||||
@end menu
|
||||
|
||||
@node Overview
|
||||
@chapter Overview
|
||||
|
||||
The GPGME Python bindings passed through many hands and numerous
|
||||
phases before, after a fifteen year journey, coming full circle to
|
||||
return to the source. This is a short explanation of that journey.
|
||||
|
||||
@menu
|
||||
* In the beginning::
|
||||
* Keeping the flame alive::
|
||||
* Passing the torch::
|
||||
* Coming full circle::
|
||||
@end menu
|
||||
|
||||
@node In the beginning
|
||||
@section In the beginning
|
||||
|
||||
In 2002 John Goerzen released PyME; Python bindings for the GPGME
|
||||
module which utilised the current release of Python of the time and
|
||||
SWIG.@footnote{In all likelihood thos would have been Python 2.2 or possibly
|
||||
Python 2.3.} Shortly after creating it and ensuring it worked he stopped
|
||||
supporting it, though he left his work available on his Gopher
|
||||
site.
|
||||
|
||||
@node Keeping the flame alive
|
||||
@section Keeping the flame alive
|
||||
|
||||
A couple of years later the project was picked up by Igor Belyi and
|
||||
actively developed and maintained by him from 2004 to 2008. Igor's
|
||||
whereabouts at the time of this document's creation are unknown,
|
||||
but the current authors do hope he is well. We're assuming (or
|
||||
hoping) that life did what life does and made continuing untenable.
|
||||
|
||||
@node Passing the torch
|
||||
@section Passing the torch
|
||||
|
||||
In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
|
||||
discovered the absence of Igor. Following a discussion on the PyME
|
||||
mailing list he became the new maintainer for PyME, releasing
|
||||
version 0.9.0 in May of that year. He remains the maintainer of
|
||||
the original PyME release in Python 2.6 and 2.7 (available via
|
||||
PyPI).
|
||||
|
||||
@node Coming full circle
|
||||
@section Coming full circle
|
||||
|
||||
In 2015 Ben McGinnes approached Martin about a Python 3 version,
|
||||
while investigating how complex a task this would be the task ended
|
||||
up being completed. A subsequent discussion with Werner Koch led
|
||||
to the decision to fold the Python 3 port back into the original
|
||||
GPGME release in the languages subdirectory for non-C bindings
|
||||
under the module name of @samp{pyme3}.
|
||||
|
||||
In 2016 this PyME module was integrated back into the GPGME project
|
||||
by Justus Winter. During the course of this work Justus adjusted
|
||||
the port to restore limited support for Python 2, but not as many
|
||||
minor point releases as the original PyME package supports. During
|
||||
the course of this integration the package was renamed to more
|
||||
accurately reflect its status as a component of GPGME. The @samp{pyme3}
|
||||
module was renamed to @samp{gpg} and adopted by the upstream GnuPG team.
|
||||
|
||||
In 2017 Justus departed G10code and the GnuPG team. Following this
|
||||
Ben returned to maintain of gpgme Python bindings and continue
|
||||
building them from that point.
|
||||
|
||||
@node Relics of the past
|
||||
@chapter Relics of the past
|
||||
|
||||
There are a few things, in addition to code specific factors, such as
|
||||
SWIG itself, which are worth noting here.
|
||||
|
||||
@menu
|
||||
* The Annoyances of Git::
|
||||
* The Perils of PyPI::
|
||||
@end menu
|
||||
|
||||
@node The Annoyances of Git
|
||||
@section The Annoyances of Git
|
||||
|
||||
As anyone who has ever worked with git knows, submodules are
|
||||
horrible way to deal with pretty much anything. In the interests
|
||||
of avoiding migraines, that was skipped with addition of the PyME
|
||||
code to GPGME.
|
||||
|
||||
Instead the files were added to a subdirectory of the @samp{lang/}
|
||||
directory, along with a copy of the entire git log up to that point
|
||||
as a separate file within the @samp{lang/python/docs/} directory.@footnote{The entire PyME git log and other preceding VCS logs are
|
||||
located in the @samp{gpgme/lang/python/docs/old-commits.log} file.}
|
||||
As the log for PyME is nearly 100KB and the log for GPGME is
|
||||
approximately 1MB, this would cause considerable bloat, as well as
|
||||
some confusion, should the two be merged.
|
||||
|
||||
Hence the unfortunate, but necessary, step to simply move the
|
||||
files. A regular repository version has been maintained should it
|
||||
be possible to implement this better in the future.
|
||||
|
||||
@node The Perils of PyPI
|
||||
@section The Perils of PyPI
|
||||
|
||||
The early port of the Python 2 @samp{pyme} module as @samp{pyme3} was never
|
||||
added to PyPI while the focus remained on development and testing
|
||||
during 2015 and early 2016. Later in 2016, however, when Justus
|
||||
completed his major integration work and subsequently renamed the
|
||||
module from @samp{pyme3} to @samp{gpg}, some prior releases were also
|
||||
provided through PyPI.
|
||||
|
||||
Since these bindings require a matching release of the GPGME
|
||||
libraries in order to function, it was determined that there was
|
||||
little benefit in also providing a copy through PyPI since anyone
|
||||
obtaining the GPGME source code would obtain the Python bindings
|
||||
source code at the same time. Whereas there was the potential to
|
||||
sew confusion amongst Python users installing the module from PyPI,
|
||||
only to discover that without the relevant C files, header files or
|
||||
SWIG compiled binaries, the Python module did them little good.
|
||||
|
||||
There are only two files on PyPI which might turn up in a search
|
||||
for this module or a sample of its content:
|
||||
|
||||
@enumerate
|
||||
@item
|
||||
gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
|
||||
@item
|
||||
pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
|
||||
@end enumerate
|
||||
|
||||
@menu
|
||||
* GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library: GPG 180 - Python bindings for GPGME GnuPG cryptography library.
|
||||
* PyME 0.9.0 - Python support for GPGME GnuPG cryptography library: PyME 090 - Python support for GPGME GnuPG cryptography library.
|
||||
@end menu
|
||||
|
||||
@node GPG 180 - Python bindings for GPGME GnuPG cryptography library
|
||||
@subsection GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
|
||||
|
||||
This is the most recent version to reach PyPI and is the version
|
||||
of the official Pyhon bindings which shipped with GPGME 1.8.0. If
|
||||
you have GPGME 1.8.0 installed and @emph{only} 1.8.0 installed, then it
|
||||
is probably safe to use this copy from PyPI.
|
||||
|
||||
As there have been a lot of changes since the release of GPGME
|
||||
1.8.0, the GnuPG Project recommends not using this version of the
|
||||
module and instead installing the current version of GPGME along
|
||||
with the Python bindings included with that package.
|
||||
|
||||
@node PyME 090 - Python support for GPGME GnuPG cryptography library
|
||||
@subsection PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
|
||||
|
||||
This is the last release of the PyME bindings maintained by Martin
|
||||
Albrecht and is only compatible with Python 2, it will not work
|
||||
with Python 3. This is the version of the software from which the
|
||||
port from Python 2 to Python 3 code was made in 2015.
|
||||
|
||||
Users of the more recent Python bindings will recognise numerous
|
||||
points of similarity, but also significant differences. It is
|
||||
likely that the more recent official bindings will feel "more
|
||||
pythonic."
|
||||
|
||||
For those using Python 2, there is essentially no harm in using
|
||||
this module, but it may lack a number of more recent features
|
||||
added to GPGME.
|
||||
|
||||
@bye
|
||||
Loading…
Reference in New Issue
Block a user