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