GpgFrontend/gpgme
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'ben/python-docs-01'

Browse Source 
* Documentation and the first brush strokes towards the future.

Signed-off-by: Ben McGinnes <ben@adversary.org>
This commit is contained in:
Ben McGinnes 2018-02-26 14:04:23 +11:00
commit 8da63fdee5
6 changed files with 432 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
lang/python/README
View File

@ -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 development see the gnupg-devel mailing list:
https://lists.gnupg.org/mailman/listinfo/gnupg-devel
For general discussion and help see the gnupg-users mailing list:
[https://lists.gnupg.org/mailman/listinfo/gnupg-users]
* 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/
* Authors
2 Bugs
══════
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.
Please report bugs using our bug tracker using the category 'gpgme',
and topic 'python': [https://bugs.gnupg.org/gnupg/]
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.
3 Authors
═════════
* History
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.
- The python bindings were renamed from PyME to "gpg" in 2016.
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.
- The bindings have been merged into the GPGME repository in 2016.
Please see the section 'History' further down this document for
references to previous versions.
- 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
4 History
═════════
- A previous version of PyME v0.8.0 can be found on sourceforge:
http://pyme.sourceforge.net/
• The python bindings were renamed from PyME to "gpg" in 2016.
- 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
• 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]

61
lang/python/README.org Normal file
View File

@ -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

172
lang/python/docs/Short_History.org Normal file
View File

@ -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.

57
lang/python/docs/Short_History.rst
View File

@ -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.

144
lang/python/docs/TODO.org Normal file
View File

@ -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.

23
lang/python/docs/TODO.rst
View File

@ -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.