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

docs: python bindings

Browse Source 
* Tightened up the docs a little bit, updated the "what's new"
  section, dropped the "-draft" version in preparation for GPGME
  1.12.0's release.
* Exported another .texi version (and updated the draft copies to this
  commit (which ought to be 1.11.1-beta313).

Signed-off-by: Ben McGinnes <ben@adversary.org>
This commit is contained in:
Ben McGinnes 2018-10-01 02:10:03 +10:00
parent 837a476053
commit 76bdfabb05
2 changed files with 122 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

97
doc/gpgme-python-howto.texi
View File

@ -79,6 +79,7 @@ Known Issues
* Multiple installations::
* Won't Work With Windows::
* CFFI is the Best™ and GPGME should use it instead of SWIG::
* Virtualised Environments::
Fundamentals
@ -168,7 +169,7 @@ Copyright and Licensing
@item Version:
@tab 0.1.4
@item GPGME Version:
@tab 1.12.0-draft
@tab 1.12.0
@item Author:
@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org>
@item Author GPG Key:
@ -292,12 +293,20 @@ 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.
others and testing the publishing of the document itself. Renamed
the file at around the same time.
@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}.
@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
@ -487,6 +496,12 @@ quite high that at least the first one and maybe two of those will
already be installed.
@end enumerate
Note that, as with Cython, some of the planned additions to the
@ref{Advanced or Experimental Use Cases, , Advanced} section, will bring with them additional requirements. Most
of these will be fairly well known and commonly installed ones,
however, which are in many cases likely to have already been installed
on many systems or be familiar to Python programmers.
@node Installation
@section Installation
@ -533,6 +548,7 @@ they be encountered.
* Multiple installations::
* Won't Work With Windows::
* CFFI is the Best™ and GPGME should use it instead of SWIG::
* Virtualised Environments::
@end menu
@node Breaking Builds
@ -727,6 +743,70 @@ 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.
@node Virtualised Environments
@subsection Virtualised Environments
It is fairly common practice amongst Python developers to, as much as
possible, use packages like virtualenv to keep various things that are
to be installed from interfering with each other. Given how much of
the GPGME bindings is often at odds with the usual pythonic way of
doing things, it stands to reason that this would be called into
question too.
As it happens the answer as to whether or not the bindings can be used
with virtualenv, the answer is both yes and no.
In general we recommend installing to the relevant path and matching
prefix of GPGME itself. Which means that when GPGME, and ideally the
rest of the GnuPG stack, is installed to a prefix like @samp{/usr/local} or
@samp{/opt/local} then the bindings would need to be installed to the main
Python installation and not a virtualised abstraction. Attempts to
separate the two in the past have been known to cause weird and
intermittent errors ranging from minor annoyances to complete failures
in the build process.
As a consequence we only recommend building with and installing to the
main Python installations within the same prefix as GPGME is installed
to or which are found by GPGME's configuration stage immediately prior
to running the make commands. Which is exactly what the compiling and
installing process of GPGME does by default.
Once that is done, however, it appears that a copy the compiled module
may be installed into a virtualenv of the same major and minor version
matching the build. Alternatively it is possible to utilise a
@samp{sites.pth} file in the @samp{site-packages/} directory of a viertualenv
installation, which links back to the system installations
corresponding directory in order to import anything installed system
wide. This may or may not be appropriate on a case by case basis.
Though extensive testing of either of these options is not yet
complete, preliminary testing of them indicates that both are viable
as long as the main installation is complete. Which means that
certain other options normally restricted to virtual environments are
also available, including integration with pythonic test suites
(e.g. @uref{https://docs.pytest.org/en/latest/index.html, pytest}) and other large projects.
That said, it is worth reiterating the warning regarding non-standard
installations. If one were to attempt to install the bindings only to
a virtual environment without somehow also including the full GnuPG
stack (or enough of it as to include GPGME) then it is highly likely
that errors would be encountered at some point and more than a little
likely that the build process itself would break.
If a degree of separation from the main operating system is still
required in spite of these warnings, then consider other forms of
virtualisation. Either a virtual machine (e.g. @uref{https://www.virtualbox.org/, VirtualBox}), a
hardware emulation layer (e.g. @uref{https://www.qemu.org/, QEMU}) or an application container
(e.g. @uref{https://www.docker.com/why-docker, Docker}).
Finally it should be noted that the limited tests conducted thus far
have been using the @samp{virtualenv} command in a new directory to create
the virtual python environment. As opposed to the standard @samp{python3
-m venv} and it is possible that this will make a difference depending
on the system and version of Python in use. Another option is to run
the command @samp{python3 -m virtualenv /path/to/install/virtual/thingy}
instead.
@node Fundamentals
@chapter Fundamentals
@ -875,6 +955,13 @@ print("""
""".format(secnum, pubnum))
@end example
@strong{NOTE:} The @ref{C plus Python plus SWIG plus Cython, , Cython} introduction in the @ref{Advanced or Experimental Use Cases, , Advanced and Experimental}
section uses this same key counting code with Cython to demonstrate
some areas where Cython can improve performance even with the
bindings. Users with large public keyrings or keyboxes, for instance,
should consider these options if they are comfortable with using
Cython.
@node Get key
@section Get key
@ -2826,6 +2913,12 @@ existing code and to detect Cython's use. The latter comes from the
@node Miscellaneous extras and work-arounds
@chapter Miscellaneous extras and work-arounds
Most of the things in the following sections are here simply because
there was no better place to put them, even though some are only
peripherally related to the GPGME Python bindings. Some are also
workarounds for functions not integrated with GPGME as yet. This is
especially true of the first of these, dealing with @ref{Group lines, , group lines}.
@menu
* Group lines::
* Keyserver access for Python::

29
lang/python/docs/gpgme-python-howto.org
View File

@ -16,7 +16,7 @@
:END:
| Version: | 0.1.4 |
| GPGME Version: | 1.12.0-draft |
| GPGME Version: | 1.12.0 |
| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org> |
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D |
| Language: | Australian English, British English |
@ -128,10 +128,16 @@ The bullet points of new additiions are:
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.
others and testing the publishing of the document itself. Renamed
the file at around the same time.
- 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]].
- 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
@ -320,6 +326,12 @@ a significant advantage in some way.
quite high that at least the first one and maybe two of those will
already be installed.
Note that, as with Cython, some of the planned additions to the
[[#advanced-use][Advanced]] section, will bring with them additional requirements. Most
of these will be fairly well known and commonly installed ones,
however, which are in many cases likely to have already been installed
on many systems or be familiar to Python programmers.
** Installation
:PROPERTIES:
@ -777,6 +789,13 @@ print("""
""".format(secnum, pubnum))
#+END_SRC
*NOTE:* The [[#cython][Cython]] introduction in the [[#advanced-use][Advanced and Experimental]]
section uses this same key counting code with Cython to demonstrate
some areas where Cython can improve performance even with the
bindings. Users with large public keyrings or keyboxes, for instance,
should consider these options if they are comfortable with using
Cython.
** Get key
:PROPERTIES:
@ -2770,6 +2789,12 @@ existing code and to detect Cython's use. The latter comes from the
:CUSTOM_ID: cheats-and-hacks
:END:
Most of the things in the following sections are here simply because
there was no better place to put them, even though some are only
peripherally related to the GPGME Python bindings. Some are also
workarounds for functions not integrated with GPGME as yet. This is
especially true of the first of these, dealing with [[#group-lines][group lines]].
** Group lines
:PROPERTIES: