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