python: doc: Remove generated files, put rules in Makefile.
* lang/python/doc/Makefile.am (EXTRA_DIST): Remove files not distributed like files under meta. * Add rules to generate .rst and .texi files. * lang/python/doc/rst: Remove .rst files to be generated. * lang/python/doc/texinfo: Remove .texi files to be generated. GnuPG-bug-id: 4275 Signed-off-by: NIIBE Yutaka <gniibe@fsij.org>
This commit is contained in:
NIIBE Yutaka
parent
d9387650ff
commit
36428d8cf1
@ -17,32 +17,56 @@
|
|||||||
# License along with this program; if not, see <https://gnu.org/licenses/>.
|
# License along with this program; if not, see <https://gnu.org/licenses/>.
|
||||||
# SPDX-License-Identifier: LGPL-2.1-or-later
|
# SPDX-License-Identifier: LGPL-2.1-or-later
|
||||||
|
|
||||||
# Created by:
|
EXTRA_DIST = README \
|
||||||
# find . -type f -print | sed 's/^.\// /;$q;s/$/ \\/' | sort
|
|
||||||
EXTRA_DIST = texinfo/what-was-new.texi \
|
|
||||||
meta/old-commits.log \
|
|
||||||
meta/TODO.org \
|
|
||||||
README \
|
|
||||||
rst/_build/README \
|
rst/_build/README \
|
||||||
|
rst/_static/README \
|
||||||
|
rst/_templates/README \
|
||||||
rst/conf.py \
|
rst/conf.py \
|
||||||
rst/gpgme-python-howto.rst \
|
rst/gpgme-python-howto.rst \
|
||||||
rst/index.rst \
|
rst/index.rst \
|
||||||
rst/maintenance-mode.rst \
|
rst/maintenance-mode.rst \
|
||||||
rst/short-history.rst \
|
rst/short-history.rst \
|
||||||
rst/_static/README \
|
|
||||||
rst/_templates/README \
|
|
||||||
rst/what-is-new.rst \
|
rst/what-is-new.rst \
|
||||||
rst/what-was-new.rst \
|
rst/what-was-new.rst \
|
||||||
src/gpgme-python-howto \
|
src/gpgme-python-howto.org \
|
||||||
src/index \
|
src/index.org \
|
||||||
src/maintenance-mode \
|
src/maintenance-mode.org \
|
||||||
src/short-history \
|
src/short-history.org \
|
||||||
src/what-is-new \
|
src/what-is-new.org \
|
||||||
src/what-was-new \
|
src/what-was-new.org \
|
||||||
|
texinfo/texinfo.tex \
|
||||||
texinfo/gpgme-python-howto.texi \
|
texinfo/gpgme-python-howto.texi \
|
||||||
texinfo/index.texi \
|
texinfo/index.texi \
|
||||||
texinfo/maintenance-mode.texi \
|
texinfo/maintenance-mode.texi \
|
||||||
texinfo/short-history.texi \
|
texinfo/short-history.texi \
|
||||||
texinfo/texinfo.tex \
|
|
||||||
texinfo/what-is-new.texi \
|
texinfo/what-is-new.texi \
|
||||||
texinfo/what-was-new.texi
|
texinfo/what-was-new.texi
|
||||||
|
|
||||||
|
if MAINTAINER_MODE
|
||||||
|
dist-hook: the_doc_dirs $(RST_GENERATED) $(TEXI_GENERATED)
|
||||||
|
cp $(RST_GENERATED) rst/
|
||||||
|
cp $(TEXI_GENERATED) texinfo/
|
||||||
|
|
||||||
|
.org.rst:
|
||||||
|
pandoc -f org -t rst $< -o $@
|
||||||
|
|
||||||
|
.org.texi:
|
||||||
|
pandoc -f org -t texinfo $< -o $@
|
||||||
|
|
||||||
|
RST_GENERATED = src/gpgme-python-howto.rst src/index.rst \
|
||||||
|
src/maintenance-mode.rst src/short-history.rst src/what-is-new.rst \
|
||||||
|
src/what-was-new.rst
|
||||||
|
|
||||||
|
TEXI_GENERATED = src/gpgme-python-howto.texi src/index.texi \
|
||||||
|
src/maintenance-mode.texi src/short-history.texi src/what-is-new.texi \
|
||||||
|
src/what-was-new.texi
|
||||||
|
|
||||||
|
# make 'src', 'rst' and 'texinfo' dir in build directory
|
||||||
|
.PHONY: the_doc_dirs
|
||||||
|
the_doc_dirs:
|
||||||
|
if test ! -d src; then $(MKDIR_P) src; fi
|
||||||
|
if test ! -d rst; then $(MKDIR_P) rst; fi
|
||||||
|
if test ! -d texinfo; then $(MKDIR_P) texinfo; fi
|
||||||
|
endif
|
||||||
|
|
||||||
|
MAINTAINERCLEANFILES = $(RST_GENERATED) $(TEXI_GENERATED)
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@ -1,22 +0,0 @@
|
|||||||
.. GPGME Python Bindings documentation master file, created by
|
|
||||||
sphinx-quickstart on Wed Dec 5 09:04:47 2018.
|
|
||||||
You can adapt this file completely to your liking, but it should at least
|
|
||||||
contain the root `toctree` directive.
|
|
||||||
|
|
||||||
GPGME Python Bindings
|
|
||||||
=====================
|
|
||||||
|
|
||||||
.. toctree::
|
|
||||||
:maxdepth: 3
|
|
||||||
:caption: Contents:
|
|
||||||
|
|
||||||
Contents
|
|
||||||
--------
|
|
||||||
|
|
||||||
- `A short history of the project <short-history>`__
|
|
||||||
- `What\'s New <what-is-new>`__
|
|
||||||
|
|
||||||
- `Maintenance Mode <maintenance-mode>`__ (from January, 2019)
|
|
||||||
|
|
||||||
- `What Was New <what-was-new>`__
|
|
||||||
- `GPGME Python Bindings HOWTO <gpgme-python-howto>`__
|
|
||||||
@ -1,133 +0,0 @@
|
|||||||
.. _maintenance-mode:
|
|
||||||
|
|
||||||
Maintenance Mode from 2019
|
|
||||||
==========================
|
|
||||||
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Version: | 0.0.1 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| GPGME Version: | 1.13.0 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author: | Ben McGinnes <ben@gnupg.org> |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Language: | Australian English, British English |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| xml:lang: | en-AU, en-GB, en |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
|
|
||||||
From the beginning of 2019 the Python bindings to GPGME will enter
|
|
||||||
maintenance mode, meaning that new features will not be added and only
|
|
||||||
bug fixes and security fixes will be made. This also means that
|
|
||||||
documentation beyond that existing at the end of 2018 will not be
|
|
||||||
developed further except to correct errors.
|
|
||||||
|
|
||||||
Though use of these bindings appears to have been quite well received,
|
|
||||||
there has been no indication of what demand there is, if any for either
|
|
||||||
financial backing of the current Python bindings development or support
|
|
||||||
contracts with g10code GmbH citing the necessity of including the
|
|
||||||
bindings.
|
|
||||||
|
|
||||||
.. _maintenance-mode-bm:
|
|
||||||
|
|
||||||
Maintainer from 2019 onward
|
|
||||||
---------------------------
|
|
||||||
|
|
||||||
How does this affect the position of GnuPG Python Bindings Maintainer?
|
|
||||||
|
|
||||||
Well, I will remain as maintainer of the bindings; but without funding
|
|
||||||
for that position, the amount of time I will be able to dedicate solely
|
|
||||||
to this task will be limited and reduced to volunteered time. As with
|
|
||||||
all volunteered time and effort in free software projects, this will be
|
|
||||||
subject to numerous external imperatives.
|
|
||||||
|
|
||||||
.. _maintenance-mode-blade-runner:
|
|
||||||
|
|
||||||
Using the Python Bindings from 2019 and beyond
|
|
||||||
----------------------------------------------
|
|
||||||
|
|
||||||
For most, if not all, Python developers using these bindings; they will
|
|
||||||
continue to "just work" the same as they always have. Expansions of
|
|
||||||
GPGME itself are usually handled by SWIG with the existing code and thus
|
|
||||||
bindings are generated properly when the bindings are installed
|
|
||||||
alongside GPGME and when the latter is built from source.
|
|
||||||
|
|
||||||
In the rare circumstances where that is not enough to address some new
|
|
||||||
addition to GPGME, then that is a bug and thus subject to the
|
|
||||||
maintenance mode provisions (i.e. it will be fixed following a bug
|
|
||||||
report being raised and your humble author will need to remember where
|
|
||||||
the timesheet template was filed, depending on how many years off such
|
|
||||||
an event is).
|
|
||||||
|
|
||||||
All the GPGME functionality will continue to be accessible via the lower
|
|
||||||
level, dynamically generated methods which match the GPGME C
|
|
||||||
documentation. While the more intuitively Pythonic higher level layer
|
|
||||||
already covers the vast majority of functionality people require with
|
|
||||||
key generation, signatures, certifications (key signing), encryption,
|
|
||||||
decryption, verification, validation, trust levels and so on.
|
|
||||||
|
|
||||||
Any wanted features lacking in the Python bindings are usually lacking
|
|
||||||
because they are missing from GPGME itself (e.g. revoking keys via the
|
|
||||||
API) and in such cases they are usually deliberately excluded. More
|
|
||||||
discussion of these issues can be found in the archives of the
|
|
||||||
`gnupg-devel mailing
|
|
||||||
list <https://lists.gnupg.org/mailman/listinfo/gnupg-devel>`__.
|
|
||||||
|
|
||||||
Any features existing in the dynamically generated layer for which
|
|
||||||
people want a specific, higher level function included to make it more
|
|
||||||
Pythonic (e.g. to avoid needing to learn or memorise cryptographic mode
|
|
||||||
values or GnuPG status code numbers), would be a feature request and
|
|
||||||
*not* a bug.
|
|
||||||
|
|
||||||
It is still worthwhile requesting it, but the addition of such a feature
|
|
||||||
would not be guaranteed and provided on a purely volunteer basis.
|
|
||||||
Expediting such a request would require funding that request.
|
|
||||||
|
|
||||||
Those with a commercial interest in expediting such a feature request
|
|
||||||
already know how to `expedite
|
|
||||||
it <https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset>`__ (use the
|
|
||||||
message field to state what feature is being requested).
|
|
||||||
|
|
||||||
.. _docs:
|
|
||||||
|
|
||||||
Documentation formats
|
|
||||||
---------------------
|
|
||||||
|
|
||||||
The documentation has been written in Org mode for GNU Emacs, with both
|
|
||||||
Texinfo and reStructuredText formats generated from that. The Texinfo
|
|
||||||
files are intended for use with the rest of the GnuPG documentation;
|
|
||||||
while the reStructuredText files are intended for use with Docutils and
|
|
||||||
Sphinx, as with other Python projects.
|
|
||||||
|
|
||||||
.. _sphinx-made-epubs-suck:
|
|
||||||
|
|
||||||
Cautionary Notes regarding Sphinx and EPUB
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Though Python\'s Docutils in conjunction with Sphinx is capable of
|
|
||||||
generating some very useful HTML sites, as proven by `Read the
|
|
||||||
Docs <https://readthedocs.org/>`__ and the `Python
|
|
||||||
documentation <https://docs.python.org/>`__, there are a number of
|
|
||||||
output formats it does not handle well. At the top of the list of things
|
|
||||||
it manages to break so atrociously as to be embarassing is the `EPUB
|
|
||||||
3 <http://idpf.org/epub>`__ format.
|
|
||||||
|
|
||||||
The automatically generated EPUB of the CPython documentation always
|
|
||||||
contains hundreds of validation errors and even the modest amount of
|
|
||||||
documentation here `produced a
|
|
||||||
file <https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub>`__
|
|
||||||
with approximately thirty validation errors. As the volume of
|
|
||||||
documentation content increases, so does the induced errors. Whereas
|
|
||||||
Texinfo doesn\'t produce EPUB output at all, nor does Org-mode.
|
|
||||||
|
|
||||||
Should there ever be genuine demand for this format, lodge a `feature
|
|
||||||
request <https://dev.gnupg.org/maniphest/task/edit/form/4/>`__ case
|
|
||||||
marked for `my <https://dev.gnupg.org/p/BenM/>`__ attention. The means
|
|
||||||
of generating such files flawlessly is already available, but is not yet
|
|
||||||
part of the GnuPG build system. Nor is it integrated with a means of
|
|
||||||
converting Org mode input files to the relevant base format
|
|
||||||
automatically, as can already be done when converting Org to
|
|
||||||
reStructuredText or Org to Texinfo. As a certain amount of work would be
|
|
||||||
required to get it done, there would need to be clear demand for that
|
|
||||||
work to be done.
|
|
||||||
@ -1,166 +0,0 @@
|
|||||||
Overview
|
|
||||||
========
|
|
||||||
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Version: | 0.0.1 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| GPGME Version: | 1.13.0 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author: | Ben McGinnes <ben@gnupg.org> |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Language: | Australian English, British English |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| xml:lang: | en-AU, en-GB, en |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
|
|
||||||
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-begining:
|
|
||||||
|
|
||||||
In the beginning
|
|
||||||
----------------
|
|
||||||
|
|
||||||
In 2002 John Goerzen released PyME; Python bindings for the GPGME module
|
|
||||||
which utilised the current release of Python of the time and SWIG. [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
|
|
||||||
-----------------------
|
|
||||||
|
|
||||||
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
|
|
||||||
-----------------
|
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
.. _ouroboros:
|
|
||||||
|
|
||||||
Coming full circle
|
|
||||||
------------------
|
|
||||||
|
|
||||||
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-past:
|
|
||||||
|
|
||||||
Relics of the past
|
|
||||||
==================
|
|
||||||
|
|
||||||
There are a few things, in addition to code specific factors, such as
|
|
||||||
SWIG itself, which are worth noting here.
|
|
||||||
|
|
||||||
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 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. [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
|
|
||||||
------------------
|
|
||||||
|
|
||||||
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:
|
|
||||||
|
|
||||||
#. gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
|
|
||||||
#. pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
|
|
||||||
|
|
||||||
.. _pypi-gpgme-180:
|
|
||||||
|
|
||||||
GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
.. _pypi-gpgme-90:
|
|
||||||
|
|
||||||
PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
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
|
|
||||||
=========
|
|
||||||
|
|
||||||
.. [1]
|
|
||||||
In all likelihood this would have been Python 2.2 or possibly Python
|
|
||||||
2.3.
|
|
||||||
|
|
||||||
.. [2]
|
|
||||||
The entire PyME git log and other preceding VCS logs are located in
|
|
||||||
the ``gpgme/lang/python/docs/old-commits.log`` file.
|
|
||||||
@ -1,50 +0,0 @@
|
|||||||
.. _new-stuff:
|
|
||||||
|
|
||||||
What\'s New
|
|
||||||
===========
|
|
||||||
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Version: | 0.0.1 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| GPGME Version: | 1.13.0 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author: | Ben McGinnes <ben@gnupg.org> |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Language: | Australian English, British English |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| xml:lang: | en-AU, en-GB, en |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
|
|
||||||
Last time the most obviously new thing was adding the *What\'s New*
|
|
||||||
section to the HOWTO. Now it\'s moving it out of the HOWTO.
|
|
||||||
|
|
||||||
.. _new-stuff-1-13-0:
|
|
||||||
|
|
||||||
New in GPGME 1·13·0
|
|
||||||
-------------------
|
|
||||||
|
|
||||||
Additions since GPGME 1.12.0 include:
|
|
||||||
|
|
||||||
- Moving the *What\'s New* section out of the basic
|
|
||||||
`HOWTO <gpgme-python-howto.org>`__ document and into its own file so
|
|
||||||
as to more readily include other documents beyond that HOWTO.
|
|
||||||
- Moving the preceding, archival, segments into `another
|
|
||||||
file <what-was-new.org>`__.
|
|
||||||
- Added ``gpg.version.versionintlist`` to make it easier for Python
|
|
||||||
developers to check for a specific version number, even with beta
|
|
||||||
versions (it will drop the \"-betaN\" part).
|
|
||||||
- Added expanded detail on issues pertaining to installing for Windows
|
|
||||||
users.
|
|
||||||
- Bindings enter `maintenance mode <maintenance-mode>`__ from January,
|
|
||||||
2019.
|
|
||||||
- Added documentation on maintenance mode and what changes can be made
|
|
||||||
to the code when in that status. Essentially that boils down to bug
|
|
||||||
fixes only and no feature requests.
|
|
||||||
- The import-keys-hkp.py example script, which uses the ``hkp4py``
|
|
||||||
module to search the SKS servers for a key, has been tightened up to
|
|
||||||
search for both hexadecimal key IDs and user ID strings with reduced
|
|
||||||
chance of unnecessary repitition. There may still be some repetition
|
|
||||||
if a key includes a user ID matching the hexadecimal value of a key
|
|
||||||
ID.
|
|
||||||
@ -1,111 +0,0 @@
|
|||||||
.. _new-stuff:
|
|
||||||
|
|
||||||
What Was New
|
|
||||||
============
|
|
||||||
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Version: | 0.0.1 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| GPGME Version: | 1.13.0 |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author: | Ben McGinnes <ben@gnupg.org> |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| Language: | Australian English, British English |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
| xml:lang: | en-AU, en-GB, en |
|
|
||||||
+-----------------+------------------------------------------+
|
|
||||||
|
|
||||||
The following are all the past *What\'s New* sections for the Python
|
|
||||||
Bindings HOWTO and other documentation.
|
|
||||||
|
|
||||||
.. _gpgme-1-12-0:
|
|
||||||
|
|
||||||
What Was New in GPGME 1·12·0
|
|
||||||
----------------------------
|
|
||||||
|
|
||||||
The most obviously new point for those reading this guide is this
|
|
||||||
section on other new things, but that's hardly important. Not given all
|
|
||||||
the other things which spurred the need for adding this section and its
|
|
||||||
subsections.
|
|
||||||
|
|
||||||
.. _new-stuff-1-12-0:
|
|
||||||
|
|
||||||
New in GPGME 1·12·0
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
There have been quite a number of additions to GPGME and the Python
|
|
||||||
bindings to it since the last release of GPGME with versions 1.11.0 and
|
|
||||||
1.11.1 in April, 2018.
|
|
||||||
|
|
||||||
The bullet points of new additiions are:
|
|
||||||
|
|
||||||
- an expanded section on
|
|
||||||
`installing <gpgme-python-howto#installation>`__ and
|
|
||||||
`troubleshooting <gpgme-python-howto#snafu>`__ the Python bindings.
|
|
||||||
- The release of Python 3.7.0; which appears to be working just fine
|
|
||||||
with our bindings, in spite of intermittent reports of problems for
|
|
||||||
many other Python projects with that new release.
|
|
||||||
- Python 3.7 has been moved to the head of the specified python
|
|
||||||
versions list in the build process.
|
|
||||||
- In order to fix some other issues, there are certain underlying
|
|
||||||
functions which are more exposed through the
|
|
||||||
`gpg.Context() <gpgme-python-howto#howto-get-context>`__, but ongoing
|
|
||||||
documentation ought to clarify that or otherwise provide the best
|
|
||||||
means of using the bindings. Some additions to ``gpg.core`` and the
|
|
||||||
``Context()``, however, were intended (see below).
|
|
||||||
- Continuing work in identifying and confirming the cause of
|
|
||||||
oft-reported `problems installing the Python bindings on
|
|
||||||
Windows <gpgme-python-howto#snafu-runtime-not-funtime>`__.
|
|
||||||
- GSOC: Google\'s Surreptitiously Ordered Conscription ... erm ... oh,
|
|
||||||
right; Google\'s Summer of Code. Though there were two hopeful
|
|
||||||
candidates this year; only one ended up involved with the GnuPG
|
|
||||||
Project directly, the other concentrated on an unrelated third party
|
|
||||||
project with closer ties to one of the GNU/Linux distributions than
|
|
||||||
to the GnuPG Project. Thus the Python bindings benefited from GSOC
|
|
||||||
participant Jacob Adams, who added the key\ :sub:`import` function;
|
|
||||||
building on prior work by Tobias Mueller.
|
|
||||||
- Several new methods functions were added to the gpg.Context(),
|
|
||||||
including: `key\ import <gpgme-python-howto#howto-import-key>`__,
|
|
||||||
`key\ export <gpgme-python-howto#howto-export-key>`__,
|
|
||||||
`key\ exportminimal <gpgme-python-howto#howto-export-public-key>`__
|
|
||||||
and
|
|
||||||
`key\ exportsecret <gpgme-python-howto#howto-export-secret-key>`__.
|
|
||||||
- Importing and exporting examples include versions integrated with
|
|
||||||
Marcel Fest\'s recently released `HKP for
|
|
||||||
Python <https://github.com/Selfnet/hkp4py>`__ module. Some
|
|
||||||
`additional notes on this module <gpgme-python-howto#hkp4py>`__ are
|
|
||||||
included at the end of the HOWTO.
|
|
||||||
- Instructions for dealing with semi-walled garden implementations like
|
|
||||||
ProtonMail are also included. This is intended to make things a
|
|
||||||
little easier when communicating with users of ProtonMail\'s services
|
|
||||||
and should not be construed as an endorsement of said service. The
|
|
||||||
GnuPG Project neither favours, nor disfavours ProtonMail and the
|
|
||||||
majority of this deals with interacting with the ProtonMail
|
|
||||||
keyserver.
|
|
||||||
- Semi-formalised the location where `draft
|
|
||||||
versions <gpgme-python-howto#draft-editions>`__ of this HOWTO may
|
|
||||||
periodically be accessible. This is both for the reference of others
|
|
||||||
and testing the publishing of the document itself. Renamed this file
|
|
||||||
at around the same time.
|
|
||||||
- The Texinfo documentation build configuration has been replicated
|
|
||||||
from the parent project in order to make to maintain consistency with
|
|
||||||
that project (and actually ship with each release).
|
|
||||||
- a reStructuredText (``.rst``) version is also generated for Python
|
|
||||||
developers more used to and comfortable with that format as it is the
|
|
||||||
standard Python documentation format and Python developers may wish
|
|
||||||
to use it with Sphinx. Please note that there has been no testing of
|
|
||||||
the reStructuredText version with Sphinx at all. The reST file was
|
|
||||||
generated by the simple expedient of using
|
|
||||||
`Pandoc <https://pandoc.org/>`__.
|
|
||||||
- Added a new section for `advanced or experimental
|
|
||||||
use <gpgme-python-howto#advanced-use>`__.
|
|
||||||
- Began the advanced use cases with `a
|
|
||||||
section <gpgme-python-howto#cython>`__ on using the module with
|
|
||||||
`Cython <https://cython.org/>`__.
|
|
||||||
- Added a number of new scripts to the ``example/howto/`` directory;
|
|
||||||
some of which may be in advance of their planned sections of the
|
|
||||||
HOWTO (and some are just there because it seemed like a good idea at
|
|
||||||
the time).
|
|
||||||
- Cleaned up a lot of things under the hood.
|
|
||||||
File diff suppressed because it is too large
Load Diff
@ -1,60 +0,0 @@
|
|||||||
\input texinfo @c -*- texinfo -*-
|
|
||||||
@c %**start of header
|
|
||||||
@setfilename index.info
|
|
||||||
@settitle GNU Privacy Guard (GnuPG) Made Easy Python Bindings
|
|
||||||
@documentencoding utf-8
|
|
||||||
@documentlanguage en
|
|
||||||
@c %**end of header
|
|
||||||
|
|
||||||
@finalout
|
|
||||||
@titlepage
|
|
||||||
@title GNU Privacy Guard (GnuPG) Made Easy Python Bindings
|
|
||||||
@author Ben McGinnes
|
|
||||||
@end titlepage
|
|
||||||
|
|
||||||
@contents
|
|
||||||
|
|
||||||
@ifnottex
|
|
||||||
@node Top
|
|
||||||
@top GNU Privacy Guard (GnuPG) Made Easy Python Bindings
|
|
||||||
@end ifnottex
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* GPGME Python Bindings::
|
|
||||||
|
|
||||||
@detailmenu
|
|
||||||
--- The Detailed Node Listing ---
|
|
||||||
|
|
||||||
GPGME Python Bindings
|
|
||||||
|
|
||||||
* Contents::
|
|
||||||
|
|
||||||
@end detailmenu
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node GPGME Python Bindings
|
|
||||||
@chapter GPGME Python Bindings
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* Contents::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node Contents
|
|
||||||
@section Contents
|
|
||||||
|
|
||||||
@itemize
|
|
||||||
@item
|
|
||||||
@uref{short-history, A short history of the project}
|
|
||||||
@item
|
|
||||||
@uref{what-is-new, What's New}
|
|
||||||
@itemize
|
|
||||||
@item
|
|
||||||
@uref{maintenance-mode, Maintenance Mode} (from January, 2019)
|
|
||||||
@end itemize
|
|
||||||
@item
|
|
||||||
@uref{what-was-new, What Was New}
|
|
||||||
@item
|
|
||||||
@uref{gpgme-python-howto, GPGME Python Bindings HOWTO}
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@bye
|
|
||||||
@ -1,169 +0,0 @@
|
|||||||
\input texinfo @c -*- texinfo -*-
|
|
||||||
@c %**start of header
|
|
||||||
@setfilename maintenance-mode.info
|
|
||||||
@settitle Maintenance Mode
|
|
||||||
@documentencoding utf-8
|
|
||||||
@documentlanguage en
|
|
||||||
@c %**end of header
|
|
||||||
|
|
||||||
@finalout
|
|
||||||
@titlepage
|
|
||||||
@title Maintenance Mode
|
|
||||||
@author Ben McGinnes
|
|
||||||
@end titlepage
|
|
||||||
|
|
||||||
@contents
|
|
||||||
|
|
||||||
@ifnottex
|
|
||||||
@node Top
|
|
||||||
@top Maintenance Mode
|
|
||||||
@end ifnottex
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* Maintenance Mode from 2019::
|
|
||||||
|
|
||||||
@detailmenu
|
|
||||||
--- The Detailed Node Listing ---
|
|
||||||
|
|
||||||
Maintenance Mode from 2019
|
|
||||||
|
|
||||||
* Maintainer from 2019 onward::
|
|
||||||
* Using the Python Bindings from 2019 and beyond::
|
|
||||||
* Documentation formats::
|
|
||||||
|
|
||||||
Documentation formats
|
|
||||||
|
|
||||||
* Cautionary Notes regarding Sphinx and EPUB::
|
|
||||||
|
|
||||||
@end detailmenu
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node Maintenance Mode from 2019
|
|
||||||
@chapter Maintenance Mode from 2019
|
|
||||||
|
|
||||||
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
||||||
@item Version:
|
|
||||||
@tab 0.0.1
|
|
||||||
@item GPGME Version:
|
|
||||||
@tab 1.13.0
|
|
||||||
@item Author:
|
|
||||||
@tab Ben McGinnes <ben@@gnupg.org>
|
|
||||||
@item Author GPG Key:
|
|
||||||
@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
|
|
||||||
@item Language:
|
|
||||||
@tab Australian English, British English
|
|
||||||
@item xml:lang:
|
|
||||||
@tab en-AU, en-GB, en
|
|
||||||
@end multitable
|
|
||||||
|
|
||||||
From the beginning of 2019 the Python bindings to GPGME will enter
|
|
||||||
maintenance mode, meaning that new features will not be added and only
|
|
||||||
bug fixes and security fixes will be made. This also means that
|
|
||||||
documentation beyond that existing at the end of 2018 will not be
|
|
||||||
developed further except to correct errors.
|
|
||||||
|
|
||||||
Though use of these bindings appears to have been quite well received,
|
|
||||||
there has been no indication of what demand there is, if any for
|
|
||||||
either financial backing of the current Python bindings development or
|
|
||||||
support contracts with g10code GmbH citing the necessity of including
|
|
||||||
the bindings.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* Maintainer from 2019 onward::
|
|
||||||
* Using the Python Bindings from 2019 and beyond::
|
|
||||||
* Documentation formats::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node Maintainer from 2019 onward
|
|
||||||
@section Maintainer from 2019 onward
|
|
||||||
|
|
||||||
How does this affect the position of GnuPG Python Bindings Maintainer?
|
|
||||||
|
|
||||||
Well, I will remain as maintainer of the bindings; but without funding
|
|
||||||
for that position, the amount of time I will be able to dedicate
|
|
||||||
solely to this task will be limited and reduced to volunteered time.
|
|
||||||
As with all volunteered time and effort in free software projects,
|
|
||||||
this will be subject to numerous external imperatives.
|
|
||||||
|
|
||||||
@node Using the Python Bindings from 2019 and beyond
|
|
||||||
@section Using the Python Bindings from 2019 and beyond
|
|
||||||
|
|
||||||
For most, if not all, Python developers using these bindings; they
|
|
||||||
will continue to “just work” the same as they always have. Expansions
|
|
||||||
of GPGME itself are usually handled by SWIG with the existing code and
|
|
||||||
thus bindings are generated properly when the bindings are installed
|
|
||||||
alongside GPGME and when the latter is built from source.
|
|
||||||
|
|
||||||
In the rare circumstances where that is not enough to address some new
|
|
||||||
addition to GPGME, then that is a bug and thus subject to the
|
|
||||||
maintenance mode provisions (i.e. it will be fixed following a bug
|
|
||||||
report being raised and your humble author will need to remember where
|
|
||||||
the timesheet template was filed, depending on how many years off such
|
|
||||||
an event is).
|
|
||||||
|
|
||||||
All the GPGME functionality will continue to be accessible via the
|
|
||||||
lower level, dynamically generated methods which match the GPGME C
|
|
||||||
documentation. While the more intuitively Pythonic higher level layer
|
|
||||||
already covers the vast majority of functionality people require with
|
|
||||||
key generation, signatures, certifications (key signing), encryption,
|
|
||||||
decryption, verification, validation, trust levels and so on.
|
|
||||||
|
|
||||||
Any wanted features lacking in the Python bindings are usually lacking
|
|
||||||
because they are missing from GPGME itself (e.g. revoking keys via the
|
|
||||||
API) and in such cases they are usually deliberately excluded. More
|
|
||||||
discussion of these issues can be found in the archives of the
|
|
||||||
@uref{https://lists.gnupg.org/mailman/listinfo/gnupg-devel, gnupg-devel mailing list}.
|
|
||||||
|
|
||||||
Any features existing in the dynamically generated layer for which
|
|
||||||
people want a specific, higher level function included to make it more
|
|
||||||
Pythonic (e.g. to avoid needing to learn or memorise cryptographic
|
|
||||||
mode values or GnuPG status code numbers), would be a feature request
|
|
||||||
and @emph{not} a bug.
|
|
||||||
|
|
||||||
It is still worthwhile requesting it, but the addition of such a
|
|
||||||
feature would not be guaranteed and provided on a purely volunteer
|
|
||||||
basis. Expediting such a request would require funding that request.
|
|
||||||
|
|
||||||
Those with a commercial interest in expediting such a feature request
|
|
||||||
already know how to @uref{https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset, expedite it} (use the message field to state what
|
|
||||||
feature is being requested).
|
|
||||||
|
|
||||||
@node Documentation formats
|
|
||||||
@section Documentation formats
|
|
||||||
|
|
||||||
The documentation has been written in Org mode for GNU Emacs, with
|
|
||||||
both Texinfo and reStructuredText formats generated from that. The
|
|
||||||
Texinfo files are intended for use with the rest of the GnuPG
|
|
||||||
documentation; while the reStructuredText files are intended for use
|
|
||||||
with Docutils and Sphinx, as with other Python projects.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* Cautionary Notes regarding Sphinx and EPUB::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node Cautionary Notes regarding Sphinx and EPUB
|
|
||||||
@subsection Cautionary Notes regarding Sphinx and EPUB
|
|
||||||
|
|
||||||
Though Python's Docutils in conjunction with Sphinx is capable of
|
|
||||||
generating some very useful HTML sites, as proven by @uref{https://readthedocs.org/, Read the Docs} and
|
|
||||||
the @uref{https://docs.python.org/, Python documentation}, there are a number of output formats it does
|
|
||||||
not handle well. At the top of the list of things it manages to break
|
|
||||||
so atrociously as to be embarassing is the @uref{http://idpf.org/epub, EPUB 3} format.
|
|
||||||
|
|
||||||
The automatically generated EPUB of the CPython documentation always
|
|
||||||
contains hundreds of validation errors and even the modest amount of
|
|
||||||
documentation here @uref{https://files.au.adversary.org.s3.amazonaws.com/crypto/gpgme-python/rst/epub/GPGMEPythonBindings.epub, produced a file} with approximately thirty
|
|
||||||
validation errors. As the volume of documentation content increases,
|
|
||||||
so does the induced errors. Whereas Texinfo doesn't produce EPUB
|
|
||||||
output at all, nor does Org-mode.
|
|
||||||
|
|
||||||
Should there ever be genuine demand for this format, lodge a @uref{https://dev.gnupg.org/maniphest/task/edit/form/4/, feature
|
|
||||||
request} case marked for @uref{https://dev.gnupg.org/p/BenM/, my} attention. The means of generating such
|
|
||||||
files flawlessly is already available, but is not yet part of the
|
|
||||||
GnuPG build system. Nor is it integrated with a means of converting
|
|
||||||
Org mode input files to the relevant base format automatically, as can
|
|
||||||
already be done when converting Org to reStructuredText or Org to
|
|
||||||
Texinfo. As a certain amount of work would be required to get it
|
|
||||||
done, there would need to be clear demand for that work to be done.
|
|
||||||
|
|
||||||
@bye
|
|
||||||
@ -1,224 +0,0 @@
|
|||||||
\input texinfo @c -*- texinfo -*-
|
|
||||||
@c %**start of header
|
|
||||||
@setfilename short-history.info
|
|
||||||
@settitle A Short History of the GPGME bindings for Python
|
|
||||||
@documentencoding utf-8
|
|
||||||
@documentlanguage en
|
|
||||||
@c %**end of header
|
|
||||||
|
|
||||||
@finalout
|
|
||||||
@titlepage
|
|
||||||
@title A Short History of the GPGME bindings for Python
|
|
||||||
@author Ben McGinnes
|
|
||||||
@end titlepage
|
|
||||||
|
|
||||||
@contents
|
|
||||||
|
|
||||||
@ifnottex
|
|
||||||
@node Top
|
|
||||||
@top A Short History of the GPGME bindings for Python
|
|
||||||
@end ifnottex
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* Overview::
|
|
||||||
* Relics of the past::
|
|
||||||
|
|
||||||
@detailmenu
|
|
||||||
--- The Detailed Node Listing ---
|
|
||||||
|
|
||||||
Overview
|
|
||||||
|
|
||||||
* In the beginning::
|
|
||||||
* Keeping the flame alive::
|
|
||||||
* Passing the torch::
|
|
||||||
* Coming full circle::
|
|
||||||
|
|
||||||
Relics of the past
|
|
||||||
|
|
||||||
* The Annoyances of Git::
|
|
||||||
* The Perils of PyPI::
|
|
||||||
|
|
||||||
The Perils of PyPI
|
|
||||||
|
|
||||||
* GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library::
|
|
||||||
* PyME 0·9·0 - Python support for GPGME GnuPG cryptography library::
|
|
||||||
|
|
||||||
@end detailmenu
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node Overview
|
|
||||||
@chapter Overview
|
|
||||||
|
|
||||||
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
||||||
@item Version:
|
|
||||||
@tab 0.0.1
|
|
||||||
@item GPGME Version:
|
|
||||||
@tab 1.13.0
|
|
||||||
@item Author:
|
|
||||||
@tab Ben McGinnes <ben@@gnupg.org>
|
|
||||||
@item Author GPG Key:
|
|
||||||
@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
|
|
||||||
@item Language:
|
|
||||||
@tab Australian English, British English
|
|
||||||
@item xml:lang:
|
|
||||||
@tab en-AU, en-GB, en
|
|
||||||
@end multitable
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* In the beginning::
|
|
||||||
* Keeping the flame alive::
|
|
||||||
* Passing the torch::
|
|
||||||
* Coming full circle::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node In the beginning
|
|
||||||
@section In the beginning
|
|
||||||
|
|
||||||
In 2002 John Goerzen released PyME; Python bindings for the GPGME
|
|
||||||
module which utilised the current release of Python of the time and
|
|
||||||
SWIG.@footnote{In all likelihood this would have been Python 2.2 or possibly
|
|
||||||
Python 2.3.} Shortly after creating it and ensuring it worked he stopped
|
|
||||||
supporting it, though he left his work available on his Gopher
|
|
||||||
site.
|
|
||||||
|
|
||||||
@node Keeping the flame alive
|
|
||||||
@section Keeping the flame alive
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
@node Passing the torch
|
|
||||||
@section Passing the torch
|
|
||||||
|
|
||||||
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).
|
|
||||||
|
|
||||||
@node Coming full circle
|
|
||||||
@section Coming full circle
|
|
||||||
|
|
||||||
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 @samp{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 @samp{pyme3}
|
|
||||||
module was renamed to @samp{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.
|
|
||||||
|
|
||||||
@node Relics of the past
|
|
||||||
@chapter Relics of the past
|
|
||||||
|
|
||||||
There are a few things, in addition to code specific factors, such as
|
|
||||||
SWIG itself, which are worth noting here.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* The Annoyances of Git::
|
|
||||||
* The Perils of PyPI::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node The Annoyances of Git
|
|
||||||
@section 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 was skipped with addition of the PyME
|
|
||||||
code to GPGME.
|
|
||||||
|
|
||||||
Instead the files were added to a subdirectory of the @samp{lang/}
|
|
||||||
directory, along with a copy of the entire git log up to that point
|
|
||||||
as a separate file within the @samp{lang/python/docs/} directory.@footnote{The entire PyME git log and other preceding VCS logs are
|
|
||||||
located in the @samp{gpgme/lang/python/docs/old-commits.log} file.}
|
|
||||||
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.
|
|
||||||
|
|
||||||
@node The Perils of PyPI
|
|
||||||
@section The Perils of PyPI
|
|
||||||
|
|
||||||
The early port of the Python 2 @samp{pyme} module as @samp{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 @samp{pyme3} to @samp{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:
|
|
||||||
|
|
||||||
@enumerate
|
|
||||||
@item
|
|
||||||
gpg (1.8.0) - Python bindings for GPGME GnuPG cryptography library
|
|
||||||
@item
|
|
||||||
pyme (0.9.0) - Python support for GPGME GnuPG cryptography library
|
|
||||||
@end enumerate
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library::
|
|
||||||
* PyME 0·9·0 - Python support for GPGME GnuPG cryptography library::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library
|
|
||||||
@subsection GPG 1·8·0 - Python bindings for GPGME GnuPG cryptography library
|
|
||||||
|
|
||||||
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 @emph{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.
|
|
||||||
|
|
||||||
@node PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
|
|
||||||
@subsection PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
@bye
|
|
||||||
@ -1,94 +0,0 @@
|
|||||||
\input texinfo @c -*- texinfo -*-
|
|
||||||
@c %**start of header
|
|
||||||
@setfilename what-is-new.info
|
|
||||||
@settitle What's New in the GPGME Python Bindings and Documentation
|
|
||||||
@documentencoding utf-8
|
|
||||||
@documentlanguage en
|
|
||||||
@c %**end of header
|
|
||||||
|
|
||||||
@finalout
|
|
||||||
@titlepage
|
|
||||||
@title What's New in the GPGME Python Bindings and Documentation
|
|
||||||
@author Ben McGinnes
|
|
||||||
@end titlepage
|
|
||||||
|
|
||||||
@contents
|
|
||||||
|
|
||||||
@ifnottex
|
|
||||||
@node Top
|
|
||||||
@top What's New in the GPGME Python Bindings and Documentation
|
|
||||||
@end ifnottex
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* What's New::
|
|
||||||
|
|
||||||
@detailmenu
|
|
||||||
--- The Detailed Node Listing ---
|
|
||||||
|
|
||||||
What's New
|
|
||||||
|
|
||||||
* New in GPGME 1·13·0::
|
|
||||||
|
|
||||||
@end detailmenu
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node What's New
|
|
||||||
@chapter What's New
|
|
||||||
|
|
||||||
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
||||||
@item Version:
|
|
||||||
@tab 0.0.1
|
|
||||||
@item GPGME Version:
|
|
||||||
@tab 1.13.0
|
|
||||||
@item Author:
|
|
||||||
@tab Ben McGinnes <ben@@gnupg.org>
|
|
||||||
@item Author GPG Key:
|
|
||||||
@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
|
|
||||||
@item Language:
|
|
||||||
@tab Australian English, British English
|
|
||||||
@item xml:lang:
|
|
||||||
@tab en-AU, en-GB, en
|
|
||||||
@end multitable
|
|
||||||
|
|
||||||
Last time the most obviously new thing was adding the @emph{What's New}
|
|
||||||
section to the HOWTO. Now it's moving it out of the HOWTO.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* New in GPGME 1·13·0::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node New in GPGME 1·13·0
|
|
||||||
@section New in GPGME 1·13·0
|
|
||||||
|
|
||||||
Additions since GPGME 1.12.0 include:
|
|
||||||
|
|
||||||
@itemize
|
|
||||||
@item
|
|
||||||
Moving the @emph{What's New} section out of the basic @uref{gpgme-python-howto.org, HOWTO} document and
|
|
||||||
into its own file so as to more readily include other documents
|
|
||||||
beyond that HOWTO.
|
|
||||||
@item
|
|
||||||
Moving the preceding, archival, segments into @uref{what-was-new.org, another file}.
|
|
||||||
@item
|
|
||||||
Added @samp{gpg.version.versionintlist} to make it easier for Python
|
|
||||||
developers to check for a specific version number, even with beta
|
|
||||||
versions (it will drop the "-betaN" part).
|
|
||||||
@item
|
|
||||||
Added expanded detail on issues pertaining to installing for Windows
|
|
||||||
users.
|
|
||||||
@item
|
|
||||||
Bindings enter @uref{maintenance-mode, maintenance mode} from January, 2019.
|
|
||||||
@item
|
|
||||||
Added documentation on maintenance mode and what changes can be made
|
|
||||||
to the code when in that status. Essentially that boils down to bug
|
|
||||||
fixes only and no feature requests.
|
|
||||||
@item
|
|
||||||
The import-keys-hkp.py example script, which uses the @samp{hkp4py}
|
|
||||||
module to search the SKS servers for a key, has been tightened up to
|
|
||||||
search for both hexadecimal key IDs and user ID strings with reduced
|
|
||||||
chance of unnecessary repitition. There may still be some
|
|
||||||
repetition if a key includes a user ID matching the hexadecimal
|
|
||||||
value of a key ID.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@bye
|
|
||||||
@ -1,160 +0,0 @@
|
|||||||
\input texinfo @c -*- texinfo -*-
|
|
||||||
@c %**start of header
|
|
||||||
@setfilename what-was-new.info
|
|
||||||
@settitle What Was New in the GPGME Python Bindings and Documentation
|
|
||||||
@documentencoding utf-8
|
|
||||||
@documentlanguage en
|
|
||||||
@c %**end of header
|
|
||||||
|
|
||||||
@finalout
|
|
||||||
@titlepage
|
|
||||||
@title What Was New in the GPGME Python Bindings and Documentation
|
|
||||||
@author Ben McGinnes
|
|
||||||
@end titlepage
|
|
||||||
|
|
||||||
@contents
|
|
||||||
|
|
||||||
@ifnottex
|
|
||||||
@node Top
|
|
||||||
@top What Was New in the GPGME Python Bindings and Documentation
|
|
||||||
@end ifnottex
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* What Was New::
|
|
||||||
|
|
||||||
@detailmenu
|
|
||||||
--- The Detailed Node Listing ---
|
|
||||||
|
|
||||||
What Was New
|
|
||||||
|
|
||||||
* What Was New in GPGME 1·12·0::
|
|
||||||
|
|
||||||
What Was New in GPGME 1·12·0
|
|
||||||
|
|
||||||
* New in GPGME 1·12·0::
|
|
||||||
|
|
||||||
@end detailmenu
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node What Was New
|
|
||||||
@chapter What Was New
|
|
||||||
|
|
||||||
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
|
|
||||||
@item Version:
|
|
||||||
@tab 0.0.1
|
|
||||||
@item GPGME Version:
|
|
||||||
@tab 1.13.0
|
|
||||||
@item Author:
|
|
||||||
@tab Ben McGinnes <ben@@gnupg.org>
|
|
||||||
@item Author GPG Key:
|
|
||||||
@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D
|
|
||||||
@item Language:
|
|
||||||
@tab Australian English, British English
|
|
||||||
@item xml:lang:
|
|
||||||
@tab en-AU, en-GB, en
|
|
||||||
@end multitable
|
|
||||||
|
|
||||||
The following are all the past @emph{What's New} sections for the Python
|
|
||||||
Bindings HOWTO and other documentation.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* What Was New in GPGME 1·12·0::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node What Was New in GPGME 1·12·0
|
|
||||||
@section What Was New in GPGME 1·12·0
|
|
||||||
|
|
||||||
The most obviously new point for those reading this guide is this
|
|
||||||
section on other new things, but that’s hardly important. Not given
|
|
||||||
all the other things which spurred the need for adding this section
|
|
||||||
and its subsections.
|
|
||||||
|
|
||||||
@menu
|
|
||||||
* New in GPGME 1·12·0::
|
|
||||||
@end menu
|
|
||||||
|
|
||||||
@node New in GPGME 1·12·0
|
|
||||||
@subsection New in GPGME 1·12·0
|
|
||||||
|
|
||||||
There have been quite a number of additions to GPGME and the Python
|
|
||||||
bindings to it since the last release of GPGME with versions 1.11.0
|
|
||||||
and 1.11.1 in April, 2018.
|
|
||||||
|
|
||||||
The bullet points of new additiions are:
|
|
||||||
|
|
||||||
@itemize
|
|
||||||
@item
|
|
||||||
an expanded section on @uref{gpgme-python-howto#installation, installing} and @uref{gpgme-python-howto#snafu, troubleshooting} the Python
|
|
||||||
bindings.
|
|
||||||
@item
|
|
||||||
The release of Python 3.7.0; which appears to be working just fine
|
|
||||||
with our bindings, in spite of intermittent reports of problems for
|
|
||||||
many other Python projects with that new release.
|
|
||||||
@item
|
|
||||||
Python 3.7 has been moved to the head of the specified python
|
|
||||||
versions list in the build process.
|
|
||||||
@item
|
|
||||||
In order to fix some other issues, there are certain underlying
|
|
||||||
functions which are more exposed through the @uref{gpgme-python-howto#howto-get-context, gpg.Context()}, but
|
|
||||||
ongoing documentation ought to clarify that or otherwise provide the
|
|
||||||
best means of using the bindings. Some additions to @samp{gpg.core} and
|
|
||||||
the @samp{Context()}, however, were intended (see below).
|
|
||||||
@item
|
|
||||||
Continuing work in identifying and confirming the cause of
|
|
||||||
oft-reported @uref{gpgme-python-howto#snafu-runtime-not-funtime, problems installing the Python bindings on Windows}.
|
|
||||||
@item
|
|
||||||
GSOC: Google's Surreptitiously Ordered Conscription @dots{} erm @dots{} oh,
|
|
||||||
right; Google's Summer of Code. Though there were two hopeful
|
|
||||||
candidates this year; only one ended up involved with the GnuPG
|
|
||||||
Project directly, the other concentrated on an unrelated third party
|
|
||||||
project with closer ties to one of the GNU/Linux distributions than
|
|
||||||
to the GnuPG Project. Thus the Python bindings benefited from GSOC
|
|
||||||
participant Jacob Adams, who added the key@math{_import} function; building
|
|
||||||
on prior work by Tobias Mueller.
|
|
||||||
@item
|
|
||||||
Several new methods functions were added to the gpg.Context(),
|
|
||||||
including: @uref{gpgme-python-howto#howto-import-key, key@math{_import}}, @uref{gpgme-python-howto#howto-export-key, key@math{_export}}, @uref{gpgme-python-howto#howto-export-public-key, key@math{_export}@math{_minimal}} and
|
|
||||||
@uref{gpgme-python-howto#howto-export-secret-key, key@math{_export}@math{_secret}}.
|
|
||||||
@item
|
|
||||||
Importing and exporting examples include versions integrated with
|
|
||||||
Marcel Fest's recently released @uref{https://github.com/Selfnet/hkp4py, HKP for Python} module. Some
|
|
||||||
@uref{gpgme-python-howto#hkp4py, additional notes on this module} are included at the end of the HOWTO.
|
|
||||||
@item
|
|
||||||
Instructions for dealing with semi-walled garden implementations
|
|
||||||
like ProtonMail are also included. This is intended to make things
|
|
||||||
a little easier when communicating with users of ProtonMail's
|
|
||||||
services and should not be construed as an endorsement of said
|
|
||||||
service. The GnuPG Project neither favours, nor disfavours
|
|
||||||
ProtonMail and the majority of this deals with interacting with the
|
|
||||||
ProtonMail keyserver.
|
|
||||||
@item
|
|
||||||
Semi-formalised the location where @uref{gpgme-python-howto#draft-editions, draft versions} of this HOWTO may
|
|
||||||
periodically be accessible. This is both for the reference of
|
|
||||||
others and testing the publishing of the document itself. Renamed
|
|
||||||
this file at around the same time.
|
|
||||||
@item
|
|
||||||
The Texinfo documentation build configuration has been replicated
|
|
||||||
from the parent project in order to make to maintain consistency
|
|
||||||
with that project (and actually ship with each release).
|
|
||||||
@item
|
|
||||||
a reStructuredText (@samp{.rst}) version is also generated for Python
|
|
||||||
developers more used to and comfortable with that format as it is
|
|
||||||
the standard Python documentation format and Python developers may
|
|
||||||
wish to use it with Sphinx. Please note that there has been no
|
|
||||||
testing of the reStructuredText version with Sphinx at all. The
|
|
||||||
reST file was generated by the simple expedient of using @uref{https://pandoc.org/, Pandoc}.
|
|
||||||
@item
|
|
||||||
Added a new section for @uref{gpgme-python-howto#advanced-use, advanced or experimental use}.
|
|
||||||
@item
|
|
||||||
Began the advanced use cases with @uref{gpgme-python-howto#cython, a section} on using the module with
|
|
||||||
@uref{https://cython.org/, Cython}.
|
|
||||||
@item
|
|
||||||
Added a number of new scripts to the @samp{example/howto/} directory;
|
|
||||||
some of which may be in advance of their planned sections of the
|
|
||||||
HOWTO (and some are just there because it seemed like a good idea at
|
|
||||||
the time).
|
|
||||||
@item
|
|
||||||
Cleaned up a lot of things under the hood.
|
|
||||||
@end itemize
|
|
||||||
|
|
||||||
@bye
|
|
||||||
Loading…
Reference in New Issue
Block a user