diff options
Diffstat (limited to 'lang/python')
| -rw-r--r-- | lang/python/README | 94 | ||||
| -rw-r--r-- | lang/python/README.org | 61 | ||||
| -rw-r--r-- | lang/python/docs/Short_History.org | 172 | ||||
| -rw-r--r-- | lang/python/docs/Short_History.rst | 57 | ||||
| -rw-r--r-- | lang/python/docs/TODO.org | 144 | ||||
| -rw-r--r-- | lang/python/docs/TODO.rst | 23 |
6 files changed, 432 insertions, 119 deletions
diff --git a/lang/python/README b/lang/python/README index 6a2e8b8c..49e88205 100644 --- a/lang/python/README +++ b/lang/python/README @@ -1,61 +1,77 @@ -gpg - GPGME bindings for Python -*- org -*- -======================= + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + GPG - GPGME BINDINGS FOR PYTHON + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + + +Table of Contents +───────────────── + +1 Mailing List +2 Bugs +3 Authors +4 History + The "gpg" module is a python interface to the GPGME library: -https://www.gnupg.org/related_software/gpgme/ +[https://www.gnupg.org/related_software/gpgme/] -"gpg" offers two interfaces, one is a high-level, curated, and -idiomatic interface that is implemented as a shim on top of the -low-level interface automatically created using SWIG. +"gpg" offers two interfaces, one is a high-level, curated, and idiomatic +interface that is implemented as a shim on top of the low-level +interface automatically created using SWIG. This way we make simple things easy, while still providing the entire functionality of the underlying library. -* Mailing List -For general discussion and help see the gnupg-users mailing list: -https://lists.gnupg.org/mailman/listinfo/gnupg-users +1 Mailing List +══════════════ + + For general discussion and help see the gnupg-users mailing list: + [https://lists.gnupg.org/mailman/listinfo/gnupg-users] + + For development see the gnupg-devel mailing list: + [https://lists.gnupg.org/mailman/listinfo/gnupg-devel] + + +2 Bugs +══════ -For development see the gnupg-devel mailing list: -https://lists.gnupg.org/mailman/listinfo/gnupg-devel + Please report bugs using our bug tracker using the category 'gpgme', + and topic 'python': [https://bugs.gnupg.org/gnupg/] -* Bugs -Please report bugs using our bug tracker using the category 'gpgme', -and topic 'python': -https://bugs.gnupg.org/gnupg/ +3 Authors +═════════ -* Authors + PyME was created by John Goerzen, and maintained, developed, and + cherished by Igor Belyi, Martin Albrecht, Ben McGinnes, and everyone + who contributed to it in any way. -PyME was created by John Goerzen, and maintained, developed, and -cherished by Igor Belyi, Martin Albrecht, Ben McGinnes, and everyone -who contributed to it in any way. + In 2016 we merged a port of PyME to into the GPGME repository, and + development will continue there. Please see the VCS history for the + list of contributors, and if you do find bugs, or want to contribute, + please get in touch and help maintain the python gpg bindings. -In 2016 we merged a port of PyME to into the GPGME repository, and -development will continue there. Please see the VCS history for the -list of contributors, and if you do find bugs, or want to contribute, -please get in touch and help maintain the python gpg bindings. + Please see the section 'History' further down this document for + references to previous versions. -Please see the section 'History' further down this document for -references to previous versions. -* History +4 History +═════════ - - The python bindings were renamed from PyME to "gpg" in 2016. + • The python bindings were renamed from PyME to "gpg" in 2016. - - The bindings have been merged into the GPGME repository in 2016. + • The bindings have been merged into the GPGME repository in 2016. - - The latest version of PyME for Python 3.2 and above (as of - May, 2015) is v0.9.1. - https://git.gnupg.org/gpgme.git/lang/py3-pyme + • The latest version of PyME for Python 3.2 and above (as of May, + 2015) is v0.9.1. [https://git.gnupg.org/gpgme.git/lang/py3-pyme] - - The latest version of PyME for Python 2.6 and 2.7 (as of this - writing) is v0.9.0. https://bitbucket.org/malb/pyme + • The latest version of PyME for Python 2.6 and 2.7 (as of this + writing) is v0.9.0. [https://bitbucket.org/malb/pyme] - - A previous version of PyME v0.8.0 can be found on sourceforge: - http://pyme.sourceforge.net/ + • A previous version of PyME v0.8.0 can be found on sourceforge: + [http://pyme.sourceforge.net/] - - A previous version of PyME v0.5.1 which works with GPGME v0.3.15 - can be found on John Goerzen's PyME page: - http://quux.org/devel/pyme/ - http://www.complete.org/JohnGoerzen + • A previous version of PyME v0.5.1 which works with GPGME v0.3.15 can + be found on John Goerzen's PyME page: [http://quux.org/devel/pyme/] + [http://www.complete.org/JohnGoerzen] diff --git a/lang/python/README.org b/lang/python/README.org new file mode 100644 index 00000000..22e7d1f8 --- /dev/null +++ b/lang/python/README.org @@ -0,0 +1,61 @@ +#+TITLE: gpg - GPGME bindings for Python + + +The "gpg" module is a python interface to the GPGME library: +https://www.gnupg.org/related_software/gpgme/ + +"gpg" offers two interfaces, one is a high-level, curated, and +idiomatic interface that is implemented as a shim on top of the +low-level interface automatically created using SWIG. + +This way we make simple things easy, while still providing the entire +functionality of the underlying library. + +* Mailing List + +For general discussion and help see the gnupg-users mailing list: +https://lists.gnupg.org/mailman/listinfo/gnupg-users + +For development see the gnupg-devel mailing list: +https://lists.gnupg.org/mailman/listinfo/gnupg-devel + +* Bugs + +Please report bugs using our bug tracker using the category 'gpgme', +and topic 'python': +https://bugs.gnupg.org/gnupg/ + +* Authors + +PyME was created by John Goerzen, and maintained, developed, and +cherished by Igor Belyi, Martin Albrecht, Ben McGinnes, and everyone +who contributed to it in any way. + +In 2016 we merged a port of PyME to into the GPGME repository, and +development will continue there. Please see the VCS history for the +list of contributors, and if you do find bugs, or want to contribute, +please get in touch and help maintain the python gpg bindings. + +Please see the section 'History' further down this document for +references to previous versions. + +* History + + - The python bindings were renamed from PyME to "gpg" in 2016. + + - The bindings have been merged into the GPGME repository in 2016. + + - The latest version of PyME for Python 3.2 and above (as of + May, 2015) is v0.9.1. + https://git.gnupg.org/gpgme.git/lang/py3-pyme + + - The latest version of PyME for Python 2.6 and 2.7 (as of this + writing) is v0.9.0. https://bitbucket.org/malb/pyme + + - A previous version of PyME v0.8.0 can be found on sourceforge: + http://pyme.sourceforge.net/ + + - A previous version of PyME v0.5.1 which works with GPGME v0.3.15 + can be found on John Goerzen's PyME page: + http://quux.org/devel/pyme/ + http://www.complete.org/JohnGoerzen diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org new file mode 100644 index 00000000..f684f0a7 --- /dev/null +++ b/lang/python/docs/Short_History.org @@ -0,0 +1,172 @@ +#+TITLE: A Short History of the GPGME bindings for Python +#+LATEX_COMPILER: xelatex +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [12pt] +#+LATEX_HEADER: \usepackage{xltxtra} +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} +#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman} + +* 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 and + SWIG.[fn:1] 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:2] + 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] In all likelihood thos would have been Python 2.2 or possibly +Python 2.3. + +[fn:2] The entire PyME git log and other preceding VCS logs are +located in the =gpgme/lang/python/docs/old-commits.log= file. diff --git a/lang/python/docs/Short_History.rst b/lang/python/docs/Short_History.rst deleted file mode 100644 index 8f609272..00000000 --- a/lang/python/docs/Short_History.rst +++ /dev/null @@ -1,57 +0,0 @@ -========================================== -A Short History of gpg bindings for Python -========================================== - -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 left his work available on -his Gopher site. - -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. - -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). - -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. Ben is the -maintainer of the Python 3 port within GPGME. - -In 2016 PyME was renamed to "gpg" and adopted by the upstream GnuPG -team. - ---------------------- -The Annoyances of Git ---------------------- - -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 is being skipped with addition of PyME to GPGME. -Instead the files will be added to the subdirectory, along with a copy -of the entire git log up to that point as a separate file within the -docs directory (old-commits.log). 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 will be maintained should it be -possible to implement this better in the future. - - ------------------- -The Perils of PyPI ------------------- - -At the current time the Python 3 fork is not available via PyPI and -the pip installer. The recommended installation method is to follow -the instructions in lang/py3-pyme/INSTALL. This will build the -necessary SWIG portions against the installed version of GPGME. diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org new file mode 100644 index 00000000..9f039d81 --- /dev/null +++ b/lang/python/docs/TODO.org @@ -0,0 +1,144 @@ +#+TITLE: Stuff To Do +#+LATEX_COMPILER: xelatex +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [12pt] +#+LATEX_HEADER: \usepackage{xltxtra} +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} +#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman} + +* 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. diff --git a/lang/python/docs/TODO.rst b/lang/python/docs/TODO.rst deleted file mode 100644 index a398ccdf..00000000 --- a/lang/python/docs/TODO.rst +++ /dev/null @@ -1,23 +0,0 @@ -=========== -Stuff To Do -=========== - ----------------- -Working examples ----------------- - -The examples from the Python 2 code base do not work and it appears -that they don't under Python 2 either. These ought to be replaced or -updated with examples from the GPGME documentation. - - -------------- -Documentation -------------- - -Currently this appears to be buried in the debian/ directory for some -unknown reason, probably pertaining to one of the other developers. -Documentation is to be moved to a more appropriate docs/ directory and -produced using reST in preparation for inevitable publication by way -of Sphinx and the existing infrastructure at readthedocs.org or the -projects new home at gnupg.org. |