[git] GPGME - branch, ben/docs/2018-03, updated. gpgme-1.10.0-59-ga98f2c5
by Ben McGinnes
cvs at cvs.gnupg.org
Thu Mar 8 05:45:37 CET 2018
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GnuPG Made Easy".
The branch, ben/docs/2018-03 has been updated
via a98f2c556fe6e33a9cd38279e64e4b09f05cc675 (commit)
via e8adab68f8c0cd865ff220f06dfaff7fe183e8a1 (commit)
from 47d401d159852ea08e90af21d91bb4b93be9000d (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit a98f2c556fe6e33a9cd38279e64e4b09f05cc675
Author: Ben McGinnes <ben at adversary.org>
Date: Thu Mar 8 15:23:05 2018 +1100
doc-howto: fundamental aspects of GPGME vs Python
* Added a section for those pythonistas who are too used to web
programming. Stressed that it's not simply not RESTful, it's not
even REST-like.
* Letting me move on to drawing a very loose parallel between a
session and a context. The differences should become obvious in the
subsequent sections.
diff --git a/lang/python/docs/GPGMEpythonHOWTOen.org b/lang/python/docs/GPGMEpythonHOWTOen.org
index 2803861..e7dc53d 100644
--- a/lang/python/docs/GPGMEpythonHOWTOen.org
+++ b/lang/python/docs/GPGMEpythonHOWTOen.org
@@ -1,5 +1,4 @@
#+TITLE: GNU Privacy Guard (GnuPG) Made Easy Python Bindings HOWTO (English)
-
#+LATEX_COMPILER: xelatex
#+LATEX_CLASS: article
#+LATEX_CLASS_OPTIONS: [12pt]
@@ -200,6 +199,61 @@ Python bindings to programmatically leverage the GPGME library.
source.
+* Fundamentals
+ :PROPERTIES:
+ :CUSTOM_ID: howto-fund-a-mental
+ :END:
+
+ Before we can get to the fun stuff, there are a few matters
+ regarding GPGME's design which hold true whether you're dealing with
+ the C code directly or these Python bindings.
+
+** No REST
+ :PROPERTIES:
+ :CUSTOM_ID: no-rest-for-the-wicked
+ :END:
+
+ The first part of which is or will be fairly blatantly obvious upon
+ viewing the first example, but it's worth reiterating anyway. That
+ being that this API is /*not*/ a REST API. Nor indeed could it
+ ever be one.
+
+ Most, if not all, Python programmers (and not just Python
+ programmers) know how easy it is to work with a RESTful API. In
+ fact they've become so popular that many other APIs attempt to
+ emulate REST-like behaviour as much as they are able. Right down
+ to the use of JSON formatted output to facilitate the use of their
+ API without having to retrain developers.
+
+ This API does not do that. It would not be able to do that and
+ also provide access to the entire C API on which it's built. It
+ does, however, provide a very pythonic interface on top of the
+ direct bindings and it's this pythonic layer with which this HOWTO
+ deals with.
+
+** Context
+ :PROPERTIES:
+ :CUSTOM_ID: howto-get-context
+ :END:
+
+ One of the reasons which prevents this API from being RESTful is
+ that most operations require more than one instruction to the API
+ to perform the task. Sure, there are certain functions which can
+ be performed simultaneously, particularly if the result known or
+ strongly anticipated (e.g selecting and encrypting to a key known
+ to be in the public keybox).
+
+ There are many more, however, which cannot be manipulated so
+ readily: they must be performed in a specific sequence and the
+ result of one operation has a direct bearing on the outcome of
+ subsequent operations. Not merely by generating an error either.
+
+ When dealing with this type of persistant state on the web, full of
+ both the RESTful and REST-like, it's most commonly referred to as a
+ session. In GPGME, however, it is called a context and every
+ operation type has one.
+
+
* Copyright and Licensing
:PROPERTIES:
:CUSTOM_ID: copyright-and-license
commit e8adab68f8c0cd865ff220f06dfaff7fe183e8a1
Author: Ben McGinnes <ben at adversary.org>
Date: Thu Mar 8 14:13:00 2018 +1100
doc: Added multiple TODOs for inclusion in the HOWTO
* Some instructions to include are fairly obvious; as with encryption,
decryption and signature verification.
* Some are a little less obvious.
* This includes the requests received to specifically include subkey
management (adding and revoking subkeys on a primary key that's
being retained.
* Added the UID equivalents to the list, as well as key selection
matters (and may or may not include something for handling group
lines since that involves wrapping a CLI binary).
* Key control documentation and examples requested by Mike Ingle of
confidantmail.org.
diff --git a/lang/python/docs/TODO.org b/lang/python/docs/TODO.org
index 4e067df..897c617 100644
--- a/lang/python/docs/TODO.org
+++ b/lang/python/docs/TODO.org
@@ -28,11 +28,13 @@
to produce reST versions via Pandoc and DITA XML can be reached
through converting to either Markdown or XHTML first.
-** TODO Documentation HOWTO
+** STARTED Documentation HOWTO
:PROPERTIES:
:CUSTOM_ID: todo-docs-howto
:END:
+ - State "STARTED" from "TODO" [2018-03-08 Thu 13:59] \\
+ Started yesterday.
Write a HOWTO style guide for the current Python bindings.
*** DONE Start python bindings HOWTO
@@ -41,6 +43,46 @@
:CUSTOM_ID: howto-start
:END:
+*** TODO Include certain specific instructions in the HOWTO
+ :PROPERTIES:
+ :CUSTOM_ID: howto-requests
+ :END:
+
+ Some functions can be worked out from the handful of examples
+ available, but many more can't and I've already begun receiving
+ requests for certain functions to be explained.
+
+**** TODO Standard scenarios
+ :PROPERTIES:
+ :CUSTOM_ID: howto-the-basics
+ :END:
+
+ What everyone expects: encryption, decryption, signing and verifying.
+
+**** TODO Key control
+ :PROPERTIES:
+ :CUSTOM_ID: howto-key-control
+ :END:
+
+ Generating keys, adding subkeys, revoking subkeys (and keeping
+ the cert key), adding and revoking UIDs, signing/certifying keys.
+
+**** TODO Key control
+ :PROPERTIES:
+ :CUSTOM_ID: howto-key-selection
+ :END:
+
+ Selecting keys to encrypt to or manipulate in other ways (e.g. as
+ with key control or the basics).
+
+**** TODO S/MIME
+ :PROPERTIES:
+ :CUSTOM_ID: howto-s-mime
+ :END:
+
+ Eventually add some of this, but it the OpenPGP details are far
+ more important at the moment.
+
** TODO Documentation SWIG
:PROPERTIES:
:CUSTOM_ID: todo-docs-swig
-----------------------------------------------------------------------
Summary of changes:
lang/python/docs/GPGMEpythonHOWTOen.org | 56 ++++++++++++++++++++++++++++++++-
lang/python/docs/TODO.org | 44 +++++++++++++++++++++++++-
2 files changed, 98 insertions(+), 2 deletions(-)
hooks/post-receive
--
GnuPG Made Easy
http://git.gnupg.org
More information about the Gnupg-commits
mailing list