diff --git a/doc/gpgme-python-howto.texi b/doc/gpgme-python-howto.texi index 2e305970..2e13d872 100644 --- a/doc/gpgme-python-howto.texi +++ b/doc/gpgme-python-howto.texi @@ -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. diff --git a/lang/python/docs/gpgme-python-howto.org b/lang/python/docs/gpgme-python-howto.org index 2f6ce73e..6c599cb0 100644 --- a/lang/python/docs/gpgme-python-howto.org +++ b/lang/python/docs/gpgme-python-howto.org @@ -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.