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

python: documentation

Browse Source 
* 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 <ben@adversary.org>
This commit is contained in:
Ben McGinnes 2018-12-01 07:45:50 +11:00
parent a9cfb6dad8
commit 3b056a01a2
19 changed files with 542 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
lang/python/doc/rst/gpgme-python-howto.rst
View File

@ -13,8 +13,11 @@ Introduction
| | e/index.html#sec-1-5>`__ | | | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> | | | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 | | Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 |
| | 3590E5D | | | 73590E5D <https://hkps.pool.sks-k |
| | eyservers.net/pks/lookup?search=0 |
| | xDB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D&exact=on&op=get>`__ |
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
| Language: | Australian English, British | | Language: | Australian English, British |
| | English | | | English |
@ -3009,34 +3012,37 @@ Draft Editions of this HOWTO
Draft editions of this HOWTO may be periodically available directly from Draft editions of this HOWTO may be periodically available directly from
the author at any of the following URLs: 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) <https://files.au.adversary.org/crypto/gpgme-python-howto.html>`__ SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
- `GPGME Python Bindings HOWTO draft (XHTML AWS S3 no - `GPGME Python Bindings HOWTO draft (XHTML single file, AWS S3 no
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__ SS) <http://files.au.adversary.org/crypto/gpgme-python-howto.html>`__
- `GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 - `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3
SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.texi>`__ SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html>`__
- `GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no - `GPGME Python Bindings HOWTO draft (XHTML multiple files, AWS S3 no
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.texi>`__ SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto-split/index.html>`__
- `GPGME Python Bindings HOWTO draft (Info file AWS S3
SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.info>`__
- `GPGME Python Bindings HOWTO draft (Info file AWS S3 no
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.info>`__
- `GPGME Python Bindings HOWTO draft (reST file AWS S3
SSL) <https://files.au.adversary.org/crypto/gpgme-python-howto.rst>`__
- `GPGME Python Bindings HOWTO draft (reST file AWS S3 no
SSL) <http://files.au.adversary.org/crypto/gpgme-python-howto.rst>`__
All of these draft versions except for one have been generated from this All of these draft versions except for one have been generated from this
document via Emacs `Org mode <https://orgmode.org/>`__ and `GNU document via GNU Emacs `Org mode <https://orgmode.org/>`__ and `GNU
Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely Texinfo <https://www.gnu.org/software/texinfo/>`__. Though it is likely
that the specific that the specific
`file <https://files.au.adversary.org/crypto/gpgme-python-howto>`__ `file <https://files.au.adversary.org/crypto/gpgme-python-howto>`__
`version <http://files.au.adversary.org/crypto/gpgme-python-howto.org>`__ `version <http://files.au.adversary.org/crypto/gpgme-python-howto.org>`__
used will be on the same server with the generated output formats. used will be on the same server with the generated output formats.
The one exception is the reStructuredText version, which was converted The GNU Texinfo and reStructured Text versions ship with the software,
using the latest version of Pandoc from the Org mode source file using while the GNU Emacs Info verseion is generated from the Texinfo version
either of the following two commands: 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 <https://pandoc.org>`__ with
either of the following commands:
.. code:: shell .. code:: shell

3
lang/python/doc/rst/index.rst
View File

@ -8,5 +8,8 @@ Contents
- `A short history of the project <short-history>`__ - `A short history of the project <short-history>`__
- `What\'s New <what-is-new>`__ - `What\'s New <what-is-new>`__
- `Maintenance Mode <maintenance-mode>`__ (from January, 2019)
- `What Was New <what-was-new>`__ - `What Was New <what-was-new>`__
- `GPGME Python Bindings HOWTO <gpgme-python-howto>`__ - `GPGME Python Bindings HOWTO <gpgme-python-howto>`__

95
lang/python/doc/rst/maintenance-mode.rst Normal file
View File

@ -0,0 +1,95 @@
.. _maintenance-mode:
Maintenance Mode from 2019
==========================
+-----------------------------------+-----------------------------------+
| Version: | 0.0.1-draft |
+-----------------------------------+-----------------------------------+
| GPGME Version: | 1.13.0 |
+-----------------------------------+-----------------------------------+
| Author: | `Ben |
| | McGinnes <https://gnupg.org/peopl |
| | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+
| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D <https://hkps.pool.sks-k |
| | eyservers.net/pks/lookup?search=0 |
| | xDB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D&exact=on&op=get>`__ |
+-----------------------------------+-----------------------------------+
| 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 <https://gnupg.org/cgi-bin/procdonate.cgi?mode=preset>`__ (use the
message field to state what feature is being requested).

22
lang/python/doc/rst/short-history.rst
View File

@ -1,6 +1,28 @@
Overview Overview
======== ========
+-----------------------------------+-----------------------------------+
| Version: | 0.0.1-draft |
+-----------------------------------+-----------------------------------+
| GPGME Version: | 1.13.0 |
+-----------------------------------+-----------------------------------+
| Author: | `Ben |
| | McGinnes <https://gnupg.org/peopl |
| | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+
| Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D <https://hkps.pool.sks-k |
| | eyservers.net/pks/lookup?search=0 |
| | xDB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D&exact=on&op=get>`__ |
+-----------------------------------+-----------------------------------+
| Language: | Australian English, British |
| | English |
+-----------------------------------+-----------------------------------+
| xml:lang: | en-AU, en-GB, en |
+-----------------------------------+-----------------------------------+
The GPGME Python bindings passed through many hands and numerous phases The GPGME Python bindings passed through many hands and numerous phases
before, after a fifteen year journey, coming full circle to return to before, after a fifteen year journey, coming full circle to return to
the source. This is a short explanation of that journey. the source. This is a short explanation of that journey.

12
lang/python/doc/rst/what-is-new.rst
View File

@ -13,8 +13,11 @@ What\'s New
| | e/index.html#sec-1-5>`__ | | | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> | | | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 | | Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 |
| | 3590E5D | | | 73590E5D <https://hkps.pool.sks-k |
| | eyservers.net/pks/lookup?search=0 |
| | xDB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D&exact=on&op=get>`__ |
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
| Language: | Australian English, British | | Language: | Australian English, British |
| | English | | | English |
@ -23,8 +26,7 @@ What\'s New
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
Last time the most obviously new thing was adding the *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 section to the HOWTO. Now it\'s moving it out of the HOWTO.
mention expanding on the documentation both generally and considerably.
.. _new-stuff-1-13-0: .. _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 - Added ``gpg.version.versionintlist`` to make it easier for Python
developers to check for a specific version number, even with beta developers to check for a specific version number, even with beta
versions (it will drop the \"-betaN\" part). versions (it will drop the \"-betaN\" part).
- Bindings enter `maintenance mode <maintenance-mode>`__ from January,
2019.

7
lang/python/doc/rst/what-was-new.rst
View File

@ -13,8 +13,11 @@ What Was New
| | e/index.html#sec-1-5>`__ | | | e/index.html#sec-1-5>`__ |
| | <ben@gnupg.org> | | | <ben@gnupg.org> |
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E237 | | Author GPG Key: | `DB4724E6FA4286C92B4E55C4321E4E23 |
| | 3590E5D | | | 73590E5D <https://hkps.pool.sks-k |
| | eyservers.net/pks/lookup?search=0 |
| | xDB4724E6FA4286C92B4E55C4321E4E23 |
| | 73590E5D&exact=on&op=get>`__ |
+-----------------------------------+-----------------------------------+ +-----------------------------------+-----------------------------------+
| Language: | Australian English, British | | Language: | Australian English, British |
| | English | | | English |

42
lang/python/doc/src/gpgme-python-howto
View File

@ -17,10 +17,11 @@
| Version: | 0.1.4 | | Version: | 0.1.4 |
| GPGME Version: | 1.12.1 | | GPGME Version: | 1.12.1 |
| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org> | | Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> |
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | | Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
| Language: | Australian English, British English | | Language: | Australian English, British English |
| Language codes: | en-AU, en-GB, en | | Language codes: | en-AU, en-GB, en |
#+TBLFM:
This document provides basic instruction in how to use the GPGME This document provides basic instruction in how to use the GPGME
Python bindings to programmatically leverage the GPGME library. 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 the GPGME Python bindings, they are both highly recommended more
generally. generally.
* Advanced or Experimental Use Cases * Advanced or Experimental Use Cases
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: advanced-use :CUSTOM_ID: advanced-use
@ -3083,23 +3085,31 @@ Copyright (C) The GnuPG Project, 2018.
Draft editions of this HOWTO may be periodically available directly Draft editions of this HOWTO may be periodically available directly
from the author at any of the following URLs: 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)]] - [[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 AWS S3 no 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.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 SSL)]] - [[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.texi][GPGME Python Bindings HOWTO draft (Texinfo file AWS S3 no 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)]]
- [[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)]]
All of these draft versions except for one have been generated from 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 this document via GNU Emacs [[https://orgmode.org/][Org mode]] and [[https://www.gnu.org/software/texinfo/][GNU Texinfo]]. Though it is
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 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
the generated output formats. with the generated output formats.
The one exception is the reStructuredText version, which was converted The GNU Texinfo and reStructured Text versions ship with the software,
using the latest version of Pandoc from the Org mode source file using while the GNU Emacs Info verseion is generated from the Texinfo
either of the following two commands: 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 #+BEGIN_SRC shell
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org

1
lang/python/doc/src/index
View File

@ -24,5 +24,6 @@
- [[file:short-history][A short history of the project]] - [[file:short-history][A short history of the project]]
- [[file:what-is-new][What's New]] - [[file:what-is-new][What's New]]
- [[file:maintenance-mode][Maintenance Mode]] (from January, 2019)
- [[file:what-was-new][What Was New]] - [[file:what-was-new][What Was New]]
- [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]] - [[file:gpgme-python-howto][GPGME Python Bindings HOWTO]]

93
lang/python/doc/src/maintenance-mode Normal file
View File

@ -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 <ben@gnupg.org>}
* 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).

16
lang/python/doc/src/short-history
View File

@ -5,13 +5,20 @@
#+LATEX_CLASS_OPTIONS: [12pt] #+LATEX_CLASS_OPTIONS: [12pt]
#+LATEX_HEADER: \usepackage{xltxtra} #+LATEX_HEADER: \usepackage{xltxtra}
#+LATEX_HEADER: \usepackage[margin=1in]{geometry} #+LATEX_HEADER: \usepackage[margin=1in]{geometry}
#+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Latin Modern Roman} #+LATEX_HEADER: \setmainfont[Ligatures={Common}]{Times New Roman}
* Overview * Overview
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: overview :CUSTOM_ID: overview
:END: :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 The GPGME Python bindings passed through many hands and numerous
phases before, after a fifteen year journey, coming full circle to phases before, after a fifteen year journey, coming full circle to
return to the source. This is a short explanation of that journey. 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 supporting it, though he left his work available on his Gopher
site. site.
** Keeping the flame alive ** Keeping the flame alive
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: keeping-the-flame-alive :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 but the current authors do hope he is well. We're assuming (or
hoping) that life did what life does and made continuing untenable. hoping) that life did what life does and made continuing untenable.
** Passing the torch ** Passing the torch
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: passing-the-torch :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 the original PyME release in Python 2.6 and 2.7 (available via
PyPI). PyPI).
** Coming full circle ** Coming full circle
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: ouroboros :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 Ben returned to maintain of gpgme Python bindings and continue
building them from that point. building them from that point.
* Relics of the past * Relics of the past
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: relics-past :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 files. A regular repository version has been maintained should it
be possible to implement this better in the future. be possible to implement this better in the future.
** The Perils of PyPI ** The Perils of PyPI
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: the-perils-of-pypi :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 module and instead installing the current version of GPGME along
with the Python bindings included with that package. with the Python bindings included with that package.
*** PyME 0·9·0 - Python support for GPGME GnuPG cryptography library *** PyME 0·9·0 - Python support for GPGME GnuPG cryptography library
:PROPERTIES: :PROPERTIES:
:CUSTOM_ID: pypi-gpgme-90 :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 this module, but it may lack a number of more recent features
added to GPGME. added to GPGME.
* Footnotes * Footnotes
[fn:1] In all likelihood this would have been Python 2.2 or possibly [fn:1] In all likelihood this would have been Python 2.2 or possibly

9
lang/python/doc/src/what-is-new
View File

@ -17,15 +17,13 @@
| Version: | 0.0.1-draft | | Version: | 0.0.1-draft |
| GPGME Version: | 1.13.0 | | GPGME Version: | 1.13.0 |
| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org> | | Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> |
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | | Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
| Language: | Australian English, British English | | Language: | Australian English, British English |
| xml:lang: | en-AU, en-GB, en | | xml:lang: | en-AU, en-GB, en |
Last time the most obviously new thing was adding the /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 section to the HOWTO. Now it's moving it out of the HOWTO.
mention expanding on the documentation both generally and
considerably.
** New in GPGME 1·13·0 ** 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 - Added =gpg.version.versionintlist= to make it easier for Python
developers to check for a specific version number, even with beta developers to check for a specific version number, even with beta
versions (it will drop the "-betaN" part). versions (it will drop the "-betaN" part).
- Bindings enter [[file:maintenance-mode][maintenance mode]] from January, 2019.

4
lang/python/doc/src/what-was-new
View File

@ -17,8 +17,8 @@
| Version: | 0.0.1-draft | | Version: | 0.0.1-draft |
| GPGME Version: | 1.13.0 | | GPGME Version: | 1.13.0 |
| Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <ben@gnupg.org> | | Author: | [[https://gnupg.org/people/index.html#sec-1-5][Ben McGinnes]] <[[mailto:ben@gnupg.org][ben@gnupg.org]]> |
| Author GPG Key: | DB4724E6FA4286C92B4E55C4321E4E2373590E5D | | Author GPG Key: | [[https://hkps.pool.sks-keyservers.net/pks/lookup?search=0xDB4724E6FA4286C92B4E55C4321E4E2373590E5D&exact=on&op=get][DB4724E6FA4286C92B4E55C4321E4E2373590E5D]] |
| Language: | Australian English, British English | | Language: | Australian English, British English |
| xml:lang: | en-AU, en-GB, en | | xml:lang: | en-AU, en-GB, en |

46
lang/python/doc/texinfo/gpgme-python-howto.texi
View File

@ -171,15 +171,15 @@ Copyright and Licensing
@node Introduction @node Introduction
@chapter Introduction @chapter Introduction
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item Version: @item Version:
@tab 0.1.4 @tab 0.1.4
@item GPGME Version: @item GPGME Version:
@tab 1.12.1 @tab 1.12.1
@item Author: @item Author:
@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org> @tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
@item Author GPG Key: @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: @item Language:
@tab Australian English, British English @tab Australian English, British English
@item Language codes: @item Language codes:
@ -3200,31 +3200,35 @@ from the author at any of the following URLs:
@itemize @itemize
@item @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 @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 @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 @item
@uref{http://files.au.adversary.org/crypto/gpgme-python-howto.texi, GPGME Python Bindings HOWTO draft (Texinfo 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)}
@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)}
@end itemize @end itemize
All of these draft versions except for one have been generated from 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 this document via GNU Emacs @uref{https://orgmode.org/, Org mode} and @uref{https://www.gnu.org/software/texinfo/, GNU Texinfo}. Though it is
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 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
the generated output formats. with the generated output formats.
The one exception is the reStructuredText version, which was converted The GNU Texinfo and reStructured Text versions ship with the software,
using the latest version of Pandoc from the Org mode source file using while the GNU Emacs Info verseion is generated from the Texinfo
either of the following two commands: 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 @example
pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org pandoc -f org -t rst+smart -o gpgme-python-howto.rst gpgme-python-howto.org

4
lang/python/doc/texinfo/index.texi
View File

@ -47,6 +47,10 @@ GPGME Python Bindings
@uref{short-history, A short history of the project} @uref{short-history, A short history of the project}
@item @item
@uref{what-is-new, What's New} @uref{what-is-new, What's New}
@itemize
@item
@uref{maintenance-mode, Maintenance Mode} (from January, 2019)
@end itemize
@item @item
@uref{what-was-new, What Was New} @uref{what-was-new, What Was New}
@item @item

123
lang/python/doc/texinfo/maintenance-mode.texi Normal file
View File

@ -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

15
lang/python/doc/texinfo/short-history.texi
View File

@ -49,6 +49,21 @@ The Perils of PyPI
@node Overview @node Overview
@chapter 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 The GPGME Python bindings passed through many hands and numerous
phases before, after a fifteen year journey, coming full circle to phases before, after a fifteen year journey, coming full circle to
return to the source. This is a short explanation of that journey. return to the source. This is a short explanation of that journey.

12
lang/python/doc/texinfo/what-is-new.texi
View File

@ -35,15 +35,15 @@ What's New
@node What's New @node What's New
@chapter What's New @chapter What's New
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item Version: @item Version:
@tab 0.0.1-draft @tab 0.0.1-draft
@item GPGME Version: @item GPGME Version:
@tab 1.13.0 @tab 1.13.0
@item Author: @item Author:
@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org> @tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
@item Author GPG Key: @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: @item Language:
@tab Australian English, British English @tab Australian English, British English
@item xml:lang: @item xml:lang:
@ -51,9 +51,7 @@ What's New
@end multitable @end multitable
Last time the most obviously new thing was adding the @emph{What's New} 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 section to the HOWTO. Now it's moving it out of the HOWTO.
mention expanding on the documentation both generally and
considerably.
@menu @menu
* New in GPGME 1·13·0:: * 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 Added @samp{gpg.version.versionintlist} to make it easier for Python
developers to check for a specific version number, even with beta developers to check for a specific version number, even with beta
versions (it will drop the "-betaN" part). versions (it will drop the "-betaN" part).
@item
Bindings enter @uref{maintenance-mode, maintenance mode} from January, 2019.
@end itemize @end itemize
@bye @bye

6
lang/python/doc/texinfo/what-was-new.texi
View File

@ -39,15 +39,15 @@ What Was New in GPGME 1·12·0
@node What Was New @node What Was New
@chapter What Was New @chapter What Was New
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} @multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item Version: @item Version:
@tab 0.0.1-draft @tab 0.0.1-draft
@item GPGME Version: @item GPGME Version:
@tab 1.13.0 @tab 1.13.0
@item Author: @item Author:
@tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <ben@@gnupg.org> @tab @uref{https://gnupg.org/people/index.html#sec-1-5, Ben McGinnes} <@email{ben@@gnupg.org, ben@@gnupg.org}>
@item Author GPG Key: @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: @item Language:
@tab Australian English, British English @tab Australian English, British English
@item xml:lang: @item xml:lang:

108
lang/python/setup.py.in
View File

@ -30,50 +30,50 @@ import subprocess
import sys import sys
# Out-of-tree build of the gpg bindings. # Out-of-tree build of the gpg bindings.
gpg_error_config = ["gpg-error-config"] gpg_error_config = ['gpg-error-config']
gpgme_config_flags = ["--thread=pthread"] gpgme_config_flags = ['--thread=pthread']
gpgme_config = ["gpgme-config"] + gpgme_config_flags gpgme_config = ['gpgme-config'] + gpgme_config_flags
gpgme_h = "" gpgme_h = ''
include_dirs = [os.getcwd()] include_dirs = [os.getcwd()]
library_dirs = [] library_dirs = []
in_tree = False in_tree = False
extra_swig_opts = [] extra_swig_opts = []
extra_macros = dict() extra_macros = dict()
top_builddir = os.environ.get("top_builddir") top_builddir = os.environ.get('top_builddir')
if top_builddir: if top_builddir:
# In-tree build. # In-tree build.
in_tree = True 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_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, library_dirs = [os.path.join(top_builddir,
"src/.libs")] # XXX uses libtool internals 'src/.libs')] # XXX uses libtool internals
extra_macros.update( extra_macros.update(
HAVE_CONFIG_H=1, HAVE_CONFIG_H=1,
HAVE_DATA_H=1, HAVE_DATA_H=1,
IN_TREE_BUILD=1, IN_TREE_BUILD=1,
) )
if hasattr(subprocess, "DEVNULL"): if hasattr(subprocess, 'DEVNULL'):
devnull = subprocess.DEVNULL devnull = subprocess.DEVNULL
else: else:
devnull = open(os.devnull, "w") devnull = open(os.devnull, 'w')
try: try:
subprocess.check_call(gpgme_config + ['--version'], stdout=devnull) subprocess.check_call(gpgme_config + ['--version'], stdout=devnull)
except: except:
sys.exit("Could not find gpgme-config. " + sys.exit('Could not find gpgme-config. ' +
"Please install the libgpgme development package.") 'Please install the libgpgme development package.')
def getconfig(what, config=gpgme_config): def getconfig(what, config=gpgme_config):
confdata = subprocess.Popen( 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 != ''] 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: if '-' in version:
version = version.split('-')[0] version = version.split('-')[0]
major, minor, patch = map(int, version.split('.')) 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)) sys.exit('Need at least GPGME version 1.7, found {}.'.format(version_raw))
if not gpgme_h: 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 = [] define_macros = []
libs = getconfig('libs') libs = getconfig('libs')
# Define extra_macros for both the SWIG and C code # Define extra_macros for both the SWIG and C code
for k, v in extra_macros.items(): 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))) define_macros.append((k, str(v)))
for item in getconfig('cflags'): for item in getconfig('cflags'):
if item.startswith("-I"): if item.startswith('-I'):
include_dirs.append(item[2:]) include_dirs.append(item[2:])
elif item.startswith("-D"): elif item.startswith('-D'):
defitem = item[2:].split("=", 1) defitem = item[2:].split('=', 1)
if len(defitem) == 2: if len(defitem) == 2:
define_macros.append((defitem[0], defitem[1])) define_macros.append((defitem[0], defitem[1]))
else: else:
define_macros.append((defitem[0], None)) define_macros.append((defitem[0], None))
# Adjust include and library locations in case of win32 # Adjust include and library locations in case of win32
uname_s = os.popen("uname -s").read() uname_s = os.popen('uname -s').read()
if uname_s.startswith("MINGW32"): if uname_s.startswith('MINGW32'):
mnts = [ 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 = sorted([(len(x[1]), x[1], x[0]) for x in mnts])
tmplist.reverse() tmplist.reverse()
@ -120,7 +120,7 @@ if uname_s.startswith("MINGW32"):
extra_dirs.append(os.path.join(tgt, item)) extra_dirs.append(os.path.join(tgt, item))
break break
include_dirs += extra_dirs 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: for ln, mnt, tgt in tmplist:
if item.startswith(mnt): if item.startswith(mnt):
item = os.path.normpath(item[ln:]) item = os.path.normpath(item[ln:])
@ -131,7 +131,7 @@ if uname_s.startswith("MINGW32"):
def in_srcdir(name): 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): def up_to_date(source, target):
@ -160,9 +160,9 @@ def up_to_date(source, target):
class BuildExtFirstHack(build): class BuildExtFirstHack(build):
def _read_header(self, header, cflags): 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: with open(tmp_include, 'w') as f:
f.write("#include <%s>" % header) f.write('#include <%s>' % header)
return subprocess.check_output( return subprocess.check_output(
os.environ.get('CPP', 'cc -E').split() + cflags + os.environ.get('CPP', 'cc -E').split() + cflags +
[tmp_include]).decode('utf-8') [tmp_include]).decode('utf-8')
@ -173,11 +173,11 @@ class BuildExtFirstHack(build):
if f.read() == content: if f.read() == content:
return return
with open(target, "w") as sink: with open(target, 'w') as sink:
sink.write(content) sink.write(content)
def _generate_gpgme_h(self, source_name, sink_name): 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) shutil.copy2(source_name, sink_name)
def _generate_errors_i(self): def _generate_errors_i(self):
@ -186,11 +186,11 @@ class BuildExtFirstHack(build):
subprocess.check_call( subprocess.check_call(
gpg_error_config + ['--version'], stdout=devnull) gpg_error_config + ['--version'], stdout=devnull)
except: except:
sys.exit("Could not find gpg-error-config. " + sys.exit('Could not find gpg-error-config. ' +
"Please install the libgpg-error development package.") 'Please install the libgpg-error development package.')
gpg_error_content = self._read_header( 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_[^ ]* =') filter_re = re.compile(r'GPG_ERR_[^ ]* =')
rewrite_re = re.compile(r' *(.*) = .*') rewrite_re = re.compile(r' *(.*) = .*')
@ -203,7 +203,7 @@ class BuildExtFirstHack(build):
r'%constant long \1 = \1;' + '\n', line.strip()) r'%constant long \1 = \1;' + '\n', line.strip())
self._write_if_unchanged( 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): def _in_build_base(self, name):
return os.path.join(self.build_base, name) return os.path.join(self.build_base, name)
@ -213,7 +213,7 @@ class BuildExtFirstHack(build):
if not os.path.exists(self.build_base): if not os.path.exists(self.build_base):
os.makedirs(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() self._generate_errors_i()
# Copy due to https://bugs.python.org/issue2624 # Copy due to https://bugs.python.org/issue2624
@ -225,9 +225,9 @@ class BuildExtFirstHack(build):
shutil.copy2(source, target) shutil.copy2(source, target)
# Append generated files via build_base # Append generated files via build_base
if not os.path.exists(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")) os.makedirs(os.path.join(self.build_lib, 'gpg'))
shutil.copy2("version.py", os.path.join(self.build_lib, "gpg")) shutil.copy2('version.py', os.path.join(self.build_lib, 'gpg'))
def run(self): def run(self):
self._generate() self._generate()
@ -248,7 +248,7 @@ py3 = [] if sys.version_info.major < 3 else ['-py3']
swig_sources = [] swig_sources = []
swig_opts = ['-threads'] + py3 + extra_swig_opts swig_opts = ['-threads'] + py3 + extra_swig_opts
swige = Extension( swige = Extension(
"gpg._gpgme", 'gpg._gpgme',
sources=swig_sources, sources=swig_sources,
swig_opts=swig_opts, swig_opts=swig_opts,
include_dirs=include_dirs, include_dirs=include_dirs,
@ -257,12 +257,34 @@ swige = Extension(
extra_link_args=libs) extra_link_args=libs)
setup( setup(
name="gpg", name='gpg',
cmdclass={'build': BuildExtFirstHack}, cmdclass={'build': BuildExtFirstHack},
version="@VERSION@", version='@VERSION@',
description='Python bindings for GPGME GnuPG cryptography library', # Note: description appears as Summary in egg-info file.
# TODO: add a long description description='Python bindings to the GPGME API of the GnuPG cryptography library.',
# long_description=long_description, # 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='The GnuPG hackers',
author_email='gnupg-devel@gnupg.org', author_email='gnupg-devel@gnupg.org',
url='https://www.gnupg.org', url='https://www.gnupg.org',
@ -271,7 +293,7 @@ setup(
'gpg', 'gpg.constants', 'gpg.constants.data', 'gpg.constants.keylist', 'gpg', 'gpg.constants', 'gpg.constants.data', 'gpg.constants.keylist',
'gpg.constants.sig', 'gpg.constants.tofu' '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=[ classifiers=[
'Development Status :: 4 - Beta', 'Development Status :: 4 - Beta',
'Intended Audience :: Developers', 'Intended Audience :: Developers',