docs: python bindings howto
* Added a What's New section to summarise changes since the last release. There have been quite a few and some attention does need to be drawn to some of them. * Confirming certain issues with some platform builds, especially BSD/OSX vs. Linux issues which will need to update the installation troubleshooting guides.
This commit is contained in:
Ben McGinnes
parent
b12b2cc996
commit
e9da4d9710
@ -39,6 +39,11 @@ Introduction
|
||||
* Python 2 versus Python 3::
|
||||
* Examples::
|
||||
* Unofficial Drafts::
|
||||
* What's New::
|
||||
|
||||
What's New
|
||||
|
||||
* New in GPGME 1.12.0: New in GPGME 1120.
|
||||
|
||||
GPGME Concepts
|
||||
|
||||
@ -175,6 +180,7 @@ Python bindings to programmatically leverage the GPGME library.
|
||||
* Python 2 versus Python 3::
|
||||
* Examples::
|
||||
* Unofficial Drafts::
|
||||
* What's New::
|
||||
@end menu
|
||||
|
||||
@node Python 2 versus Python 3
|
||||
@ -214,6 +220,80 @@ on locations to read or download @ref{Draft Editions of this HOWTO, , draft edit
|
||||
at the end of it. These are unofficial versions produced in between
|
||||
major releases.
|
||||
|
||||
@node What's New
|
||||
@section 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.
|
||||
|
||||
@menu
|
||||
* New in GPGME 1.12.0: New in GPGME 1120.
|
||||
@end menu
|
||||
|
||||
@node New in GPGME 1120
|
||||
@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 @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
|
||||
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.
|
||||
@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{http://cython.org/, Cython}.
|
||||
@end itemize
|
||||
|
||||
@node GPGME Concepts
|
||||
@chapter GPGME Concepts
|
||||
|
||||
@ -479,7 +559,7 @@ If Python is set to precede one of the other languages then it is
|
||||
possible that the errors described here may interrupt the build
|
||||
process before generating bindings for those other languages. In
|
||||
these cases it may be preferable to configure all preferred language
|
||||
bindings separately with alternative @samp{configure} steps for GPGME using
|
||||
howto-export-public-keybindings separately with alternative @samp{configure} steps for GPGME using
|
||||
the @samp{--enable-languages=$LANGUAGE} option.
|
||||
@end enumerate
|
||||
|
||||
@ -2673,7 +2753,11 @@ support for Python 2.7 as well and is available via PyPI.
|
||||
|
||||
Since it rewrites the @samp{hkp} protocol prefix as @samp{http} and @samp{hkps} as
|
||||
@samp{https}, the module is able to be used even with servers which do not
|
||||
support the full scope of keyserver functions. It also works quite
|
||||
support the full scope of keyserver functions.@footnote{Such as with ProtonMail servers. This also means that
|
||||
restricted servers which only advertise either HTTP or HTTPS end
|
||||
points and not HKP or HKPS end points must still be identified as as
|
||||
HKP or HKPS within the Python Code. The @samp{hkp4py} module will rewrite
|
||||
these appropriately when the connection is made to the server.} It also works quite
|
||||
readily when incorporated into a @ref{C plus Python plus SWIG plus Cython, , Cython} generated and compiled version
|
||||
of any code.
|
||||
|
||||
|
||||
@ -72,6 +72,68 @@ at the end of it. These are unofficial versions produced in between
|
||||
major releases.
|
||||
|
||||
|
||||
** What's New
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: new-stuff
|
||||
:END:
|
||||
|
||||
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 in GPGME 1.12.0
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: new-stuff-1-12-0
|
||||
:END:
|
||||
|
||||
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 [[#installation][installing]] and [[#snafu][troubleshooting]] 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.
|
||||
- In order to fix some other issues, there are certain underlying
|
||||
functions which are more exposed through the [[#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 =gpg.core= and
|
||||
the =Context()=, however, were intended (see below).
|
||||
- Continuing work in identifying and confirming the cause of
|
||||
oft-reported [[#snafu-runtime-not-funtime][problems installing the Python bindings on Windows]].
|
||||
- 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_import function; building
|
||||
on prior work by Tobias Mueller.
|
||||
- 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
|
||||
[[#howto-export-secret-key][key_export_secret]].
|
||||
- Importing and exporting examples include versions integrated with
|
||||
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.
|
||||
- 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-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.
|
||||
- Added a new section for [[#advanced-use][advanced or experimental use]].
|
||||
- Began the advanced use cases with [[#cython][a section]] on using the module with
|
||||
[[http://cython.org/][Cython]].
|
||||
|
||||
|
||||
* GPGME Concepts
|
||||
:PROPERTIES:
|
||||
:CUSTOM_ID: gpgme-concepts
|
||||
@ -336,7 +398,7 @@ If Python is set to precede one of the other languages then it is
|
||||
possible that the errors described here may interrupt the build
|
||||
process before generating bindings for those other languages. In
|
||||
these cases it may be preferable to configure all preferred language
|
||||
bindings separately with alternative =configure= steps for GPGME using
|
||||
howto-export-public-keybindings separately with alternative =configure= steps for GPGME using
|
||||
the =--enable-languages=$LANGUAGE= option.
|
||||
|
||||
|
||||
@ -2577,7 +2639,7 @@ support for Python 2.7 as well and is available via PyPI.
|
||||
|
||||
Since it rewrites the =hkp= protocol prefix as =http= and =hkps= as
|
||||
=https=, the module is able to be used even with servers which do not
|
||||
support the full scope of keyserver functions. It also works quite
|
||||
support the full scope of keyserver functions.[fn:6] It also works quite
|
||||
readily when incorporated into a [[#cython][Cython]] generated and compiled version
|
||||
of any code.
|
||||
|
||||
@ -2704,3 +2766,9 @@ POSIX systems which utilise single user mode (some even require it).
|
||||
keyservers for "gnupg.org" produces over 400 results, the majority of
|
||||
which aren't actually at the gnupg.org domain, but just included a
|
||||
comment regarding the project in their key somewhere.
|
||||
|
||||
[fn:6] Such as with ProtonMail servers. This also means that
|
||||
restricted servers which only advertise either HTTP or HTTPS end
|
||||
points and not HKP or HKPS end points must still be identified as as
|
||||
HKP or HKPS within the Python Code. The =hkp4py= module will rewrite
|
||||
these appropriately when the connection is made to the server.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user