From d86fd7c54c462ef23c70370624e07fcc1bc15121 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 21:21:58 +1100 Subject: [PATCH 01/18] Short History * Converted document from reST to org-mode. --- lang/python/docs/Short_History.org | 56 ++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 lang/python/docs/Short_History.org diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org new file mode 100644 index 00000000..fa40d6eb --- /dev/null +++ b/lang/python/docs/Short_History.org @@ -0,0 +1,56 @@ +#+TITLE: 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 + :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 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 + :PROPERTIES: + :CUSTOM_ID: the-perils-of-pypi + :END: + +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. From 1d48b04cfb3d1de654f3995578e9434a6b7b2fed Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 21:23:04 +1100 Subject: [PATCH 02/18] Short History * Removed reST version. --- lang/python/docs/Short_History.rst | 57 ------------------------------ 1 file changed, 57 deletions(-) delete mode 100644 lang/python/docs/Short_History.rst 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. From c4fa4216199b16c1f169725c0a1e0a40764b1ebb Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 21:24:54 +1100 Subject: [PATCH 03/18] TODO * Converted document from reST to org-mode. --- lang/python/docs/TODO.org | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 lang/python/docs/TODO.org diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org new file mode 100644 index 00000000..8930b800 --- /dev/null +++ b/lang/python/docs/TODO.org @@ -0,0 +1,22 @@ +#+TITLE: Stuff To Do + +* Working examples + :PROPERTIES: + :CUSTOM_ID: working-examples + :END: + +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 + :PROPERTIES: + :CUSTOM_ID: documentation + :END: + +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. From 487ed9337e8e07d1c63e53b785cc39e3bd35ff6e Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 21:25:45 +1100 Subject: [PATCH 04/18] TODO * Removed reST version of file. --- lang/python/docs/TODO.rst | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100644 lang/python/docs/TODO.rst 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. From fccd2ea3871f5d63fb038db0733a34f9c5d550c3 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 22:28:50 +1100 Subject: [PATCH 05/18] TODO * Updated TODO. * The entirety of the old TODO has been replaced with either more relevant tasks or goals for the examples and a more measured approach to the docs and why, in this project, Org Mode trumps reST, even though it's Python through and through. --- lang/python/docs/TODO.org | 59 ++++++++++++++++++++++++++++----------- 1 file changed, 42 insertions(+), 17 deletions(-) diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 8930b800..74b478dc 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,22 +1,47 @@ #+TITLE: Stuff To Do -* Working examples - :PROPERTIES: - :CUSTOM_ID: working-examples - :END: +* TODO -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. +** Working examples + :PROPERTIES: + :CUSTOM_ID: working-examples + :END: -* Documentation - :PROPERTIES: - :CUSTOM_ID: documentation - :END: + The old GUI examples were unable to be retained since they depended + on GTK2 and Python 2's integration with GTK2. -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. + 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 reST 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. Furthermore, there are 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. From a1bc710c5fb7a7d2253434c1443e33e019020a55 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Wed, 14 Feb 2018 22:44:27 +1100 Subject: [PATCH 06/18] History * Reshaping the history file to fit Org Mode's structuring for docs. * Also said history needs to be a bit more clear (it was kind of unfinished). --- lang/python/docs/Short_History.org | 116 ++++++++++++++++------------- 1 file changed, 66 insertions(+), 50 deletions(-) diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org index fa40d6eb..11a87c67 100644 --- a/lang/python/docs/Short_History.org +++ b/lang/python/docs/Short_History.org @@ -1,56 +1,72 @@ -#+TITLE: A Short History of gpg bindings for Python +#+TITLE: A Short History of the GPGME 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 +* Overview :PROPERTIES: - :CUSTOM_ID: the-annoyances-of-git + :CUSTOM_ID: overview :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 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 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. -* The Perils of PyPI - :PROPERTIES: - :CUSTOM_ID: the-perils-of-pypi - :END: +** In the beginning + :PROPERTIES: + :CUSTOM_ID: in-the-begining + :END: -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. + 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. + + 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 + :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 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 + :PROPERTIES: + :CUSTOM_ID: the-perils-of-pypi + :END: + + 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. From 7c662d22a8f7d2e6ad6532014f2ecc1769de16fb Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Thu, 15 Feb 2018 01:03:12 +1100 Subject: [PATCH 07/18] Subsectioned history * Split the main parts down into subsections. * Still need to cull the incorrect stuff towards the end and add more recent changes. --- lang/python/docs/Short_History.org | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org index 11a87c67..2295499c 100644 --- a/lang/python/docs/Short_History.org +++ b/lang/python/docs/Short_History.org @@ -20,12 +20,22 @@ return to the source. This is a short explanation of that journey. 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 @@ -33,6 +43,11 @@ return to the source. This is a short explanation of that journey. 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 From 3c3b149996036e7ff4cc4c77ef2d97062d880409 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Thu, 15 Feb 2018 04:19:15 +1100 Subject: [PATCH 08/18] Short History * Fixed or updated the most fundamental errors. * Also included some details on which modules are available on PyPI, as well as what happened to the PyME commit log. --- lang/python/docs/Short_History.org | 116 ++++++++++++++++++++++++----- 1 file changed, 96 insertions(+), 20 deletions(-) diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org index 2295499c..e0cd877e 100644 --- a/lang/python/docs/Short_History.org +++ b/lang/python/docs/Short_History.org @@ -50,13 +50,30 @@ return to the source. This is a short explanation of that journey. 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. + 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 PyME was renamed to "gpg" and adopted by the upstream GnuPG - team. + 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: @@ -65,23 +82,82 @@ return to the source. This is a short explanation of that journey. 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. + 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: - 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. + 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. From 40da5022922172ed898172956a8ccf5622e5638d Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Thu, 15 Feb 2018 21:28:07 +1100 Subject: [PATCH 09/18] TODO * Beginning to turn the first part of this into something kind of like an actual TODO list as Org Mode uses it (maybe). --- lang/python/docs/TODO.org | 41 ++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 74b478dc..c0ec5562 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,6 +1,33 @@ #+TITLE: Stuff To Do -* TODO +* Project Task List + +** TODO Documentation default format + :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 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. + +* Project Task Details ** Working examples :PROPERTIES: @@ -27,12 +54,12 @@ bindings has been removed. Current and future documentation will adhere to the GnuPG standard - of using Org Mode and not use the reST 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. Furthermore, there are aspects - of Org Mode's publishing features which are superior to the - defaults of reST, including the capacity to generate fully + 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 From 235d899a5fc24cdf9c856adbc021a69c43985c99 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Thu, 15 Feb 2018 21:30:32 +1100 Subject: [PATCH 10/18] TODO Documentation * Checked off the decision to stick with Org Mode. --- lang/python/docs/TODO.org | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index c0ec5562..1ddd394e 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -2,7 +2,8 @@ * Project Task List -** TODO Documentation default format +** DONE Documentation default format + CLOSED: [2018-02-15 Thu 21:29] :PROPERTIES: :CUSTOM_ID: todo-docs-default :END: From 6f15d821404742ac2683f54ca4102ee4aaedacf2 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Fri, 16 Feb 2018 01:26:20 +1100 Subject: [PATCH 11/18] LaTeX margins * Added LaTeX header for 1 inch margins in the quite likely event that all PDF output ultimately uses LaTeX. --- lang/python/docs/Short_History.org | 2 + lang/python/docs/TODO.org | 65 ++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) 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,4 +1,6 @@ #+TITLE: A Short History of the GPGME bindings for Python +#+LATEX_CLASS: article +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} * Overview :PROPERTIES: 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,6 +1,11 @@ #+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] @@ -19,6 +24,25 @@ 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 @@ -28,7 +52,48 @@ 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: From fb16eaa685fe488f12f4df9b59d1f3689c813034 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Fri, 16 Feb 2018 19:15:32 +1100 Subject: [PATCH 12/18] History path * Fixed a typo in a filepath reference. * Moved conjecture regarding the first version of Python used to a footnote. --- lang/python/docs/Short_History.org | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org index 89bb21e1..3ce3480c 100644 --- a/lang/python/docs/Short_History.org +++ b/lang/python/docs/Short_History.org @@ -17,10 +17,10 @@ return to the source. This is a short explanation of that journey. :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. + 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: @@ -89,7 +89,7 @@ SWIG itself, which are worth noting here. 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 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. @@ -161,5 +161,8 @@ SWIG itself, which are worth noting here. * 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. +[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. From fe4f3edd70949329cb992dd963de2de3c86dcd81 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 20 Feb 2018 02:45:44 +1100 Subject: [PATCH 13/18] Schizophrenic file types * Removed Markdown style heading underlining. * Removed in-line file type declaration (which is not correctly parsed by the web interface on dev.gnupg.org). --- lang/python/README | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lang/python/README b/lang/python/README index 6a2e8b8c..9339bf82 100644 --- a/lang/python/README +++ b/lang/python/README @@ -1,5 +1,5 @@ -gpg - GPGME bindings for Python -*- org -*- -======================= +#+TITLE gpg - GPGME bindings for Python + The "gpg" module is a python interface to the GPGME library: https://www.gnupg.org/related_software/gpgme/ From 1ae3ead2cd854258954e784bf51f03822321aefe Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 20 Feb 2018 02:51:02 +1100 Subject: [PATCH 14/18] Conflict with Phabricator files * The developers of Phabricator, the web front-end on dev.gnupg.org have not implemented renderers for Markdown, Org-Mode or any other common markdown like language. * They also refuse to do so. * Instead they re-invented the wheel and implemented their own version of Markdown-like thing which is incompatible with everything else. It is called Remarkup. * The developers of Phabricator and Remarkup have refused to provide conversion tools to move files to/from any format to/from Remarkup. * They expect everyone to learn their new favourite pet project. * Remarkup may or may not display Org Mode files, but if so then it is likely to only want to do so as plain text. * There is an unaffiliated and unofficial project to convert Github Markdown to Remarkup via Pandoc. This might be adapted for our use, but requires testing. * Until then exporting from Org Mode to UTF-8 text is likely the least worst plan. * Which means renaming this file to README.org first. --- lang/python/{README => README.org} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename lang/python/{README => README.org} (100%) diff --git a/lang/python/README b/lang/python/README.org similarity index 100% rename from lang/python/README rename to lang/python/README.org From ea481d4bb9e6197fbc195187d1362b844e2cba2e Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 20 Feb 2018 03:11:02 +1100 Subject: [PATCH 15/18] Title fix * Fixed title. --- lang/python/README.org | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lang/python/README.org b/lang/python/README.org index 9339bf82..22e7d1f8 100644 --- a/lang/python/README.org +++ b/lang/python/README.org @@ -1,4 +1,4 @@ -#+TITLE gpg - GPGME bindings for Python +#+TITLE: gpg - GPGME bindings for Python The "gpg" module is a python interface to the GPGME library: From c82b17c6ce490738efb07186532e752e6f70ea07 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 20 Feb 2018 03:11:50 +1100 Subject: [PATCH 16/18] Text conversion * Exported from Org Mode to UTF-8 text. * Removed my name from just under the title. --- lang/python/README.txt | 77 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 77 insertions(+) create mode 100644 lang/python/README.txt diff --git a/lang/python/README.txt b/lang/python/README.txt new file mode 100644 index 00000000..49e88205 --- /dev/null +++ b/lang/python/README.txt @@ -0,0 +1,77 @@ + ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + 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/] + +"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. + + +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 +══════ + + Please report bugs using our bug tracker using the category 'gpgme', + and topic 'python': [https://bugs.gnupg.org/gnupg/] + + +3 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. + + +4 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] From 272a8e778a959cb24298f488e77fce9bffd23b7a Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Tue, 20 Feb 2018 03:13:42 +1100 Subject: [PATCH 17/18] Renaming ad infinitum ... * Dropped the .txt from the end of the file ... --- lang/python/{README.txt => README} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename lang/python/{README.txt => README} (100%) diff --git a/lang/python/README.txt b/lang/python/README similarity index 100% rename from lang/python/README.txt rename to lang/python/README From 6f2e2e0f150d5c6d53de5bc48af137f7864d5fd9 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Mon, 26 Feb 2018 13:51:23 +1100 Subject: [PATCH 18/18] LaTeX headers * Set LaTeX headers to enable ligatures and a 12pt font by default. * Paper size left for regional defaults. * Using XeLaTeX for easier font control. * Using default LaTeX font of Latin Main, but that's easy enough to change. --- lang/python/docs/Short_History.org | 4 ++++ lang/python/docs/TODO.org | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/lang/python/docs/Short_History.org b/lang/python/docs/Short_History.org index 3ce3480c..f684f0a7 100644 --- a/lang/python/docs/Short_History.org +++ b/lang/python/docs/Short_History.org @@ -1,6 +1,10 @@ #+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: diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org index 10324e60..9f039d81 100644 --- a/lang/python/docs/TODO.org +++ b/lang/python/docs/TODO.org @@ -1,6 +1,10 @@ #+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: