Merge branch 'master' of /Users/ben/dev/hgit/mine/gnupg/gpgme/master into ben/python...
[gpgme.git] / lang / python / docs / Short_History.org
1 #+TITLE: A Short History of the GPGME bindings for Python
2 #+LATEX_CLASS: article
3 #+LATEX_HEADER: \usepackage[margin=1in]{geometry}
4
5 * Overview
6   :PROPERTIES:
7   :CUSTOM_ID: overview
8   :END:
9
10 The GPGME Python bindings passed through many hands and numerous
11 phases before, after a fifteen year journey, coming full circle to
12 return to the source.  This is a short explanation of that journey.
13
14 ** In the beginning
15    :PROPERTIES:
16    :CUSTOM_ID: in-the-begining
17    :END:
18
19    In 2002 John Goerzen released PyME; Python bindings for the GPGME
20    module which utilised the current release of Python of the time
21    (Python 2.2 or 2.3) and SWIG.  Shortly after creating it and
22    ensuring it worked he stopped supporting it, though he left his
23    work available on his Gopher site.
24
25 ** Keeping the flame alive
26    :PROPERTIES:
27    :CUSTOM_ID: keeping-the-flame-alive
28    :END:
29
30    A couple of years later the project was picked up by Igor Belyi and
31    actively developed and maintained by him from 2004 to 2008.  Igor's
32    whereabouts at the time of this document's creation are unknown,
33    but the current authors do hope he is well.  We're assuming (or
34    hoping) that life did what life does and made continuing untenable.
35
36 ** Passing the torch
37    :PROPERTIES:
38    :CUSTOM_ID: passing-the-torch
39    :END:
40
41    In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
42    discovered the absence of Igor.  Following a discussion on the PyME
43    mailing list he became the new maintainer for PyME, releasing
44    version 0.9.0 in May of that year.  He remains the maintainer of
45    the original PyME release in Python 2.6 and 2.7 (available via
46    PyPI).
47
48 ** Coming full circle
49    :PROPERTIES:
50    :CUSTOM_ID: ouroboros 
51    :END:
52
53    In 2015 Ben McGinnes approached Martin about a Python 3 version,
54    while investigating how complex a task this would be the task ended
55    up being completed.  A subsequent discussion with Werner Koch led
56    to the decision to fold the Python 3 port back into the original
57    GPGME release in the languages subdirectory for non-C bindings
58    under the module name of =pyme3=.
59
60    In 2016 this PyME module was integrated back into the GPGME project
61    by Justus Winter.  During the course of this work Justus adjusted
62    the port to restore limited support for Python 2, but not as many
63    minor point releases as the original PyME package supports.  During
64    the course of this integration the package was renamed to more
65    accurately reflect its status as a component of GPGME.  The =pyme3=
66    module was renamed to =gpg= and adopted by the upstream GnuPG team.
67
68    In 2017 Justus departed G10code and the GnuPG team.  Following this
69    Ben returned to maintain of gpgme Python bindings and continue
70    building them from that point.
71
72 * Relics of the past
73   :PROPERTIES:
74   :CUSTOM_ID: relics-past
75   :END:
76
77 There are a few things, in addition to code specific factors, such as
78 SWIG itself, which are worth noting here.
79
80 ** The Annoyances of Git
81    :PROPERTIES:
82    :CUSTOM_ID: the-annoyances-of-git
83    :END:
84
85    As anyone who has ever worked with git knows, submodules are
86    horrible way to deal with pretty much anything.  In the interests
87    of avoiding migraines, that was skipped with addition of the PyME
88    code to GPGME.
89
90    Instead the files were added to a subdirectory of the =lang/=
91    directory, along with a copy of the entire git log up to that point
92    as a separate file within the =lang/python/docs/= directory.[fn:1]
93    As the log for PyME is nearly 100KB and the log for GPGME is
94    approximately 1MB, this would cause considerable bloat, as well as
95    some confusion, should the two be merged.
96
97    Hence the unfortunate, but necessary, step to simply move the
98    files.  A regular repository version has been maintained should it
99    be possible to implement this better in the future.
100
101 ** The Perils of PyPI
102    :PROPERTIES:
103    :CUSTOM_ID: the-perils-of-pypi
104    :END:
105
106    The early port of the Python 2 =pyme= module as =pyme3= was never
107    added to PyPI while the focus remained on development and testing
108    during 2015 and early 2016.  Later in 2016, however, when Justus
109    completed his major integration work and subsequently renamed the
110    module from =pyme3= to =gpg=, some prior releases were also
111    provided through PyPI.
112
113    Since these bindings require a matching release of the GPGME
114    libraries in order to function, it was determined that there was
115    little benefit in also providing a copy through PyPI since anyone
116    obtaining the GPGME source code would obtain the Python bindings
117    source code at the same time.  Whereas there was the potential to
118    sew confusion amongst Python users installing the module from PyPI,
119    only to discover that without the relevant C files, header files or
120    SWIG compiled binaries, the Python module did them little good.
121
122    There are only two files on PyPI which might turn up in a search
123    for this module or a sample of its content:
124
125    1. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
126    2. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
127
128 *** GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library
129     :PROPERTIES:
130     :CUSTOM_ID: pypi-gpgme-180
131     :END:
132
133     This is the most recent version to reach PyPI and is the version
134     of the official Pyhon bindings which shipped with GPGME 1.8.0.  If
135     you have GPGME 1.8.0 installed and /only/ 1.8.0 installed, then it
136     is probably safe to use this copy from PyPI.
137
138     As there have been a lot of changes since the release of GPGME
139     1.8.0, the GnuPG Project recommends not using this version of the
140     module and instead installing the current version of GPGME along
141     with the Python bindings included with that package.
142
143 *** PyME 0.9.0 - Python support for GPGME GnuPG cryptography library
144     :PROPERTIES:
145     :CUSTOM_ID: pypi-gpgme-90
146     :END:
147
148     This is the last release of the PyME bindings maintained by Martin
149     Albrecht and is only compatible with Python 2, it will not work
150     with Python 3.  This is the version of the software from which the
151     port from Python 2 to Python 3 code was made in 2015.
152
153     Users of the more recent Python bindings will recognise numerous
154     points of similarity, but also significant differences.  It is
155     likely that the more recent official bindings will feel "more
156     pythonic."
157
158     For those using Python 2, there is essentially no harm in using
159     this module, but it may lack a number of more recent features
160     added to GPGME.
161
162 * Footnotes
163
164 [fn:1] The entire PyME git log and other preceding VCS logs are
165 located in the =gpgme/lanf/python/docs/old-commits.log= file.