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