aboutsummaryrefslogtreecommitdiffstats
path: root/lang/python/doc/rst/gpgme-python-howto.rst
diff options
context:
space:
mode:
authorBen McGinnes <[email protected]>2018-11-06 05:22:50 +0000
committerBen McGinnes <[email protected]>2018-11-06 05:22:50 +0000
commitd0a5caf73c2d6b73dd043f62574c31946e4f347d (patch)
tree5b84b8694b5bffb212a38c6473387d5ab5ce0225 /lang/python/doc/rst/gpgme-python-howto.rst
parentpython examples: another importer (diff)
downloadgpgme-d0a5caf73c2d6b73dd043f62574c31946e4f347d.tar.gz
gpgme-d0a5caf73c2d6b73dd043f62574c31946e4f347d.zip
docs: python bindings
* Continued restructuring as part of moving beyond mere;y the HOWTO file. * Generated the alternative source files for reST and Texinfo. * Fixed some errors and updated links after moving the what's new section to two new files (yes, two).
Diffstat (limited to '')
-rw-r--r--lang/python/doc/rst/gpgme-python-howto.rst123
1 files changed, 36 insertions, 87 deletions
diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst
index 104b530e..3fd8a4d0 100644
--- a/lang/python/doc/rst/gpgme-python-howto.rst
+++ b/lang/python/doc/rst/gpgme-python-howto.rst
@@ -71,87 +71,25 @@ produced in between major releases.
What\'s New
-----------
-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.
+Full details of what is new are now available in the `What\'s
+New <what-is-new.org>`__ file and archives of the preceding *What\'s
+New* sections are available in the `What Was New <what-was-new>`__ file.
+
+.. _new-stuff-1-13-0:
+
+New in GPGME 1·13·0
+~~~~~~~~~~~~~~~~~~~
+
+See the `What\'s New <what-is-new#new-stuff-1-13-0>`__ document for what
+is new in version 1.13.0.
.. _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 <#installation>`__ and
- `troubleshooting <#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() <#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 <#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 <#howto-import-key>`__,
- `key\ export <#howto-export-key>`__,
- `key\ exportminimal <#howto-export-public-key>`__ and
- `key\ exportsecret <#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 <#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 <#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 <#advanced-use>`__.
-- Began the advanced use cases with `a section <#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.
+See the `What Was New <what-was-new#new-stuff-1-12-0>`__ document for
+what was new in version 1.12.0.
GPGME Concepts
==============
@@ -472,7 +410,7 @@ place.
Multiple installations
~~~~~~~~~~~~~~~~~~~~~~
-For a veriety of reasons it may be either necessary or just preferable
+For a variety of reasons it may be either necessary or just preferable
to install the bindings to alternative installed Python versions which
meet the requirements of these bindings.
@@ -489,6 +427,16 @@ by major version numbers and probably minor numbers too).
On most POSIX systems, including OS X, this will very likely be the case
in most, if not all, cases.
+Note that from GPGME
+`1.12.1 <https://dev.gnupg.org/rMff6ff616aea6f59b7f2ce1176492850ecdf3851e>`__
+the default installation installs to each version of Python it can find
+first. That is that it will currently install for the first copies of
+Python versions 2.7, 3.4, 3.5, 3.6, 3.7 and 3.8 (dev branch) that it
+finds. Usually this will be in the same prefix as GPGME itself, but is
+dictated by the ``$PATH`` when the installation is performed. The above
+instructions can still be performed on other python installations which
+the installer does not find, including alternative prefixes.
+
.. _snafu-runtime-not-funtime:
Won\'t Work With Windows
@@ -602,10 +550,10 @@ to or which are found by GPGME\'s configuration stage immediately prior
to running the make commands. Which is exactly what the compiling and
installing process of GPGME does by default.
-Once that is done, however, it appears that a copy the compiled module
-may be installed into a virtualenv of the same major and minor version
-matching the build. Alternatively it is possible to utilise a
-``sites.pth`` file in the ``site-packages/`` directory of a viertualenv
+Once that is done, however, it appears that a copy of the compiled
+module may be installed into a virtualenv of the same major and minor
+version matching the build. Alternatively it is possible to utilise a
+``sites.pth`` file in the ``site-packages/`` directory of a virtualenv
installation, which links back to the system installations corresponding
directory in order to import anything installed system wide. This may or
may not be appropriate on a case by case basis.
@@ -2565,8 +2513,8 @@ Unsurprisingly the result of this is:
.. _keygen-uids-revoke:
-Revokinging User IDs
-~~~~~~~~~~~~~~~~~~~~
+Revoking User IDs
+~~~~~~~~~~~~~~~~~
Revoking a user ID is a fairly similar process, except that it uses the
``key_revoke_uid`` method.
@@ -2815,7 +2763,7 @@ is the key IDs of the group as a string.
The ``group_lists`` result is very similar in that it is a list of
lists. The first part, ``group_lists[i][0]`` matches
``group_lines[i][0]`` as the name of the group, but
-``group_lists[i][1]`` is the key IDs of the group as a string.
+``group_lists[i][1]`` is the key IDs of the group as a list.
A demonstration of using the ``groups.py`` module is also available in
the form of the executable ``mutt-groups.py`` script. This second script
@@ -2920,17 +2868,18 @@ All of these draft versions except for one have been generated from this
document via Emacs `Org mode <https://orgmode.org/>`__ and `GNU
Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely
that the specific
-`file <https://files.au.adversary.org/crypto/gpgme-python-howto.org>`__
+`file <https://files.au.adversary.org/crypto/gpgme-python-howto>`__
`version <http://files.au.adversary.org/crypto/gpgme-python-howto.org>`__
used will be on the same server with the generated output formats.
The one exception is the reStructuredText version, which was converted
using the latest version of Pandoc from the Org mode source file using
-the following command:
+either of the following two commands:
.. code:: shell
- pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org
+ pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto.org
+ pandoc -f org -t rst -o gpgme-python-howto.rst gpgme-python-howto
In addition to these there is a significantly less frequently updated
version as a HTML `WebHelp
@@ -2965,7 +2914,7 @@ Footnotes
=========
.. [1]
- ``short-history.org`` and/or ``short-history.html``.
+ ``short-history`` and/or ``short-history.html``.
.. [2]
With no issues reported specific to Python 3.7, the release of Python