[git] GPGME - branch, ben/docs/2018-03, updated. gpgme-1.10.0-91-g1d05e6a

[by Ben McGinnes]

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  1d05e6aa4ea467c8c5926b827cfcfba357d03312 (commit)
      from  b35aaef7a3b793b8f6f5b42596c0a6a51e87f78c (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 1d05e6aa4ea467c8c5926b827cfcfba357d03312
Author: Ben McGinnes <ben at adversary.org>
Date:   Thu Mar 15 12:14:29 2018 +1100

    doc: python bindings howto
    
    * Added c.get_key instructions and examples.

diff --git a/lang/python/docs/GPGMEpythonHOWTOen.org b/lang/python/docs/GPGMEpythonHOWTOen.org
index dca6999..8f57adb 100644
--- a/lang/python/docs/GPGMEpythonHOWTOen.org
+++ b/lang/python/docs/GPGMEpythonHOWTOen.org
@@ -345,35 +345,78 @@
    #+end_src
 
 
-** Counting keys
+*** Counting keys
+    :PROPERTIES:
+    :CUSTOM_ID: howto-keys-counting
+    :END:
+
+    Counting the number of keys in your public keybox (=pubring.kbx=),
+    the format which has superceded the old keyring format
+    (=pubring.gpg= and =secring.gpg=), or the number of secret keys is
+    a very simple task.
+
+    #+begin_src python
+      import gpg
+
+      c = gpg.Context()
+      seckeys = c.keylist(pattern=None, secret=True)
+      pubkeys = c.keylist(pattern=None, secret=False)
+
+      seclist = list(seckeys)
+      secnum = len(seclist)
+
+      publist = list(pubkeys)
+      pubnum = len(publist)
+
+      print("""
+      Number of secret keys:  {0}
+      Number of public keys:  {1}
+      """.format(secnum, pubnum)
+    #+end_src
+
+
+** Get key
    :PROPERTIES:
-   :CUSTOM_ID: howto-keys-counting
+   :CUSTOM_ID: howto-get-key
    :END:
 
-   Counting the number of keys in your public keybox (=pubring.kbx=),
-   the format which has superceded the old keyring format
-   (=pubring.gpg= and =secring.gpg=), or the number of secret keys is
-   a very simple task.
+   An alternative method of getting a single key via its fingerprint
+   is available directly within a Context with =Context().get_key=.
+   This is the preferred method of selecting a key in order to modify
+   it, sign or certify it and for obtaining relevant data about a
+   single key as a part of other functions; when verifying a signature
+   made by that key, for instance.
+
+   By default this method will select public keys, but it can select
+   secret keys as well.
+
+   This first example demonstrates selecting the current key of Werner
+   Koch, which is due to expire at the end of 2018:
 
    #+begin_src python
      import gpg
 
-     c = gpg.Context()
-     seckeys = c.keylist(pattern=None, secret=True)
-     pubkeys = c.keylist(pattern=None, secret=False)
+     fingerprint = "80615870F5BAD690333686D0F2AD85AC1E42B367"
+     key = gpg.Context().get_key(fingerprint)
+   #+end_src
 
-     seclist = list(seckeys)
-     secnum = len(seclist)
+   Whereas this example demonstrates selecting the author's current
+   key with the =secret= key word argument set to =True=:
 
-     publist = list(pubkeys)
-     pubnum = len(publist)
+   #+begin_src python
+     import gpg
 
-     print("""
-     Number of secret keys:  {0}
-     Number of public keys:  {1}
-     """.format(secnum, pubnum)
+     fingerprint = "DB4724E6FA4286C92B4E55C4321E4E2373590E5D"
+     key = gpg.Context().get_key(fingerprint, secret=True)
    #+end_src
 
+   It is, of course, quite possible to select expired, disabled and
+   revoked keys with this function, but only to effectively display
+   information about those keys.
+
+   It is also possible to use both unicode or string literals and byte
+   literals with the fingerprint when getting a key in this way.
+
 
 * Basic Functions
   :PROPERTIES:

-----------------------------------------------------------------------

Summary of changes:
 lang/python/docs/GPGMEpythonHOWTOen.org | 77 +++++++++++++++++++++++++--------
 1 file changed, 60 insertions(+), 17 deletions(-)


hooks/post-receive
-- 
GnuPG Made Easy
http://git.gnupg.org