docs: python bindings HOWTO
authorBen McGinnes <ben@adversary.org>
Tue, 28 Aug 2018 18:14:24 +0000 (04:14 +1000)
committerBen McGinnes <ben@adversary.org>
Tue, 28 Aug 2018 18:14:24 +0000 (04:14 +1000)
* Finished CFFI vs SWIG bit in known issues.
* tidied up some of the structure.
* Fixed some minor errors and links.

lang/python/docs/GPGMEpythonHOWTOen.org

index ffe5034..84ba6a3 100644 (file)
@@ -15,7 +15,7 @@
   :CUSTOM_ID: intro
   :END:
 
-| Version:        | 0.1.3                                    |
+| Version:        | 0.1.4                                    |
 | Author:         | Ben McGinnes <ben@gnupg.org>             |
 | Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
 | Language:       | Australian English, British English      |
@@ -207,6 +207,9 @@ include a package in PyPI which actually built correctly would require
 either statically built libraries for every architecture bundled with
 it or a full implementation of C for each architecture.
 
+See the additional notes regarding CFFI and SWIG at the end of this
+section for further details.
+
 
 ** Requirements
    :PROPERTIES:
@@ -217,7 +220,7 @@ The GPGME Python bindings only have three requirements:
 
 1. A suitable version of Python 2 or Python 3.  With Python 2 that
    means Python 2.7 and with Python 3 that means Python 3.4 or higher.
-2. [[https://www.swig.org][SWIG]]..
+2. [[https://www.swig.org][SWIG]].
 3. GPGME itself.  Which also means that all of GPGME's dependencies
    must be installed too.
 
@@ -243,7 +246,7 @@ For Python 2 it checks for these executables in this order: =python=,
 =python2= and =python2.7=.
 
 For Python 3 it checks for these executables in this order: =python3=,
-=python3.6=, =python3.5=, =python3.4= and =python3.7=.[fn:4]
+=python3.6=, =python3.5=, =python3.4= and =python3.7=.[fn:3]
 
 
 *** Installing GPGME
@@ -290,7 +293,7 @@ build directory missing a lot of expected files.  Even when this
 occurs, the solution is actually quite simple and will always work.
 
 That solution is simply to run the following commands as either the
-*root* user or prepended with =sudo -H=[fn:5] in the =lang/python/=
+*root* user or prepended with =sudo -H=[fn:4] in the =lang/python/=
 directory:
 
 #+BEGIN_SRC shell
@@ -398,7 +401,7 @@ ongoing.
     :CUSTOM_ID: snafu-foad
     :END:
 
-There are many reasons for favouring CFFI and proponents of it are
+There are many reasons for favouring [[https://cffi.readthedocs.io/en/latest/overview.html][CFFI]] and proponents of it are
 quite happy to repeat these things as if all it would take to switch
 from SWIG to CFFI is repeating that list as if it were a new concept.
 
@@ -421,6 +424,14 @@ project to switch to CFFI then rather than just insisting that it
 should, I'd suggest you volunteer to bring CFFI up to the level this
 project needs.
 
+If you're actually seriously considering doing so, then I'd suggest
+taking the =gpgme-tool.c= file in the GPGME =src/= directory and
+getting that to work with any of the CFFI API methods (not the ABI
+methods, they'll work with pretty much anything).  When you start
+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.
+
 
 * Fundamentals
   :PROPERTIES:
@@ -1167,7 +1178,7 @@ Encrypting to multiple keys essentially just expands upon the key
 selection process and the recipients from the previous examples.
 
 The following example encrypts a message (=text=) to everyone with an
-email address on the =gnupg.org= domain,[fn:3] but does /not/ encrypt
+email address on the =gnupg.org= domain,[fn:5] but does /not/ encrypt
 to a default key or other key which is configured to normally encrypt
 to.
 
@@ -2017,19 +2028,19 @@ PURPOSE.
 
 [fn:2] The =lang/python/docs/= directory in the GPGME source.
 
-[fn:3] You probably don't really want to do this.  Searching the
-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:4] As Python 3.7 is a very recent release, it is not given
+[fn:3] As Python 3.7 is a very recent release, it is not given
 priority over 3.6 yet, but will probably be prioritised by the release
 of Python 3.7.2.
 
-[fn:5] Yes, even if you use virtualenv with everything you do in
+[fn:4] Yes, even if you use virtualenv with everything you do in
 Python.  If you want to install this module as just your user account
 then you will need to manually configure, compile and install the
 /entire/ GnuPG stack as that user as well.  This includes libraries
 which are not often installed that way.  It can be done and there are
 circumstances under which it is worthwhile, but generally only on
 POSIX systems which utilise single user mode (some even require it).
+
+[fn:5] You probably don't really want to do this.  Searching the
+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.