From 3b056a01a252bb72df5744409ba494e1a6e54d31 Mon Sep 17 00:00:00 2001 From: Ben McGinnes Date: Sat, 1 Dec 2018 07:45:50 +1100 Subject: [PATCH] python: documentation * Added long description to setup.py.in. * Added maintenance mode details with clarification for what type of things would be a bug as far as MM is concerned and what wouldn't be. ** Includes a not too subtle hint directed towards the donations page. * Miscellaneous tightening of documentation. Signed-off-by: Ben McGinnes --- lang/python/doc/rst/gpgme-python-howto.rst | 48 ++++--- lang/python/doc/rst/index.rst | 3 + lang/python/doc/rst/maintenance-mode.rst | 95 ++++++++++++++ lang/python/doc/rst/short-history.rst | 22 ++++ lang/python/doc/rst/what-is-new.rst | 12 +- lang/python/doc/rst/what-was-new.rst | 7 +- lang/python/doc/src/gpgme-python-howto | 42 +++--- lang/python/doc/src/index | 1 + lang/python/doc/src/maintenance-mode | 93 +++++++++++++ lang/python/doc/src/short-history | 16 ++- lang/python/doc/src/what-is-new | 9 +- lang/python/doc/src/what-was-new | 4 +- .../doc/texinfo/gpgme-python-howto.texi | 46 ++++--- lang/python/doc/texinfo/index.texi | 4 + lang/python/doc/texinfo/maintenance-mode.texi | 123 ++++++++++++++++++ lang/python/doc/texinfo/short-history.texi | 15 +++ lang/python/doc/texinfo/what-is-new.texi | 12 +- lang/python/doc/texinfo/what-was-new.texi | 6 +- lang/python/setup.py.in | 108 +++++++++------ 19 files changed, 542 insertions(+), 124 deletions(-) create mode 100644 lang/python/doc/rst/maintenance-mode.rst create mode 100644 lang/python/doc/src/maintenance-mode create mode 100644 lang/python/doc/texinfo/maintenance-mode.texi diff --git a/lang/python/doc/rst/gpgme-python-howto.rst b/lang/python/doc/rst/gpgme-python-howto.rst index dae4c646..d1cb3fd3 100644 --- a/lang/python/doc/rst/gpgme-python-howto.rst +++ b/lang/python/doc/rst/gpgme-python-howto.rst @@ -13,8 +13,11 @@ Introduction | | e/index.html#sec-1-5>`__ | | | | +-----------------------------------+-----------------------------------+ -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 | -| | 3590E5D | +| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 | +| | 73590E5D `__ | +-----------------------------------+-----------------------------------+ | Language: | Australian English, British | | | English | @@ -3009,34 +3012,37 @@ Draft Editions of this HOWTO Draft editions of this HOWTO may be periodically available directly from the author at any of the following URLs: -- `GPGME Python Bindings HOWTO draft (XHTML AWS S3 +- `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL) `__ -- `GPGME Python Bindings HOWTO draft (XHTML AWS S3 no - SSL) `__ -- `GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 - SSL) `__ -- `GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no - SSL) `__ -- `GPGME Python Bindings HOWTO draft (Info file AWS S3 - SSL) `__ -- `GPGME Python Bindings HOWTO draft (Info file AWS S3 no - SSL) `__ -- `GPGME Python Bindings HOWTO draft (reST file AWS S3 - SSL) `__ -- `GPGME Python Bindings HOWTO draft (reST file AWS S3 no - SSL) `__ +- `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no + SS) `__ +- `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 + SSL) `__ +- `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no + SSL) `__ All of these draft versions except for one have been generated from this -document via Emacs `Org mode `__ and `GNU +document via GNU Emacs `Org mode `__ and `GNU Texinfo `__. Though it is likely that the specific `file `__ `version `__ used will be on the same server with the generated output formats. -The one exception is the reStructuredText version, which was converted -using the latest version of Pandoc from the Org mode source file using -either of the following two commands: +The GNU Texinfo and reStructured Text versions ship with the software, +while the GNU Emacs Info verseion is generated from the Texinfo version +using GNU Texinfo or GNU Makeinfo. The Texinfo format is generated from +the original Org mode source file in Org mode itself either within GNU +Emacs or via the command line by invoking Emacs in batch mode: + +.. code:: shell + + emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill + emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill + +The reStructuredText format is also generated from the Org-mode source +file, except it is generated using `Pandoc `__ with +either of the following commands: .. code:: shell diff --git a/lang/python/doc/rst/index.rst b/lang/python/doc/rst/index.rst index 5f736c7e..746391c3 100644 --- a/lang/python/doc/rst/index.rst +++ b/lang/python/doc/rst/index.rst @@ -8,5 +8,8 @@ Contents - `A short history of the project `__ - `What\'s New `__ + + - `Maintenance Mode `__ (from January, 2019) + - `What Was New `__ - `GPGME Python Bindings HOWTO `__ diff --git a/lang/python/doc/rst/maintenance-mode.rst b/lang/python/doc/rst/maintenance-mode.rst new file mode 100644 index 00000000..75cd947a --- /dev/null +++ b/lang/python/doc/rst/maintenance-mode.rst @@ -0,0 +1,95 @@ +.. _maintenance-mode: + +Maintenance Mode from 2019 +========================== + ++-----------------------------------+-----------------------------------+ +| Version: | 0.0.1-draft | ++-----------------------------------+-----------------------------------+ +| GPGME Version: | 1.13.0 | ++-----------------------------------+-----------------------------------+ +| Author: | `Ben | +| | McGinnes `__ | +| | | ++-----------------------------------+-----------------------------------+ +| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 | +| | 73590E5D `__ | ++-----------------------------------+-----------------------------------+ +| Language: | Australian English, British | +| | English | ++-----------------------------------+-----------------------------------+ +| xml:lang: | en-AU, en-GB, en | ++-----------------------------------+-----------------------------------+ + +From the beginning of 2019 the Python bindings to GPGME will enter +maintenance mode, meaning that new features will not be added and only +bug fixes and security fixes will be made. This also means that +documentation beyond that existing at the end of 2018 will not be +developed further except to correct errors. + +Though use of these bindings appears to have been quite well received, +there has been no indication of what demand there is, if any for either +financial backing of the current Python bindings development or support +contracts with g10code GmbH citing the necessity of including the +bindings. + +.. _maintenance-mode-bm: + +Maintainer from 2019 onward +--------------------------- + +How does this affect the position of GnuPG Python Bindings Maintainer? + +Well, I will remain as maintainer of the bindings; but without funding +for that position, the amount of time I will be able to dedicate solely +to this task will be limited and reduced to volunteered time. As with +all volunteered time and effort in free software projects, this will be +subject to numerous external imperatives. + +.. _maintenance-mode-blade-runner: + +Using the Python Bindings from 2019 and beyond +---------------------------------------------- + +For most, if not all, Python developers using these bindings; they will +continue to "just work" the same as they always have. Expansions of +GPGME itself are usually handled by SWIG with the existing code and thus +bindings are generated properly when the bindings are installed +alongside GPGME and when the latter is built from source. + +In the rare circumstances where that is not enough to address some new +addition to GPGME, then that is a bug and thus subject to the +maintenance mode provisions (i.e. it will be fixed following a bug +report being raised and your humble author will need to remember where +the timesheet template was filed, depending on how many years off such +an event is). + +All the GPGME functionality will continue to be accessible via the lower +level, dynamically generated methods which match the GPGME C +documentation. While the more intuitively Pythonic higher level layer +already covers the vast majority of functionality people require with +key generation, signatures, certifications (key signing), encryption, +decryption, verification, validation, trust levels and so on. + +Any wanted features lacking in the Python bindings are usually lacking +because they are missing from GPGME itself (e.g. revoking keys via the +API) and in such cases they are usually deliberately excluded. More + +Any features existing in the dynamically generated layer for which +people want a specific, higher level function included to make it more +Pythonic (e.g. to avoid needing to learn or memorise cryptographic mode +values or GnuPG status code numbers), would be a feature request and +*not* a bug. + +It is still worthwhile requesting it, but the addition of such a feature +would not be guaranteed and provided on a purely volunteer basis. +Expediting such a request would require funding that request. + +Those with a commercial interest in expediting such a feature request +already know how to `expedite +it `__ (use the +message field to state what feature is being requested). diff --git a/lang/python/doc/rst/short-history.rst b/lang/python/doc/rst/short-history.rst index d6f0a5d5..70f9b25e 100644 --- a/lang/python/doc/rst/short-history.rst +++ b/lang/python/doc/rst/short-history.rst @@ -1,6 +1,28 @@ Overview ======== ++-----------------------------------+-----------------------------------+ +| Version: | 0.0.1-draft | ++-----------------------------------+-----------------------------------+ +| GPGME Version: | 1.13.0 | ++-----------------------------------+-----------------------------------+ +| Author: | `Ben | +| | McGinnes `__ | +| | | ++-----------------------------------+-----------------------------------+ +| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 | +| | 73590E5D `__ | ++-----------------------------------+-----------------------------------+ +| Language: | Australian English, British | +| | English | ++-----------------------------------+-----------------------------------+ +| xml:lang: | en-AU, en-GB, en | ++-----------------------------------+-----------------------------------+ + The GPGME Python bindings passed through many hands and numerous phases before, after a fifteen year journey, coming full circle to return to the source. This is a short explanation of that journey. diff --git a/lang/python/doc/rst/what-is-new.rst b/lang/python/doc/rst/what-is-new.rst index 0fca98f2..b3ec06a7 100644 --- a/lang/python/doc/rst/what-is-new.rst +++ b/lang/python/doc/rst/what-is-new.rst @@ -13,8 +13,11 @@ What\'s New | | e/index.html#sec-1-5>`__ | | | | +-----------------------------------+-----------------------------------+ -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 | -| | 3590E5D | +| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 | +| | 73590E5D `__ | +-----------------------------------+-----------------------------------+ | Language: | Australian English, British | | | English | @@ -23,8 +26,7 @@ What\'s New +-----------------------------------+-----------------------------------+ Last time the most obviously new thing was adding the *What\'s New* -section to the HOWTO. Now it\'s moving it out of the HOWTO. Not to -mention expanding on the documentation both generally and considerably. +section to the HOWTO. Now it\'s moving it out of the HOWTO. .. _new-stuff-1-13-0: @@ -41,3 +43,5 @@ Additions since GPGME 1.12.0 include: - Added ``gpg.version.versionintlist`` to make it easier for Python developers to check for a specific version number, even with beta versions (it will drop the \"-betaN\" part). +- Bindings enter `maintenance mode `__ from January, + 2019. diff --git a/lang/python/doc/rst/what-was-new.rst b/lang/python/doc/rst/what-was-new.rst index 23f30828..cc11bbfc 100644 --- a/lang/python/doc/rst/what-was-new.rst +++ b/lang/python/doc/rst/what-was-new.rst @@ -13,8 +13,11 @@ What Was New | | e/index.html#sec-1-5>`__ | | | | +-----------------------------------+-----------------------------------+ -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 | -| | 3590E5D | +| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 | +| | 73590E5D `__ | +-----------------------------------+-----------------------------------+ | Language: | Australian English, British | | | English | diff --git a/lang/python/doc/src/gpgme-python-howto b/lang/python/doc/src/gpgme-python-howto index 4b02a933..fe1fc2b4 100644 --- a/lang/python/doc/src/gpgme-python-howto +++ b/lang/python/doc/src/gpgme-python-howto @@ -17,10 +17,11 @@ | Version: | 0.1.4 | | GPGME Version: | 1.12.1 | -| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] | -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | +| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> | +| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] | | Language: | Australian English, British English | | Language codes: | en-AU, en-GB, en | +#+TBLFM: This document provides basic instruction in how to use the GPGME Python bindings to programmatically leverage the GPGME library. @@ -2716,6 +2717,7 @@ Though neither requests nor pendulum are required modules for using the GPGME Python bindings, they are both highly recommended more generally. + * Advanced or Experimental Use Cases :PROPERTIES: :CUSTOM_ID: advanced-use @@ -3083,23 +3085,31 @@ Copyright (C) The GnuPG Project, 2018. Draft editions of this HOWTO may be periodically available directly from the author at any of the following URLs: -- [[https://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML AWS S3 SSL)]] -- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML AWS S3 no SSL)]] -- [[https://files.au.adversary.org/crypto/gpgme-python-howto.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 SSL)]] -- [[http://files.au.adversary.org/crypto/gpgme-python-howto.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no SSL)]] -- [[https://files.au.adversary.org/crypto/gpgme-python-howto.info][GPGME Python Bindings HOWTO draft (Info file AWS S3 SSL)]] -- [[http://files.au.adversary.org/crypto/gpgme-python-howto.info][GPGME Python Bindings HOWTO draft (Info file AWS S3 no SSL)]] -- [[https://files.au.adversary.org/crypto/gpgme-python-howto.rst][GPGME Python Bindings HOWTO draft (reST file AWS S3 SSL)]] -- [[http://files.au.adversary.org/crypto/gpgme-python-howto.rst][GPGME Python Bindings HOWTO draft (reST file AWS S3 no SSL)]] +- [[https://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)]] +- [[http://files.au.adversary.org/crypto/gpgme-python-howto.html][GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)]] +- [[https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)]] +- [[http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html][GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)]] All of these draft versions except for one have been generated from -this document via Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is likely -that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server with -the generated output formats. +this document via GNU Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is +likely that the specific [[https://files.au.adversary.org/crypto/gpgme-python-howto][file]] [[http://files.au.adversary.org/crypto/gpgme-python-howto.org][version]] used will be on the same server +with the generated output formats. -The one exception is the reStructuredText version, which was converted -using the latest version of Pandoc from the Org mode source file using -either of the following two commands: +The GNU Texinfo and reStructured Text versions ship with the software, +while the GNU Emacs Info verseion is generated from the Texinfo +version using GNU Texinfo or GNU Makeinfo. The Texinfo format is +generated from the original Org mode source file in Org mode itself +either within GNU Emacs or via the command line by invoking Emacs in +batch mode: + +#+BEGIN_SRC shell + emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill + emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill +#+END_SRC + +The reStructuredText format is also generated from the Org-mode source +file, except it is generated using [[https://pandoc.org][Pandoc]] with either of the following +commands: #+BEGIN_SRC shell pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org diff --git a/lang/python/doc/src/index b/lang/python/doc/src/index index ce347ea7..ec13c9a1 100644 --- a/lang/python/doc/src/index +++ b/lang/python/doc/src/index @@ -24,5 +24,6 @@ - [[file:short-history][A short history of the project]] - [[file:what-is-new][What's New]] + - [[file:maintenance-mode][Maintenance Mode]] (from January, 2019) - [[file:what-was-new][What Was New]] - [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]] diff --git a/lang/python/doc/src/maintenance-mode b/lang/python/doc/src/maintenance-mode new file mode 100644 index 00000000..ef56e4e6 --- /dev/null +++ b/lang/python/doc/src/maintenance-mode @@ -0,0 +1,93 @@ +# -*- mode: org -*- +#+TITLE: Maintenance Mode +#+AUTHOR: Ben McGinnes +#+LATEX_COMPILER: xelatex +#+LATEX_CLASS: article +#+LATEX_CLASS_OPTIONS: [12pt] +#+LATEX_HEADER: \usepackage{xltxtra} +#+LATEX_HEADER: \usepackage[margin=1in]{geometry} +#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman} +#+LATEX_HEADER: \author{Ben McGinnes } + + +* Maintenance Mode from 2019 + :PROPERTIES: + :CUSTOM_ID: maintenance-mode + :END: + +| Version: | 0.0.1-draft | +| GPGME Version: | 1.13.0 | +| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> | +| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] | +| Language: | Australian English, British English | +| xml:lang: | en-AU, en-GB, en | + +From the beginning of 2019 the Python bindings to GPGME will enter +maintenance mode, meaning that new features will not be added and only +bug fixes and security fixes will be made. This also means that +documentation beyond that existing at the end of 2018 will not be +developed further except to correct errors. + +Though use of these bindings appears to have been quite well received, +there has been no indication of what demand there is, if any for +either financial backing of the current Python bindings development or +support contracts with g10code GmbH citing the necessity of including +the bindings. + + +** Maintainer from 2019 onward + :PROPERTIES: + :CUSTOM_ID: maintenance-mode-bm + :END: + +How does this affect the position of GnuPG Python Bindings Maintainer? + +Well, I will remain as maintainer of the bindings; but without funding +for that position, the amount of time I will be able to dedicate +solely to this task will be limited and reduced to volunteered time. +As with all volunteered time and effort in free software projects, +this will be subject to numerous external imperatives. + + +** Using the Python Bindings from 2019 and beyond + :PROPERTIES: + :CUSTOM_ID: maintenance-mode-blade-runner + :END: + +For most, if not all, Python developers using these bindings; they +will continue to “just work” the same as they always have. Expansions +of GPGME itself are usually handled by SWIG with the existing code and +thus bindings are generated properly when the bindings are installed +alongside GPGME and when the latter is built from source. + +In the rare circumstances where that is not enough to address some new +addition to GPGME, then that is a bug and thus subject to the +maintenance mode provisions (i.e. it will be fixed following a bug +report being raised and your humble author will need to remember where +the timesheet template was filed, depending on how many years off such +an event is). + +All the GPGME functionality will continue to be accessible via the +lower level, dynamically generated methods which match the GPGME C +documentation. While the more intuitively Pythonic higher level layer +already covers the vast majority of functionality people require with +key generation, signatures, certifications (key signing), encryption, +decryption, verification, validation, trust levels and so on. + +Any wanted features lacking in the Python bindings are usually lacking +because they are missing from GPGME itself (e.g. revoking keys via the +API) and in such cases they are usually deliberately excluded. More + +Any features existing in the dynamically generated layer for which +people want a specific, higher level function included to make it more +Pythonic (e.g. to avoid needing to learn or memorise cryptographic +mode values or GnuPG status code numbers), would be a feature request +and /not/ a bug. + +It is still worthwhile requesting it, but the addition of such a +feature would not be guaranteed and provided on a purely volunteer +basis. Expediting such a request would require funding that request. + +Those with a commercial interest in expediting such a feature request +already know how to [[https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset][expedite it]] (use the message field to state what +feature is being requested). diff --git a/lang/python/doc/src/short-history b/lang/python/doc/src/short-history index 6c5c96ec..c91f0298 100644 --- a/lang/python/doc/src/short-history +++ b/lang/python/doc/src/short-history @@ -5,13 +5,20 @@ #+LATEX_CLASS_OPTIONS: [12pt] #+LATEX_HEADER: \usepackage{xltxtra} #+LATEX_HEADER: \usepackage[margin=1in]{geometry} -#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman} +#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman} * Overview :PROPERTIES: :CUSTOM_ID: overview :END: +| Version: | 0.0.1-draft | +| GPGME Version: | 1.13.0 | +| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> | +| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] | +| Language: | Australian English, British English | +| xml:lang: | en-AU, en-GB, en | + The GPGME Python bindings passed through many hands and numerous phases before, after a fifteen year journey, coming full circle to return to the source. This is a short explanation of that journey. @@ -27,6 +34,7 @@ return to the source. This is a short explanation of that journey. supporting it, though he left his work available on his Gopher site. + ** Keeping the flame alive :PROPERTIES: :CUSTOM_ID: keeping-the-flame-alive @@ -38,6 +46,7 @@ return to the source. This is a short explanation of that journey. but the current authors do hope he is well. We're assuming (or hoping) that life did what life does and made continuing untenable. + ** Passing the torch :PROPERTIES: :CUSTOM_ID: passing-the-torch @@ -50,6 +59,7 @@ return to the source. This is a short explanation of that journey. the original PyME release in Python 2.6 and 2.7 (available via PyPI). + ** Coming full circle :PROPERTIES: :CUSTOM_ID: ouroboros @@ -74,6 +84,7 @@ return to the source. This is a short explanation of that journey. Ben returned to maintain of gpgme Python bindings and continue building them from that point. + * Relics of the past :PROPERTIES: :CUSTOM_ID: relics-past @@ -103,6 +114,7 @@ SWIG itself, which are worth noting here. files. A regular repository version has been maintained should it be possible to implement this better in the future. + ** The Perils of PyPI :PROPERTIES: :CUSTOM_ID: the-perils-of-pypi @@ -145,6 +157,7 @@ SWIG itself, which are worth noting here. module and instead installing the current version of GPGME along with the Python bindings included with that package. + *** PyME 0·9·0 - Python support for GPGME GnuPG cryptography library :PROPERTIES: :CUSTOM_ID: pypi-gpgme-90 @@ -164,6 +177,7 @@ SWIG itself, which are worth noting here. this module, but it may lack a number of more recent features added to GPGME. + * Footnotes [fn:1] In all likelihood this would have been Python 2.2 or possibly diff --git a/lang/python/doc/src/what-is-new b/lang/python/doc/src/what-is-new index 5bcb5aeb..ab94e3ed 100644 --- a/lang/python/doc/src/what-is-new +++ b/lang/python/doc/src/what-is-new @@ -17,15 +17,13 @@ | Version: | 0.0.1-draft | | GPGME Version: | 1.13.0 | -| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] | -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | +| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> | +| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] | | Language: | Australian English, British English | | xml:lang: | en-AU, en-GB, en | Last time the most obviously new thing was adding the /What's New/ -section to the HOWTO. Now it's moving it out of the HOWTO. Not to -mention expanding on the documentation both generally and -considerably. +section to the HOWTO. Now it's moving it out of the HOWTO. ** New in GPGME 1·13·0 @@ -42,3 +40,4 @@ Additions since GPGME 1.12.0 include: - Added =gpg.version.versionintlist= to make it easier for Python developers to check for a specific version number, even with beta versions (it will drop the "-betaN" part). +- Bindings enter [[file:maintenance-mode][maintenance mode]] from January, 2019. diff --git a/lang/python/doc/src/what-was-new b/lang/python/doc/src/what-was-new index 7c851b1e..1d3494cb 100644 --- a/lang/python/doc/src/what-was-new +++ b/lang/python/doc/src/what-was-new @@ -17,8 +17,8 @@ | Version: | 0.0.1-draft | | GPGME Version: | 1.13.0 | -| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] | -| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | +| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> | +| Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] | | Language: | Australian English, British English | | xml:lang: | en-AU, en-GB, en | diff --git a/lang/python/doc/texinfo/gpgme-python-howto.texi b/lang/python/doc/texinfo/gpgme-python-howto.texi index 558bc873..ad3fbedf 100644 --- a/lang/python/doc/texinfo/gpgme-python-howto.texi +++ b/lang/python/doc/texinfo/gpgme-python-howto.texi @@ -171,15 +171,15 @@ Copyright and Licensing @node Introduction @chapter Introduction -@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @item Version: @tab 0.1.4 @item GPGME Version: @tab 1.12.1 @item Author: -@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} +@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}> @item Author GPG Key: -@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D +@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D} @item Language: @tab Australian English, British English @item Language codes: @@ -3200,31 +3200,35 @@ from the author at any of the following URLs: @itemize @item -@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML AWS S3 SSL)} +@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 SSL)} @item -@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML AWS S3 no SSL)} +@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.html, GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no SS)} @item -@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.texi, GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 SSL)} +@uref{https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 SSL)} @item -@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.texi, GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no SSL)} -@item -@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.info, GPGME Python Bindings HOWTO draft (Info file AWS S3 SSL)} -@item -@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.info, GPGME Python Bindings HOWTO draft (Info file AWS S3 no SSL)} -@item -@uref{https://files.au.adversary.org/crypto/gpgme-python-howto.rst, GPGME Python Bindings HOWTO draft (reST file AWS S3 SSL)} -@item -@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.rst, GPGME Python Bindings HOWTO draft (reST file AWS S3 no SSL)} +@uref{http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html, GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no SSL)} @end itemize All of these draft versions except for one have been generated from -this document via Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}. Though it is likely -that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto, file} @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.org, version} used will be on the same server with -the generated output formats. +this document via GNU Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}. Though it is +likely that the specific @uref{https://files.au.adversary.org/crypto/gpgme-python-howto, file} @uref{http://files.au.adversary.org/crypto/gpgme-python-howto.org, version} used will be on the same server +with the generated output formats. -The one exception is the reStructuredText version, which was converted -using the latest version of Pandoc from the Org mode source file using -either of the following two commands: +The GNU Texinfo and reStructured Text versions ship with the software, +while the GNU Emacs Info verseion is generated from the Texinfo +version using GNU Texinfo or GNU Makeinfo. The Texinfo format is +generated from the original Org mode source file in Org mode itself +either within GNU Emacs or via the command line by invoking Emacs in +batch mode: + +@example +emacs gpgme-python-howto.org --batch -f org-texinfo-export-to-texinfo --kill +emacs gpgme-python-howto --batch -f org-texinfo-export-to-texinfo --kill +@end example + +The reStructuredText format is also generated from the Org-mode source +file, except it is generated using @uref{https://pandoc.org, Pandoc} with either of the following +commands: @example pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org diff --git a/lang/python/doc/texinfo/index.texi b/lang/python/doc/texinfo/index.texi index 2ec5e24b..2250d1e6 100644 --- a/lang/python/doc/texinfo/index.texi +++ b/lang/python/doc/texinfo/index.texi @@ -47,6 +47,10 @@ GPGME Python Bindings @uref{short-history, A short history of the project} @item @uref{what-is-new, What's New} +@itemize +@item +@uref{maintenance-mode, Maintenance Mode} (from January, 2019) +@end itemize @item @uref{what-was-new, What Was New} @item diff --git a/lang/python/doc/texinfo/maintenance-mode.texi b/lang/python/doc/texinfo/maintenance-mode.texi new file mode 100644 index 00000000..ad526068 --- /dev/null +++ b/lang/python/doc/texinfo/maintenance-mode.texi @@ -0,0 +1,123 @@ +\input texinfo @c -*- texinfo -*- +@c %**start of header +@setfilename maintenance-mode.info +@settitle Maintenance Mode +@documentencoding UTF-8 +@documentlanguage en +@c %**end of header + +@finalout +@titlepage +@title Maintenance Mode +@author Ben McGinnes +@end titlepage + +@contents + +@ifnottex +@node Top +@top Maintenance Mode +@end ifnottex + +@menu +* Maintenance Mode from 2019:: + +@detailmenu +--- The Detailed Node Listing --- + +Maintenance Mode from 2019 + +* Maintainer from 2019 onward:: +* Using the Python Bindings from 2019 and beyond:: + +@end detailmenu +@end menu + +@node Maintenance Mode from 2019 +@chapter Maintenance Mode from 2019 + +@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item Version: +@tab 0.0.1-draft +@item GPGME Version: +@tab 1.13.0 +@item Author: +@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}> +@item Author GPG Key: +@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D} +@item Language: +@tab Australian English, British English +@item xml:lang: +@tab en-AU, en-GB, en +@end multitable + +From the beginning of 2019 the Python bindings to GPGME will enter +maintenance mode, meaning that new features will not be added and only +bug fixes and security fixes will be made. This also means that +documentation beyond that existing at the end of 2018 will not be +developed further except to correct errors. + +Though use of these bindings appears to have been quite well received, +there has been no indication of what demand there is, if any for +either financial backing of the current Python bindings development or +support contracts with g10code GmbH citing the necessity of including +the bindings. + +@menu +* Maintainer from 2019 onward:: +* Using the Python Bindings from 2019 and beyond:: +@end menu + +@node Maintainer from 2019 onward +@section Maintainer from 2019 onward + +How does this affect the position of GnuPG Python Bindings Maintainer? + +Well, I will remain as maintainer of the bindings; but without funding +for that position, the amount of time I will be able to dedicate +solely to this task will be limited and reduced to volunteered time. +As with all volunteered time and effort in free software projects, +this will be subject to numerous external imperatives. + +@node Using the Python Bindings from 2019 and beyond +@section Using the Python Bindings from 2019 and beyond + +For most, if not all, Python developers using these bindings; they +will continue to “just work” the same as they always have. Expansions +of GPGME itself are usually handled by SWIG with the existing code and +thus bindings are generated properly when the bindings are installed +alongside GPGME and when the latter is built from source. + +In the rare circumstances where that is not enough to address some new +addition to GPGME, then that is a bug and thus subject to the +maintenance mode provisions (i.e. it will be fixed following a bug +report being raised and your humble author will need to remember where +the timesheet template was filed, depending on how many years off such +an event is). + +All the GPGME functionality will continue to be accessible via the +lower level, dynamically generated methods which match the GPGME C +documentation. While the more intuitively Pythonic higher level layer +already covers the vast majority of functionality people require with +key generation, signatures, certifications (key signing), encryption, +decryption, verification, validation, trust levels and so on. + +Any wanted features lacking in the Python bindings are usually lacking +because they are missing from GPGME itself (e.g. revoking keys via the +API) and in such cases they are usually deliberately excluded. More + +Any features existing in the dynamically generated layer for which +people want a specific, higher level function included to make it more +Pythonic (e.g. to avoid needing to learn or memorise cryptographic +mode values or GnuPG status code numbers), would be a feature request +and @emph{not} a bug. + +It is still worthwhile requesting it, but the addition of such a +feature would not be guaranteed and provided on a purely volunteer +basis. Expediting such a request would require funding that request. + +Those with a commercial interest in expediting such a feature request +already know how to @uref{https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset, expedite it} (use the message field to state what +feature is being requested). + +@bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/short-history.texi b/lang/python/doc/texinfo/short-history.texi index 395901f4..480aebfd 100644 --- a/lang/python/doc/texinfo/short-history.texi +++ b/lang/python/doc/texinfo/short-history.texi @@ -49,6 +49,21 @@ The Perils of PyPI @node Overview @chapter Overview +@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@item Version: +@tab 0.0.1-draft +@item GPGME Version: +@tab 1.13.0 +@item Author: +@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}> +@item Author GPG Key: +@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D} +@item Language: +@tab Australian English, British English +@item xml:lang: +@tab en-AU, en-GB, en +@end multitable + The GPGME Python bindings passed through many hands and numerous phases before, after a fifteen year journey, coming full circle to return to the source. This is a short explanation of that journey. diff --git a/lang/python/doc/texinfo/what-is-new.texi b/lang/python/doc/texinfo/what-is-new.texi index 0b70d215..25d12c27 100644 --- a/lang/python/doc/texinfo/what-is-new.texi +++ b/lang/python/doc/texinfo/what-is-new.texi @@ -35,15 +35,15 @@ What's New @node What's New @chapter What's New -@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @item Version: @tab 0.0.1-draft @item GPGME Version: @tab 1.13.0 @item Author: -@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} +@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}> @item Author GPG Key: -@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D +@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D} @item Language: @tab Australian English, British English @item xml:lang: @@ -51,9 +51,7 @@ What's New @end multitable Last time the most obviously new thing was adding the @emph{What's New} -section to the HOWTO. Now it's moving it out of the HOWTO. Not to -mention expanding on the documentation both generally and -considerably. +section to the HOWTO. Now it's moving it out of the HOWTO. @menu * New in GPGME 1·13·0:: @@ -75,6 +73,8 @@ Moving the preceding, archival, segments into @uref{what-was-new.org, another fi Added @samp{gpg.version.versionintlist} to make it easier for Python developers to check for a specific version number, even with beta versions (it will drop the "-betaN" part). +@item +Bindings enter @uref{maintenance-mode, maintenance mode} from January, 2019. @end itemize @bye \ No newline at end of file diff --git a/lang/python/doc/texinfo/what-was-new.texi b/lang/python/doc/texinfo/what-was-new.texi index f81e0c39..63317d88 100644 --- a/lang/python/doc/texinfo/what-was-new.texi +++ b/lang/python/doc/texinfo/what-was-new.texi @@ -39,15 +39,15 @@ What Was New in GPGME 1·12·0 @node What Was New @chapter What Was New -@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} +@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @item Version: @tab 0.0.1-draft @item GPGME Version: @tab 1.13.0 @item Author: -@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} +@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}> @item Author GPG Key: -@tab DB4724E6FA4286C92B4E55C4321E4E2373590E5D +@tab @uref{https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get, DB4724E6FA4286C92B4E55C4321E4E2373590E5D} @item Language: @tab Australian English, British English @item xml:lang: diff --git a/lang/python/setup.py.in b/lang/python/setup.py.in index f23015a2..9785a282 100755 --- a/lang/python/setup.py.in +++ b/lang/python/setup.py.in @@ -30,50 +30,50 @@ import subprocess import sys # Out-of-tree build of the gpg bindings. -gpg_error_config = ["gpg-error-config"] -gpgme_config_flags = ["--thread=pthread"] -gpgme_config = ["gpgme-config"] + gpgme_config_flags -gpgme_h = "" +gpg_error_config = ['gpg-error-config'] +gpgme_config_flags = ['--thread=pthread'] +gpgme_config = ['gpgme-config'] + gpgme_config_flags +gpgme_h = '' include_dirs = [os.getcwd()] library_dirs = [] in_tree = False extra_swig_opts = [] extra_macros = dict() -top_builddir = os.environ.get("top_builddir") +top_builddir = os.environ.get('top_builddir') if top_builddir: # In-tree build. in_tree = True - gpgme_config = [os.path.join(top_builddir, "src/gpgme-config") + gpgme_config = [os.path.join(top_builddir, 'src/gpgme-config') ] + gpgme_config_flags - gpgme_h = os.path.join(top_builddir, "src/gpgme.h") + gpgme_h = os.path.join(top_builddir, 'src/gpgme.h') library_dirs = [os.path.join(top_builddir, - "src/.libs")] # XXX uses libtool internals + 'src/.libs')] # XXX uses libtool internals extra_macros.update( HAVE_CONFIG_H=1, HAVE_DATA_H=1, IN_TREE_BUILD=1, ) -if hasattr(subprocess, "DEVNULL"): +if hasattr(subprocess, 'DEVNULL'): devnull = subprocess.DEVNULL else: - devnull = open(os.devnull, "w") + devnull = open(os.devnull, 'w') try: subprocess.check_call(gpgme_config + ['--version'], stdout=devnull) except: - sys.exit("Could not find gpgme-config. " + - "Please install the libgpgme development package.") + sys.exit('Could not find gpgme-config. ' + + 'Please install the libgpgme development package.') def getconfig(what, config=gpgme_config): confdata = subprocess.Popen( - config + ["--%s" % what], stdout=subprocess.PIPE).communicate()[0] + config + ['--%s' % what], stdout=subprocess.PIPE).communicate()[0] return [x for x in confdata.decode('utf-8').split() if x != ''] -version = version_raw = getconfig("version")[0] +version = version_raw = getconfig('version')[0] if '-' in version: version = version.split('-')[0] major, minor, patch = map(int, version.split('.')) @@ -82,31 +82,31 @@ if not (major > 1 or (major == 1 and minor >= 7)): sys.exit('Need at least GPGME version 1.7, found {}.'.format(version_raw)) if not gpgme_h: - gpgme_h = os.path.join(getconfig("prefix")[0], "include", "gpgme.h") + gpgme_h = os.path.join(getconfig('prefix')[0], 'include', 'gpgme.h') define_macros = [] libs = getconfig('libs') # Define extra_macros for both the SWIG and C code for k, v in extra_macros.items(): - extra_swig_opts.append("-D{0}={1}".format(k, v)) + extra_swig_opts.append('-D{0}={1}'.format(k, v)) define_macros.append((k, str(v))) for item in getconfig('cflags'): - if item.startswith("-I"): + if item.startswith('-I'): include_dirs.append(item[2:]) - elif item.startswith("-D"): - defitem = item[2:].split("=", 1) + elif item.startswith('-D'): + defitem = item[2:].split('=', 1) if len(defitem) == 2: define_macros.append((defitem[0], defitem[1])) else: define_macros.append((defitem[0], None)) # Adjust include and library locations in case of win32 -uname_s = os.popen("uname -s").read() -if uname_s.startswith("MINGW32"): +uname_s = os.popen('uname -s').read() +if uname_s.startswith('MINGW32'): mnts = [ - x.split()[0:3:2] for x in os.popen("mount").read().split("\n") if x + x.split()[0:3:2] for x in os.popen('mount').read().split('\n') if x ] tmplist = sorted([(len(x[1]), x[1], x[0]) for x in mnts]) tmplist.reverse() @@ -120,7 +120,7 @@ if uname_s.startswith("MINGW32"): extra_dirs.append(os.path.join(tgt, item)) break include_dirs += extra_dirs - for item in [x[2:] for x in libs if x.startswith("-L")]: + for item in [x[2:] for x in libs if x.startswith('-L')]: for ln, mnt, tgt in tmplist: if item.startswith(mnt): item = os.path.normpath(item[ln:]) @@ -131,7 +131,7 @@ if uname_s.startswith("MINGW32"): def in_srcdir(name): - return os.path.join(os.environ.get("srcdir", ""), name) + return os.path.join(os.environ.get('srcdir', ''), name) def up_to_date(source, target): @@ -160,9 +160,9 @@ def up_to_date(source, target): class BuildExtFirstHack(build): def _read_header(self, header, cflags): - tmp_include = self._in_build_base("include1.h") + tmp_include = self._in_build_base('include1.h') with open(tmp_include, 'w') as f: - f.write("#include <%s>" % header) + f.write('#include <%s>' % header) return subprocess.check_output( os.environ.get('CPP', 'cc -E').split() + cflags + [tmp_include]).decode('utf-8') @@ -173,11 +173,11 @@ class BuildExtFirstHack(build): if f.read() == content: return - with open(target, "w") as sink: + with open(target, 'w') as sink: sink.write(content) def _generate_gpgme_h(self, source_name, sink_name): - print("Using gpgme.h from {}".format(source_name)) + print('Using gpgme.h from {}'.format(source_name)) shutil.copy2(source_name, sink_name) def _generate_errors_i(self): @@ -186,11 +186,11 @@ class BuildExtFirstHack(build): subprocess.check_call( gpg_error_config + ['--version'], stdout=devnull) except: - sys.exit("Could not find gpg-error-config. " + - "Please install the libgpg-error development package.") + sys.exit('Could not find gpg-error-config. ' + + 'Please install the libgpg-error development package.') gpg_error_content = self._read_header( - "gpg-error.h", getconfig("cflags", config=gpg_error_config)) + 'gpg-error.h', getconfig('cflags', config=gpg_error_config)) filter_re = re.compile(r'GPG_ERR_[^ ]* =') rewrite_re = re.compile(r' *(.*) = .*') @@ -203,7 +203,7 @@ class BuildExtFirstHack(build): r'%constant long \1 = \1;' + '\n', line.strip()) self._write_if_unchanged( - self._in_build_base("errors.i"), errors_i_content) + self._in_build_base('errors.i'), errors_i_content) def _in_build_base(self, name): return os.path.join(self.build_base, name) @@ -213,7 +213,7 @@ class BuildExtFirstHack(build): if not os.path.exists(self.build_base): os.makedirs(self.build_base) - self._generate_gpgme_h(gpgme_h, self._in_build_base("gpgme.h")) + self._generate_gpgme_h(gpgme_h, self._in_build_base('gpgme.h')) self._generate_errors_i() # Copy due to https://bugs.python.org/issue2624 @@ -225,9 +225,9 @@ class BuildExtFirstHack(build): shutil.copy2(source, target) # Append generated files via build_base - if not os.path.exists(os.path.join(self.build_lib, "gpg")): - os.makedirs(os.path.join(self.build_lib, "gpg")) - shutil.copy2("version.py", os.path.join(self.build_lib, "gpg")) + if not os.path.exists(os.path.join(self.build_lib, 'gpg')): + os.makedirs(os.path.join(self.build_lib, 'gpg')) + shutil.copy2('version.py', os.path.join(self.build_lib, 'gpg')) def run(self): self._generate() @@ -248,7 +248,7 @@ py3 = [] if sys.version_info.major < 3 else ['-py3'] swig_sources = [] swig_opts = ['-threads'] + py3 + extra_swig_opts swige = Extension( - "gpg._gpgme", + 'gpg._gpgme', sources=swig_sources, swig_opts=swig_opts, include_dirs=include_dirs, @@ -257,12 +257,34 @@ swige = Extension( extra_link_args=libs) setup( - name="gpg", + name='gpg', cmdclass={'build': BuildExtFirstHack}, - version="@VERSION@", - description='Python bindings for GPGME GnuPG cryptography library', - # TODO: add a long description - # long_description=long_description, + version='@VERSION@', + # Note: description appears as Summary in egg-info file. + description='Python bindings to the GPGME API of the GnuPG cryptography library.', + # Note: long-description appears as Description in egg-info file. + long_description='''Dynamically generated bindings to the C API of the GNU Privacy Guard. + +The GPG Made Easy (GPGME) library provides a high-level API in C to all the +component software and libraries in the GnuPG Project, including GPG itself +(the GnuPG OpenPGP implementation), libgcrypt, libgpg-error, libassuan and +more. + +The official CPython bindings to GPGME are generated during the compiling +process of GPGME itself and built for the specific C header and include files +produced when GPGME is compiled using SWIG. This provides access to over two +thousand functions, methods and values via both the lower level dynamically +generated bindings and a more intuitively pythonic higher level layer. + +While the lower level, dynamically generated bindings provide access to +everything which GPGME itself provides; the higher level layer is easier to use +by Python developers, provides access to the vast majority of functionality +developers would want from GnuPG and is extensively documented. + +GPGME and these bindings is available here: + + https://gnupg.org/software/gpgme/index.html +''', author='The GnuPG hackers', author_email='gnupg-devel@gnupg.org', url='https://www.gnupg.org', @@ -271,7 +293,7 @@ setup( 'gpg', 'gpg.constants', 'gpg.constants.data', 'gpg.constants.keylist', 'gpg.constants.sig', 'gpg.constants.tofu' ], - license="LGPL2.1+ (the library), GPL2+ (tests and examples)", + license='LGPL2.1+ (the library), GPL2+ (tests and examples)', classifiers=[ 'Development Status :: 4 - Beta', 'Intended Audience :: Developers',