python: docs
[gpgme.git] / lang / python / doc / texinfo / short-history.texi
1 \input texinfo    @c -*- texinfo -*-
2 @c %**start of header
3 @setfilename short-history.info
4 @settitle A Short History of the GPGME bindings for Python
5 @documentencoding utf-8
6 @documentlanguage en
7 @c %**end of header
8
9 @finalout
10 @titlepage
11 @title A Short History of the GPGME bindings for Python
12 @author Ben McGinnes
13 @end titlepage
14
15 @contents
16
17 @ifnottex
18 @node Top
19 @top A Short History of the GPGME bindings for Python
20 @end ifnottex
21
22 @menu
23 * Overview::
24 * Relics of the past::
25
26 @detailmenu
27 --- The Detailed Node Listing ---
28
29 Overview
30
31 * In the beginning::
32 * Keeping the flame alive::
33 * Passing the torch::
34 * Coming full circle::
35
36 Relics of the past
37
38 * The Annoyances of Git::
39 * The Perils of PyPI::
40
41 The Perils of PyPI
42
43 * GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library::
44 * PyME 0·9·0 - Python support for GPGME GnuPG cryptography library::
45
46 @end detailmenu
47 @end menu
48
49 @node Overview
50 @chapter Overview
51
52 @multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
53 @item Version:
54 @tab 0.0.1
55 @item GPGME Version:
56 @tab 1.13.0
57 @item Author:
58 @tab Ben McGinnes <ben@@gnupg.org>
59 @item Author GPG Key:
60 @tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
61 @item Language:
62 @tab Australian English, British English
63 @item xml:lang:
64 @tab en-AU, en-GB, en
65 @end multitable
66
67 The GPGME Python bindings passed through many hands and numerous
68 phases before, after a fifteen year journey, coming full circle to
69 return to the source.  This is a short explanation of that journey.
70
71 @menu
72 * In the beginning::
73 * Keeping the flame alive::
74 * Passing the torch::
75 * Coming full circle::
76 @end menu
77
78 @node In the beginning
79 @section In the beginning
80
81 In 2002 John Goerzen released PyME; Python bindings for the GPGME
82 module which utilised the current release of Python of the time and
83 SWIG.@footnote{In all likelihood this would have been Python 2.2 or possibly
84 Python 2.3.}  Shortly after creating it and ensuring it worked he stopped
85 supporting it, though he left his work available on his Gopher
86 site.
87
88 @node Keeping the flame alive
89 @section Keeping the flame alive
90
91 A couple of years later the project was picked up by Igor Belyi and
92 actively developed and maintained by him from 2004 to 2008.  Igor's
93 whereabouts at the time of this document's creation are unknown,
94 but the current authors do hope he is well.  We're assuming (or
95 hoping) that life did what life does and made continuing untenable.
96
97 @node Passing the torch
98 @section Passing the torch
99
100 In 2014 Martin Albrecht wanted to patch a bug in the PyME code and
101 discovered the absence of Igor.  Following a discussion on the PyME
102 mailing list he became the new maintainer for PyME, releasing
103 version 0.9.0 in May of that year.  He remains the maintainer of
104 the original PyME release in Python 2.6 and 2.7 (available via
105 PyPI).
106
107 @node Coming full circle
108 @section Coming full circle
109
110 In 2015 Ben McGinnes approached Martin about a Python 3 version,
111 while investigating how complex a task this would be the task ended
112 up being completed.  A subsequent discussion with Werner Koch led
113 to the decision to fold the Python 3 port back into the original
114 GPGME release in the languages subdirectory for non-C bindings
115 under the module name of @samp{pyme3}.
116
117 In 2016 this PyME module was integrated back into the GPGME project
118 by Justus Winter.  During the course of this work Justus adjusted
119 the port to restore limited support for Python 2, but not as many
120 minor point releases as the original PyME package supports.  During
121 the course of this integration the package was renamed to more
122 accurately reflect its status as a component of GPGME.  The @samp{pyme3}
123 module was renamed to @samp{gpg} and adopted by the upstream GnuPG team.
124
125 In 2017 Justus departed G10code and the GnuPG team.  Following this
126 Ben returned to maintain of gpgme Python bindings and continue
127 building them from that point.
128
129 @node Relics of the past
130 @chapter Relics of the past
131
132 There are a few things, in addition to code specific factors, such as
133 SWIG itself, which are worth noting here.
134
135 @menu
136 * The Annoyances of Git::
137 * The Perils of PyPI::
138 @end menu
139
140 @node The Annoyances of Git
141 @section The Annoyances of Git
142
143 As anyone who has ever worked with git knows, submodules are
144 horrible way to deal with pretty much anything.  In the interests
145 of avoiding migraines, that was skipped with addition of the PyME
146 code to GPGME.
147
148 Instead the files were added to a subdirectory of the @samp{lang/}
149 directory, along with a copy of the entire git log up to that point
150 as a separate file within the @samp{lang/python/docs/} directory.@footnote{The entire PyME git log and other preceding VCS logs are
151 located in the @samp{gpgme/lang/python/docs/old-commits.log} file.}
152 As the log for PyME is nearly 100KB and the log for GPGME is
153 approximately 1MB, this would cause considerable bloat, as well as
154 some confusion, should the two be merged.
155
156 Hence the unfortunate, but necessary, step to simply move the
157 files.  A regular repository version has been maintained should it
158 be possible to implement this better in the future.
159
160 @node The Perils of PyPI
161 @section The Perils of PyPI
162
163 The early port of the Python 2 @samp{pyme} module as @samp{pyme3} was never
164 added to PyPI while the focus remained on development and testing
165 during 2015 and early 2016.  Later in 2016, however, when Justus
166 completed his major integration work and subsequently renamed the
167 module from @samp{pyme3} to @samp{gpg}, some prior releases were also
168 provided through PyPI.
169
170 Since these bindings require a matching release of the GPGME
171 libraries in order to function, it was determined that there was
172 little benefit in also providing a copy through PyPI since anyone
173 obtaining the GPGME source code would obtain the Python bindings
174 source code at the same time.  Whereas there was the potential to
175 sew confusion amongst Python users installing the module from PyPI,
176 only to discover that without the relevant C files, header files or
177 SWIG compiled binaries, the Python module did them little good.
178
179 There are only two files on PyPI which might turn up in a search
180 for this module or a sample of its content:
181
182 @enumerate
183 @item
184 gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
185 @item
186 pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
187 @end enumerate
188
189 @menu
190 * GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library::
191 * PyME 0·9·0 - Python support for GPGME GnuPG cryptography library::
192 @end menu
193
194 @node GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library
195 @subsection GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library
196
197 This is the most recent version to reach PyPI and is the version
198 of the official Pyhon bindings which shipped with GPGME 1.8.0.  If
199 you have GPGME 1.8.0 installed and @emph{only} 1.8.0 installed, then it
200 is probably safe to use this copy from PyPI.
201
202 As there have been a lot of changes since the release of GPGME
203 1.8.0, the GnuPG Project recommends not using this version of the
204 module and instead installing the current version of GPGME along
205 with the Python bindings included with that package.
206
207 @node PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
208 @subsection PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
209
210 This is the last release of the PyME bindings maintained by Martin
211 Albrecht and is only compatible with Python 2, it will not work
212 with Python 3.  This is the version of the software from which the
213 port from Python 2 to Python 3 code was made in 2015.
214
215 Users of the more recent Python bindings will recognise numerous
216 points of similarity, but also significant differences.  It is
217 likely that the more recent official bindings will feel "more
218 pythonic."
219
220 For those using Python 2, there is essentially no harm in using
221 this module, but it may lack a number of more recent features
222 added to GPGME.
223
224 @bye