From f4d83800d89173e618cceca44b584778217fadb3 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Mon, 17 Sep 2018 14:33:02 +1000 Subject: [PATCH] docs: python bindings howto * Tightened up the Cython demonstration. --- doc/gpgme-python-howto.texi | 31 +++++++++---------------- lang/python/docs/gpgme-python-howto.org | 31 +++++++++---------------- 2 files changed, 22 insertions(+), 40 deletions(-) diff --git a/doc/gpgme-python-howto.texi b/doc/gpgme-python-howto.texi index 2fbac1f3..8073a90b 100644 --- a/doc/gpgme-python-howto.texi +++ b/doc/gpgme-python-howto.texi @@ -567,16 +567,6 @@ running into trouble with "ifdefs" then you'll know what sort of things are lacking. That doesn't even take into account the amount of work saved via SWIG's code generation techniques either. -There's a greater likelihood of turning to Cython to add something to -these bindings at this point than there is of turning to CFFI. Except -that there's little reason to do so when the C code in question either -already exists or could be produced fairly quickly by the far more -expedient means of asking either @uref{https://gnupg.org/people/index.html#sec-1-1, Werner}, @uref{https://gnupg.org/people/index.html#sec-1-3, Niibe} or @uref{https://gnupg.org/people/index.html#sec-1-6, Andre} to write -whatever was missing. Perhaps even @uref{https://gnupg.org/people/index.html#sec-1-4, Jussi}, but there shouldn't be any -need for these bindings to interface directly with his work and for -much the same reasons as we recommend people not call libgcrypt -directly unless they know what they're doing. - @node Fundamentals @chapter Fundamentals @@ -2076,9 +2066,10 @@ c.key_sign(key, uids=uid, expires_in=2764800) @node C plus Python plus SWIG plus Cython @section C plus Python plus SWIG plus Cython -In spite of my near facetious commentary in @ref{CFFI is the Best™ and GPGME should use it instead of SWIG, , an earlier section}, it is -in fact quite possible to use the GPGME bindings with @uref{http://docs.cython.org/en/latest/index.html, Cython}. In many -cases the benefits may not be obvious since the most computationally +In spite of the apparent incongruence of using Python bindings to a C +interface only to generate more C from the Python; it is in fact quite +possible to use the GPGME bindings with @uref{http://docs.cython.org/en/latest/index.html, Cython}. Though in many cases +the benefits may not be obvious since the most computationally intensive work never leaves the level of the C code with which GPGME itself is interacting with. @@ -2090,9 +2081,9 @@ the @samp{examples/howto/} directory), will take a noticable amount of time to run on most systems where the public keybox or keyring contains a few thousand public keys. -Earlier in the evening I ran that script on my laptop, as I tend to do -periodically and timed it using @samp{time} utility, with the following -results: +Earlier in the evening, prior to starting this section, I ran that +script on my laptop; as I tend to do periodically and timed it using +@samp{time} utility, with the following results: @example bash-4.4$ time keycount.py @@ -2110,10 +2101,10 @@ bash-4.4$ Sometime after that I imported another key and followed it with a little test of Cython. This test was kept fairly basic, essentially -lifting the material from the initial @uref{http://docs.cython.org/en/latest/src/tutorial/cython_tutorial.html#cython-hello-world, Cython Hello World tutorial} to -demonstrate compiling Python code to C. The first step was to take -the example key counting code quoted previously, essentially from the -importing of the @samp{gpg} module to the end of the script: +lifting the material from the @uref{http://docs.cython.org/en/latest/src/tutorial/cython_tutorial.html, Cython Basic Tutorial} to demonstrate +compiling Python code to C. The first step was to take the example +key counting code quoted previously, essentially from the importing of +the @samp{gpg} module to the end of the script: @example import gpg diff --git a/lang/python/docs/gpgme-python-howto.org b/lang/python/docs/gpgme-python-howto.org index 95b19343..0d7f9b4e 100644 --- a/lang/python/docs/gpgme-python-howto.org +++ b/lang/python/docs/gpgme-python-howto.org @@ -438,16 +438,6 @@ running into trouble with "ifdefs" then you'll know what sort of things are lacking. That doesn't even take into account the amount of work saved via SWIG's code generation techniques either. -There's a greater likelihood of turning to Cython to add something to -these bindings at this point than there is of turning to CFFI. Except -that there's little reason to do so when the C code in question either -already exists or could be produced fairly quickly by the far more -expedient means of asking either [[https://gnupg.org/people/index.html#sec-1-1][Werner]], [[https://gnupg.org/people/index.html#sec-1-3][Niibe]] or [[https://gnupg.org/people/index.html#sec-1-6][Andre]] to write -whatever was missing. Perhaps even [[https://gnupg.org/people/index.html#sec-1-4][Jussi]], but there shouldn't be any -need for these bindings to interface directly with his work and for -much the same reasons as we recommend people not call libgcrypt -directly unless they know what they're doing. - * Fundamentals :PROPERTIES: @@ -1981,9 +1971,10 @@ c.key_sign(key, uids=uid, expires_in=2764800) :CUSTOM_ID: cython :END: -In spite of my near facetious commentary in [[#snafu-cffi][an earlier section]], it is -in fact quite possible to use the GPGME bindings with [[http://docs.cython.org/en/latest/index.html][Cython]]. In many -cases the benefits may not be obvious since the most computationally +In spite of the apparent incongruence of using Python bindings to a C +interface only to generate more C from the Python; it is in fact quite +possible to use the GPGME bindings with [[http://docs.cython.org/en/latest/index.html][Cython]]. Though in many cases +the benefits may not be obvious since the most computationally intensive work never leaves the level of the C code with which GPGME itself is interacting with. @@ -1995,9 +1986,9 @@ the =examples/howto/= directory), will take a noticable amount of time to run on most systems where the public keybox or keyring contains a few thousand public keys. -Earlier in the evening I ran that script on my laptop, as I tend to do -periodically and timed it using =time= utility, with the following -results: +Earlier in the evening, prior to starting this section, I ran that +script on my laptop; as I tend to do periodically and timed it using +=time= utility, with the following results: #+BEGIN_SRC shell bash-4.4$ time keycount.py @@ -2015,10 +2006,10 @@ results: Sometime after that I imported another key and followed it with a little test of Cython. This test was kept fairly basic, essentially -lifting the material from the initial [[http://docs.cython.org/en/latest/src/tutorial/cython_tutorial.html#cython-hello-world][Cython Hello World tutorial]] to -demonstrate compiling Python code to C. The first step was to take -the example key counting code quoted previously, essentially from the -importing of the =gpg= module to the end of the script: +lifting the material from the [[http://docs.cython.org/en/latest/src/tutorial/cython_tutorial.html][Cython Basic Tutorial]] to demonstrate +compiling Python code to C. The first step was to take the example +key counting code quoted previously, essentially from the importing of +the =gpg= module to the end of the script: #+BEGIN_SRC python -i import gpg