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

docs: python bindings

Browse Source 
* 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).
This commit is contained in:
Ben McGinnes 2018-11-06 16:22:50 +11:00
parent 0cb625da84
commit d0a5caf73c
14 changed files with 504 additions and 215 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
lang/python/doc/README
View File

@ -25,14 +25,14 @@ This docs directory contains four main subdirectories:
4. texinfo 4. texinfo
The Meta directory is for docs that are not intended for distribution The Meta directory is for docs that are not intended for distribution
or are about the docs themselves. The sole exception being this RDME or are about the docs themselves. The sole exception being this
file. README file.
The Src directory is where the original edited files are, from which The Src directory is where the original edited files are, from which
the following two formats are generated initially. Most, if not all, the following two formats are generated initially. Most, if not all,
of these are written in Org Mode. of these are written in Org Mode.
The ReST directory contains reStructuredText files ehich have been The ReST directory contains reStructuredText files which have been
converted to that format from the Org Mode files via Pandoc. converted to that format from the Org Mode files via Pandoc.
The Texinfo directory contains Texinfo files which have been exported The Texinfo directory contains Texinfo files which have been exported

123
lang/python/doc/rst/gpgme-python-howto.rst
View File

@ -71,87 +71,25 @@ produced in between major releases.
What\'s New What\'s New
----------- -----------
The most obviously new point for those reading this guide is this Full details of what is new are now available in the `What\'s
section on other new things, but that\'s hardly important. Not given all New <what-is-new.org>`__ file and archives of the preceding *What\'s
the other things which spurred the need for adding this section and its New* sections are available in the `What Was New <what-was-new>`__ file.
subsections.
.. _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-stuff-1-12-0:
New in GPGME 1·12·0 New in GPGME 1·12·0
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
There have been quite a number of additions to GPGME and the Python See the `What Was New <what-was-new#new-stuff-1-12-0>`__ document for
bindings to it since the last release of GPGME with versions 1.11.0 and what was new in version 1.12.0.
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.
GPGME Concepts GPGME Concepts
============== ==============
@ -472,7 +410,7 @@ place.
Multiple installations 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 to install the bindings to alternative installed Python versions which
meet the requirements of these bindings. 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 On most POSIX systems, including OS X, this will very likely be the case
in most, if not all, cases. 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: .. _snafu-runtime-not-funtime:
Won\'t Work With Windows 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 to running the make commands. Which is exactly what the compiling and
installing process of GPGME does by default. installing process of GPGME does by default.
Once that is done, however, it appears that a copy the compiled module Once that is done, however, it appears that a copy of the compiled
may be installed into a virtualenv of the same major and minor version module may be installed into a virtualenv of the same major and minor
matching the build. Alternatively it is possible to utilise a version matching the build. Alternatively it is possible to utilise a
``sites.pth`` file in the ``site-packages/`` directory of a viertualenv ``sites.pth`` file in the ``site-packages/`` directory of a virtualenv
installation, which links back to the system installations corresponding installation, which links back to the system installations corresponding
directory in order to import anything installed system wide. This may or directory in order to import anything installed system wide. This may or
may not be appropriate on a case by case basis. may not be appropriate on a case by case basis.
@ -2565,8 +2513,8 @@ Unsurprisingly the result of this is:
.. _keygen-uids-revoke: .. _keygen-uids-revoke:
Revokinging User IDs Revoking User IDs
~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
Revoking a user ID is a fairly similar process, except that it uses the Revoking a user ID is a fairly similar process, except that it uses the
``key_revoke_uid`` method. ``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 The ``group_lists`` result is very similar in that it is a list of
lists. The first part, ``group_lists[i][0]`` matches lists. The first part, ``group_lists[i][0]`` matches
``group_lines[i][0]`` as the name of the group, but ``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 A demonstration of using the ``groups.py`` module is also available in
the form of the executable ``mutt-groups.py`` script. This second script 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 document via Emacs `Org mode <https://orgmode.org/>`__ and `GNU
Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely
that the specific 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>`__ `version <http://files.au.adversary.org/crypto/gpgme-python-howto.org>`__
used will be on the same server with the generated output formats. used will be on the same server with the generated output formats.
The one exception is the reStructuredText version, which was converted The one exception is the reStructuredText version, which was converted
using the latest version of Pandoc from the Org mode source file using using the latest version of Pandoc from the Org mode source file using
the following command: either of the following two commands:
.. code:: shell .. 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 In addition to these there is a significantly less frequently updated
version as a HTML `WebHelp version as a HTML `WebHelp
@ -2965,7 +2914,7 @@ Footnotes
========= =========
.. [1] .. [1]
``short-history.org`` and/or ``short-history.html``. ``short-history`` and/or ``short-history.html``.
.. [2] .. [2]
With no issues reported specific to Python 3.7, the release of Python With no issues reported specific to Python 3.7, the release of Python

10
lang/python/doc/rst/index.rst
View File

@ -1,12 +1,12 @@
.. _index: .. _top:
GPGME Python Bindings GPGME Python Bindings
===================== =====================
.. _index-contents:
Contents Contents
-------- --------
- `A short history of the project <short-history.org>`__ - `A short history of the project <short-history>`__
- `GPGME Python Bindings HOWTO <gpgme-python-howto.org>`__ - `What\'s New <what-is-new>`__
- `What Was New <what-was-new>`__
- `GPGME Python Bindings HOWTO <gpgme-python-howto>`__

12
lang/python/doc/rst/short-history.rst
View File

@ -19,10 +19,10 @@ Keeping the flame alive
----------------------- -----------------------
A couple of years later the project was picked up by Igor Belyi and 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 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 whereabouts at the time of this document\'s creation are unknown, but
current authors do hope he is well. We're assuming (or hoping) that life the current authors do hope he is well. We\'re assuming (or hoping) that
did what life does and made continuing untenable. life did what life does and made continuing untenable.
Passing the torch Passing the torch
----------------- -----------------
@ -135,7 +135,7 @@ Python 2 to Python 3 code was made in 2015.
Users of the more recent Python bindings will recognise numerous points Users of the more recent Python bindings will recognise numerous points
of similarity, but also significant differences. It is likely that the of similarity, but also significant differences. It is likely that the
more recent official bindings will feel "more pythonic." more recent official bindings will feel \"more pythonic.\"
For those using Python 2, there is essentially no harm in using this 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. module, but it may lack a number of more recent features added to GPGME.
@ -144,7 +144,7 @@ Footnotes
========= =========
.. [1] .. [1]
In all likelihood thos would have been Python 2.2 or possibly Python In all likelihood this would have been Python 2.2 or possibly Python
2.3. 2.3.
.. [2] .. [2]

42
lang/python/doc/rst/what-is-new.rst Normal file
View File

@ -0,0 +1,42 @@
.. _new-stuff:
What\'s New
===========
+-----------------------------------+-----------------------------------+
| Version: | 0.0.1-draft |
+-----------------------------------+-----------------------------------+
| GPGME Version: | 1.13.0 |
+-----------------------------------+-----------------------------------+
| Author: | `Ben |
| | McGinnes <https://gnupg.org/peopl |
| | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 |
| | 3590E5D |
+-----------------------------------+-----------------------------------+
| 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. Not to
mention expanding on the documentation both generally and considerably.
.. _new-stuff-1-13-0:
New in GPGME 1·13·0
-------------------
Additions since GPGME 1.12.0 include:
- An advanced HOWTO on using the bindings with web interfaces,
specifically Flask.
- 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>`__.

116
lang/python/doc/rst/what-was-new.rst Normal file
View File

@ -0,0 +1,116 @@
.. _new-stuff:
What Was New
============
+-----------------------------------+-----------------------------------+
| Version: | 0.0.1-draft |
+-----------------------------------+-----------------------------------+
| GPGME Version: | 1.13.0 |
+-----------------------------------+-----------------------------------+
| Author: | `Ben |
| | McGinnes <https://gnupg.org/peopl |
| | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 |
| | 3590E5D |
+-----------------------------------+-----------------------------------+
| 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.

6
lang/python/doc/src/index
View File

@ -12,15 +12,17 @@
* GPGME Python Bindings * GPGME Python Bindings
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: index :CUSTOM_ID: top
:END: :END:
** Contents ** Contents
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: index-contents :CUSTOM_ID: contents
:END: :END:
- [[file:short-history][A short history of the project]] - [[file:short-history][A short history of the project]]
- [[file:what-is-new][What's New]]
- [[file:what-was-new][What Was New]]
- [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]] - [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]]

2
lang/python/doc/src/short-history
View File

@ -166,7 +166,7 @@ SWIG itself, which are worth noting here.
* Footnotes * Footnotes
[fn:1] In all likelihood thos would have been Python 2.2 or possibly [fn:1] In all likelihood this would have been Python 2.2 or possibly
Python 2.3. Python 2.3.
[fn:2] The entire PyME git log and other preceding VCS logs are [fn:2] The entire PyME git log and other preceding VCS logs are

18
lang/python/doc/src/what-was-new
View File

@ -48,7 +48,7 @@ and 1.11.1 in April, 2018.
The bullet points of new additiions are: The bullet points of new additiions are:
- an expanded section on [[#installation][installing]] and [[#snafu][troubleshooting]] the Python - an expanded section on [[file:gpgme-python-howto#installation][installing]] and [[file:gpgme-python-howto#snafu][troubleshooting]] the Python
bindings. bindings.
- The release of Python 3.7.0; which appears to be working just fine - 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 with our bindings, in spite of intermittent reports of problems for
@ -56,12 +56,12 @@ The bullet points of new additiions are:
- Python 3.7 has been moved to the head of the specified python - Python 3.7 has been moved to the head of the specified python
versions list in the build process. versions list in the build process.
- In order to fix some other issues, there are certain underlying - In order to fix some other issues, there are certain underlying
functions which are more exposed through the [[#howto-get-context][gpg.Context()]], but functions which are more exposed through the [[file:gpgme-python-howto#howto-get-context][gpg.Context()]], but
ongoing documentation ought to clarify that or otherwise provide the ongoing documentation ought to clarify that or otherwise provide the
best means of using the bindings. Some additions to =gpg.core= and best means of using the bindings. Some additions to =gpg.core= and
the =Context()=, however, were intended (see below). the =Context()=, however, were intended (see below).
- Continuing work in identifying and confirming the cause of - Continuing work in identifying and confirming the cause of
oft-reported [[#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]]. oft-reported [[file:gpgme-python-howto#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]].
- GSOC: Google's Surreptitiously Ordered Conscription ... erm ... oh, - GSOC: Google's Surreptitiously Ordered Conscription ... erm ... oh,
right; Google's Summer of Code. Though there were two hopeful right; Google's Summer of Code. Though there were two hopeful
candidates this year; only one ended up involved with the GnuPG candidates this year; only one ended up involved with the GnuPG
@ -71,11 +71,11 @@ The bullet points of new additiions are:
participant Jacob Adams, who added the key_import function; building participant Jacob Adams, who added the key_import function; building
on prior work by Tobias Mueller. on prior work by Tobias Mueller.
- Several new methods functions were added to the gpg.Context(), - Several new methods functions were added to the gpg.Context(),
including: [[#howto-import-key][key_import]], [[#howto-export-key][key_export]], [[#howto-export-public-key][key_export_minimal]] and including: [[file:gpgme-python-howto#howto-import-key][key_import]], [[file:gpgme-python-howto#howto-export-key][key_export]], [[file:gpgme-python-howto#howto-export-public-key][key_export_minimal]] and
[[#howto-export-secret-key][key_export_secret]]. [[file:gpgme-python-howto#howto-export-secret-key][key_export_secret]].
- Importing and exporting examples include versions integrated with - Importing and exporting examples include versions integrated with
Marcel Fest's recently released [[https://github.com/Selfnet/hkp4py][HKP for Python]] module. Some Marcel Fest's recently released [[https://github.com/Selfnet/hkp4py][HKP for Python]] module. Some
[[#hkp4py][additional notes on this module]] are included at the end of the HOWTO. [[file:gpgme-python-howto#hkp4py][additional notes on this module]] are included at the end of the HOWTO.
- Instructions for dealing with semi-walled garden implementations - Instructions for dealing with semi-walled garden implementations
like ProtonMail are also included. This is intended to make things like ProtonMail are also included. This is intended to make things
a little easier when communicating with users of ProtonMail's a little easier when communicating with users of ProtonMail's
@ -83,7 +83,7 @@ The bullet points of new additiions are:
service. The GnuPG Project neither favours, nor disfavours service. The GnuPG Project neither favours, nor disfavours
ProtonMail and the majority of this deals with interacting with the ProtonMail and the majority of this deals with interacting with the
ProtonMail keyserver. ProtonMail keyserver.
- Semi-formalised the location where [[#draft-editions][draft versions]] of this HOWTO may - Semi-formalised the location where [[file:gpgme-python-howto#draft-editions][draft versions]] of this HOWTO may
periodically be accessible. This is both for the reference of periodically be accessible. This is both for the reference of
others and testing the publishing of the document itself. Renamed others and testing the publishing of the document itself. Renamed
this file at around the same time. this file at around the same time.
@ -96,8 +96,8 @@ The bullet points of new additiions are:
wish to use it with Sphinx. Please note that there has been no wish to use it with Sphinx. Please note that there has been no
testing of the reStructuredText version with Sphinx at all. The testing of the reStructuredText version with Sphinx at all. The
reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]]. reST file was generated by the simple expedient of using [[https://pandoc.org/][Pandoc]].
- Added a new section for [[#advanced-use][advanced or experimental use]]. - Added a new section for [[file:gpgme-python-howto#advanced-use][advanced or experimental use]].
- Began the advanced use cases with [[#cython][a section]] on using the module with - Began the advanced use cases with [[file:gpgme-python-howto#cython][a section]] on using the module with
[[https://cython.org/][Cython]]. [[https://cython.org/][Cython]].
- Added a number of new scripts to the =example/howto/= directory; - Added a number of new scripts to the =example/howto/= directory;
some of which may be in advance of their planned sections of the some of which may be in advance of their planned sections of the

133
lang/python/doc/texinfo/gpgme-python-howto.texi
View File

@ -43,6 +43,7 @@ Introduction
What's New What's New
* New in GPGME 1·13·0::
* New in GPGME 1·12·0:: * New in GPGME 1·12·0::
GPGME Concepts GPGME Concepts
@ -138,7 +139,7 @@ Creating keys and subkeys
User IDs User IDs
* Adding User IDs:: * Adding User IDs::
* Revokinging User IDs:: * Revoking User IDs::
Advanced or Experimental Use Cases Advanced or Experimental Use Cases
@ -230,98 +231,24 @@ major releases.
@node What's New @node What's New
@section What's New @section What's New
The most obviously new point for those reading this guide is this Full details of what is new are now available in the @uref{what-is-new.org, What's New} file
section on other new things, but that's hardly important. Not given and archives of the preceding @emph{What's New} sections are available in
all the other things which spurred the need for adding this section the @uref{what-was-new, What Was New} file.
and its subsections.
@menu @menu
* New in GPGME 1·13·0::
* New in GPGME 1·12·0:: * New in GPGME 1·12·0::
@end menu @end menu
@node New in GPGME 1·13·0
@subsection New in GPGME 1·13·0
See the @uref{what-is-new#new-stuff-1-13-0, What's New} document for what is new in version 1.13.0.
@node New in GPGME 1·12·0 @node New in GPGME 1·12·0
@subsection 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 See the @uref{what-was-new#new-stuff-1-12-0, What Was New} document for what was new in version 1.12.0.
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 @ref{Installation, , installing} and @ref{Known Issues, , 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 @ref{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 @ref{Won't Work With Windows, , 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: @ref{Importing keys, , key@math{_import}}, @ref{Exporting keys, , key@math{_export}}, @ref{Exporting public keys, , key@math{_export}@math{_minimal}} and
@ref{Exporting secret keys, , 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
@ref{Keyserver access for Python, , 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 @ref{Draft Editions of this HOWTO, , 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 @ref{Advanced or Experimental Use Cases, , advanced or experimental use}.
@item
Began the advanced use cases with @ref{C plus Python plus SWIG plus 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
@node GPGME Concepts @node GPGME Concepts
@chapter GPGME Concepts @chapter GPGME Concepts
@ -418,7 +345,7 @@ version 3.0 (or any later version).
This package is the origin of these bindings, though they are somewhat This package is the origin of these bindings, though they are somewhat
different now. For details of when and how the PyME package was different now. For details of when and how the PyME package was
folded back into GPGME itself see the @uref{short-history.org, Short History} document.@footnote{@samp{short-history.org} and/or @samp{short-history.html}.} folded back into GPGME itself see the @uref{short-history.org, Short History} document.@footnote{@samp{short-history} and/or @samp{short-history.html}.}
The PyME package was first released in 2002 and was also the first The PyME package was first released in 2002 and was also the first
attempt to implement a low level binding to GPGME. In doing so it attempt to implement a low level binding to GPGME. In doing so it
@ -670,7 +597,7 @@ place.
@node Multiple installations @node Multiple installations
@subsection Multiple installations @subsection 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 to install the bindings to alternative installed Python versions which
meet the requirements of these bindings. meet the requirements of these bindings.
@ -687,6 +614,15 @@ by major version numbers and probably minor numbers too).
On most POSIX systems, including OS X, this will very likely be the On most POSIX systems, including OS X, this will very likely be the
case in most, if not all, cases. case in most, if not all, cases.
Note that from GPGME @uref{https://dev.gnupg.org/rMff6ff616aea6f59b7f2ce1176492850ecdf3851e, 1.12.1} 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 @samp{$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.
@node Won't Work With Windows @node Won't Work With Windows
@subsection Won't Work With Windows @subsection Won't Work With Windows
@ -800,10 +736,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 to running the make commands. Which is exactly what the compiling and
installing process of GPGME does by default. installing process of GPGME does by default.
Once that is done, however, it appears that a copy the compiled module Once that is done, however, it appears that a copy of the compiled
may be installed into a virtualenv of the same major and minor version module may be installed into a virtualenv of the same major and minor
matching the build. Alternatively it is possible to utilise a version matching the build. Alternatively it is possible to utilise a
@samp{sites.pth} file in the @samp{site-packages/} directory of a viertualenv @samp{sites.pth} file in the @samp{site-packages/} directory of a virtualenv
installation, which links back to the system installations installation, which links back to the system installations
corresponding directory in order to import anything installed system corresponding directory in order to import anything installed system
wide. This may or may not be appropriate on a case by case basis. wide. This may or may not be appropriate on a case by case basis.
@ -2724,7 +2660,7 @@ bash-4.4$
@menu @menu
* Adding User IDs:: * Adding User IDs::
* Revokinging User IDs:: * Revoking User IDs::
@end menu @end menu
@node Adding User IDs @node Adding User IDs
@ -2763,8 +2699,8 @@ ssb rsa3072 2018-03-15 [E] [expires: 2018-09-13]
bash-4.4$ bash-4.4$
@end example @end example
@node Revokinging User IDs @node Revoking User IDs
@subsection Revokinging User IDs @subsection Revoking User IDs
Revoking a user ID is a fairly similar process, except that it uses Revoking a user ID is a fairly similar process, except that it uses
the @samp{key_revoke_uid} method. the @samp{key_revoke_uid} method.
@ -3009,7 +2945,7 @@ is the key IDs of the group as a string.
The @samp{group_lists} result is very similar in that it is a list of The @samp{group_lists} result is very similar in that it is a list of
lists. The first part, @samp{group_lists[i][0]} matches lists. The first part, @samp{group_lists[i][0]} matches
@samp{group_lines[i][0]} as the name of the group, but @samp{group_lists[i][1]} @samp{group_lines[i][0]} as the name of the group, but @samp{group_lists[i][1]}
is the key IDs of the group as a string. is the key IDs of the group as a list.
A demonstration of using the @samp{groups.py} module is also available in A demonstration of using the @samp{groups.py} module is also available in
the form of the executable @samp{mutt-groups.py} script. This second the form of the executable @samp{mutt-groups.py} script. This second
@ -3116,15 +3052,16 @@ from the author at any of the following URLs:
All of these draft versions except for one have been generated from All of these draft versions except for one have been generated from
this document via Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}. Though it is likely this document via Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}. Though it is likely
that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto.org, file} @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.org, version} used will be on the same server with that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto, file} @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.org, version} used will be on the same server with
the generated output formats. the generated output formats.
The one exception is the reStructuredText version, which was converted The one exception is the reStructuredText version, which was converted
using the latest version of Pandoc from the Org mode source file using using the latest version of Pandoc from the Org mode source file using
the following command: either of the following two commands:
@example @example
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
@end example @end example
In addition to these there is a significantly less frequently updated In addition to these there is a significantly less frequently updated

8
lang/python/doc/texinfo/index.texi
View File

@ -44,9 +44,13 @@ GPGME Python Bindings
@itemize @itemize
@item @item
@uref{short-history.org, A short history of the project} @uref{short-history, A short history of the project}
@item @item
@uref{gpgme-python-howto.org, GPGME Python Bindings HOWTO} @uref{what-is-new, What's New}
@item
@uref{what-was-new, What Was New}
@item
@uref{gpgme-python-howto, GPGME Python Bindings HOWTO}
@end itemize @end itemize
@bye @bye

2
lang/python/doc/texinfo/short-history.texi
View File

@ -65,7 +65,7 @@ return to the source. This is a short explanation of that journey.
In 2002 John Goerzen released PyME; Python bindings for the GPGME In 2002 John Goerzen released PyME; Python bindings for the GPGME
module which utilised the current release of Python of the time and module which utilised the current release of Python of the time and
SWIG.@footnote{In all likelihood thos would have been Python 2.2 or possibly 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 Python 2.3.} Shortly after creating it and ensuring it worked he stopped
supporting it, though he left his work available on his Gopher supporting it, though he left his work available on his Gopher
site. site.

79
lang/python/doc/texinfo/what-is-new.texi Normal file
View File

@ -0,0 +1,79 @@
\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} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item Version:
@tab 0.0.1-draft
@item GPGME Version:
@tab 1.13.0
@item Author:
@tab @uref{https://gnupg.org/people/index.html#sec-1-5, 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. Not to
mention expanding on the documentation both generally and
considerably.
@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
An advanced HOWTO on using the bindings with web interfaces,
specifically Flask.
@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}.
@end itemize
@bye

160
lang/python/doc/texinfo/what-was-new.texi Normal file
View File

@ -0,0 +1,160 @@
\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} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item Version:
@tab 0.0.1-draft
@item GPGME Version:
@tab 1.13.0
@item Author:
@tab @uref{https://gnupg.org/people/index.html#sec-1-5, 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