diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org index e0cd877e..89bb21e1 100644 --- a/lang/python/docs/Short_History.org +++ b/lang/python/docs/Short_History.org @@ -1,163 +1,165 @@ #+TITLE: A Short History of the GPGME bindings for Python +#+LATEX_CLASS: article +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} * Overview :PROPERTIES: :CUSTOM_ID: overview :END: The GPGME Python bindings passed through many hands and numerous phases before, after a fifteen year journey, coming full circle to return to the source. This is a short explanation of that journey. ** In the beginning :PROPERTIES: :CUSTOM_ID: in-the-begining :END: In 2002 John Goerzen released PyME; Python bindings for the GPGME module which utilised the current release of Python of the time (Python 2.2 or 2.3) and SWIG. Shortly after creating it and ensuring it worked he stopped supporting it, though he left his work available on his Gopher site. ** Keeping the flame alive :PROPERTIES: :CUSTOM_ID: keeping-the-flame-alive :END: A couple of years later the project was picked up by Igor Belyi and actively developed and maintained by him from 2004 to 2008. Igor's whereabouts at the time of this document's creation are unknown, but the current authors do hope he is well. We're assuming (or hoping) that life did what life does and made continuing untenable. ** Passing the torch :PROPERTIES: :CUSTOM_ID: passing-the-torch :END: In 2014 Martin Albrecht wanted to patch a bug in the PyME code and discovered the absence of Igor. Following a discussion on the PyME mailing list he became the new maintainer for PyME, releasing version 0.9.0 in May of that year. He remains the maintainer of the original PyME release in Python 2.6 and 2.7 (available via PyPI). ** Coming full circle :PROPERTIES: :CUSTOM_ID: ouroboros :END: In 2015 Ben McGinnes approached Martin about a Python 3 version, while investigating how complex a task this would be the task ended up being completed. A subsequent discussion with Werner Koch led to the decision to fold the Python 3 port back into the original GPGME release in the languages subdirectory for non-C bindings under the module name of =pyme3=. In 2016 this PyME module was integrated back into the GPGME project by Justus Winter. During the course of this work Justus adjusted the port to restore limited support for Python 2, but not as many minor point releases as the original PyME package supports. During the course of this integration the package was renamed to more accurately reflect its status as a component of GPGME. The =pyme3= module was renamed to =gpg= and adopted by the upstream GnuPG team. In 2017 Justus departed G10code and the GnuPG team. Following this Ben returned to maintain of gpgme Python bindings and continue building them from that point. * Relics of the past :PROPERTIES: :CUSTOM_ID: relics-past :END: There are a few things, in addition to code specific factors, such as SWIG itself, which are worth noting here. ** The Annoyances of Git :PROPERTIES: :CUSTOM_ID: the-annoyances-of-git :END: As anyone who has ever worked with git knows, submodules are horrible way to deal with pretty much anything. In the interests of avoiding migraines, that was skipped with addition of the PyME code to GPGME. Instead the files were added to a subdirectory of the =lang/= directory, along with a copy of the entire git log up to that point as a separate file within the =lang/python/docs/= directory.[fn:1] As the log for PyME is nearly 100KB and the log for GPGME is approximately 1MB, this would cause considerable bloat, as well as some confusion, should the two be merged. Hence the unfortunate, but necessary, step to simply move the files. A regular repository version has been maintained should it be possible to implement this better in the future. ** The Perils of PyPI :PROPERTIES: :CUSTOM_ID: the-perils-of-pypi :END: The early port of the Python 2 =pyme= module as =pyme3= was never added to PyPI while the focus remained on development and testing during 2015 and early 2016. Later in 2016, however, when Justus completed his major integration work and subsequently renamed the module from =pyme3= to =gpg=, some prior releases were also provided through PyPI. Since these bindings require a matching release of the GPGME libraries in order to function, it was determined that there was little benefit in also providing a copy through PyPI since anyone obtaining the GPGME source code would obtain the Python bindings source code at the same time. Whereas there was the potential to sew confusion amongst Python users installing the module from PyPI, only to discover that without the relevant C files, header files or SWIG compiled binaries, the Python module did them little good. There are only two files on PyPI which might turn up in a search for this module or a sample of its content: 1. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library 2. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library *** GPG 1.8.0 - Python bindings for GPGME GnuPG cryptography library :PROPERTIES: :CUSTOM_ID: pypi-gpgme-180 :END: This is the most recent version to reach PyPI and is the version of the official Pyhon bindings which shipped with GPGME 1.8.0. If you have GPGME 1.8.0 installed and /only/ 1.8.0 installed, then it is probably safe to use this copy from PyPI. As there have been a lot of changes since the release of GPGME 1.8.0, the GnuPG Project recommends not using this version of the module and instead installing the current version of GPGME along with the Python bindings included with that package. *** PyME 0.9.0 - Python support for GPGME GnuPG cryptography library :PROPERTIES: :CUSTOM_ID: pypi-gpgme-90 :END: This is the last release of the PyME bindings maintained by Martin Albrecht and is only compatible with Python 2, it will not work with Python 3. This is the version of the software from which the port from Python 2 to Python 3 code was made in 2015. Users of the more recent Python bindings will recognise numerous points of similarity, but also significant differences. It is likely that the more recent official bindings will feel "more pythonic." For those using Python 2, there is essentially no harm in using this module, but it may lack a number of more recent features added to GPGME. * Footnotes [fn:1] The entire PyME git log and other preceding VCS logs are located in the =gpgme/lanf/python/docs/old-commits.log= file. diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 1ddd394e..10324e60 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,75 +1,140 @@ #+TITLE: Stuff To Do +#+LATEX_CLASS: article +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} * Project Task List + :PROPERTIES: + :CUSTOM_ID: task-list + :END: ** DONE Documentation default format CLOSED: [2018-02-15 Thu 21:29] :PROPERTIES: :CUSTOM_ID: todo-docs-default :END: Decide on a default file format for documentation. The two main contenders being Org Mode, the default for the GnuPG Project and reStructuredText, the default for Python projects. A third option of DITA XML was considered due to a number of beneficial features it provides. The decision was made to use Org Mode in order to fully integrate with the rest of the GPGME and GnuPG documentation. It is possible to produce reST versions via Pandoc and DITA XML can be reached through converting to either Markdown or XHTML first. +** TODO Documentation HOWTO + :PROPERTIES: + :CUSTOM_ID: todo-docs-howto + :END: + + Write a HOWTO style guide for the current Python bindings. + +** TODO Documentation SWIG + :PROPERTIES: + :CUSTOM_ID: todo-docs-swig + :END: + + Write documentation for the complete SWIG bindings demonstrating + the correspondence with GPGME itself. + + Note: it is likely that this will be more in the nature of + something to be used in conjunction with the existing GPGME + documentation which makes it easier for Python developers to use. + ** TODO GUI examples :PROPERTIES: :CUSTOM_ID: todo-gui-examples :END: Create some examples of using Python bindings in a GUI application to either match or be similar to the old GTK2 examples available with PyME. +** TODO Replace SWIG + :PROPERTIES: + :CUSTOM_ID: todo-replace-swig + :END: + + Selecting SWIG for this project in 2002 was understandable and + effectively the only viable option. The options available now, + however, are significantly improved and some of those would resolve + a number of existing problems with using SWIG, particularly when + running code on both POSIX compliant and Windows platforms. + + The long term goal is to replace SWIG by reimplementing the Python + bindings using a more suitable means of interfacing with the GPGME + C source code. + +*** TODO Replacement for SWIG + :PROPERTIES: + :CUSTOM_ID: todo-replace-swig-replacement + :END: + + Decide on a replacement for SWIG. Currently CFFI is looking like + the most viable candidate, but some additional testing and checks + are yet to be completed. + +** TODO API for an API + :PROPERTIES: + :CUSTOM_ID: todo-api-squared + :END: + + A C API like GPGME is not what most modern developers think of when + they hear the term API. Normally they think of something they can + interact with like a RESTful web API. Though RESTful is unlikely + given the nature of GPGME and the process of encryption, it may be + possible to provide a more familiar interface which can be utilised + by developers of other languages for which bindings are not + available or for which it is too difficult to create proper + bindings. + * Project Task Details + :PROPERTIES: + :CUSTOM_ID: detailed-tasks + :END: ** Working examples :PROPERTIES: :CUSTOM_ID: working-examples :END: The old GUI examples were unable to be retained since they depended on GTK2 and Python 2's integration with GTK2. Current GPGME examples so far only include command line tools or basic Python code for use with either Python 2.7 or Python 3.4 and above. Future GUI examples ought to utilise available GUI modules and libraries supported by Python 3. This may include Qt frameworks, Tkinter, GTK3 or something else entirely. ** Documentation :PROPERTIES: :CUSTOM_ID: documentation :END: The legacy documentation which no longer applies to the Python bindings has been removed. Current and future documentation will adhere to the GnuPG standard of using Org Mode and not use the reStructuredText (reST) format more commonly associated with Python documentation. The reasons for this are that this project is best served as shipping with the rest of GPGME and the documentation ought to match that. There are also aspects of Org Mode's publishing features which are superior to the defaults of reST, including the capacity to generate fully validating strict XHTML output. If reST files are required at a later point for future inclusion with other Python packages, then that format can be generated from the .org files with Pandoc before being leveraged by either Docutils, Sphinx or something else. While there are some advanced typesetting features of reST which are not directly available to Org Mode, more often than not those features are best implemented with either HTML and CSS, with LaTeX to produce a PDF or via a number of XML solutions. Both reST and Org Mode have multiple paths by which to achieve all of these.