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/>.
|
||||
# SPDX-License-Identifier: LGPL-2.1-or-later
|
||||
|
||||
# Created by:
|
||||
# find . -type f -print | sed 's/^.\// /;$q;s/$/ \\/' | sort
|
||||
EXTRA_DIST = texinfo/what-was-new.texi \
|
||||
meta/old-commits.log \
|
||||
meta/TODO.org \
|
||||
README \
|
||||
EXTRA_DIST = README \
|
||||
rst/_build/README \
|
||||
rst/_static/README \
|
||||
rst/_templates/README \
|
||||
rst/conf.py \
|
||||
rst/gpgme-python-howto.rst \
|
||||
rst/index.rst \
|
||||
rst/maintenance-mode.rst \
|
||||
rst/short-history.rst \
|
||||
rst/_static/README \
|
||||
rst/_templates/README \
|
||||
rst/what-is-new.rst \
|
||||
rst/what-was-new.rst \
|
||||
src/gpgme-python-howto \
|
||||
src/index \
|
||||
src/maintenance-mode \
|
||||
src/short-history \
|
||||
src/what-is-new \
|
||||
src/what-was-new \
|
||||
src/gpgme-python-howto.org \
|
||||
src/index.org \
|
||||
src/maintenance-mode.org \
|
||||
src/short-history.org \
|
||||
src/what-is-new.org \
|
||||
src/what-was-new.org \
|
||||
texinfo/texinfo.tex \
|
||||
texinfo/gpgme-python-howto.texi \
|
||||
texinfo/index.texi \
|
||||
texinfo/maintenance-mode.texi \
|
||||
texinfo/short-history.texi \
|
||||
texinfo/texinfo.tex \
|
||||
texinfo/what-is-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