[Pkg-gnupg-commit] [gpgme] 171/412: python: Improve the documentation.
Daniel Kahn Gillmor
dkg at fifthhorseman.net
Thu Sep 22 21:26:41 UTC 2016
This is an automated email from the git hooks/post-receive script.
dkg pushed a commit to branch master
in repository gpgme.
commit 5492853d7b84b4e1d0b11b234e32252ba8d1608d
Author: Justus Winter <justus at g10code.com>
Date: Mon Jun 6 14:08:59 2016 +0200
python: Improve the documentation.
* lang/python/Makefile.am: Copy the README file.
* lang/python/README: Rename, convert to org, and update.
* lang/python/pyme/__init__.py: Move license out of the docstring,
update docstring.
* lang/python/pyme/core.py: Add and update docstrings.
Signed-off-by: Justus Winter <justus at g10code.com>
---
lang/python/Makefile.am | 9 +++--
lang/python/README | 57 +++++++++++++++++++++++++++++
lang/python/README.rst | 48 -------------------------
lang/python/pyme/__init__.py | 50 +++++++++++++-------------
lang/python/pyme/core.py | 86 ++++++++++++++++++++++++++++++--------------
5 files changed, 148 insertions(+), 102 deletions(-)
diff --git a/lang/python/Makefile.am b/lang/python/Makefile.am
index 2c84f2b..18005bf 100644
--- a/lang/python/Makefile.am
+++ b/lang/python/Makefile.am
@@ -16,16 +16,21 @@
# You should have received a copy of the GNU Lesser General Public
# License along with this program; if not, see <http://www.gnu.org/licenses/>.
-EXTRA_DIST = README.rst
+EXTRA_DIST = README
SUBDIRS = tests
+COPY_FILES = \
+ $(srcdir)/README \
+ $(srcdir)/pyme \
+ $(srcdir)/helpers.c $(srcdir)/helpers.h
+
# Cleanup gpgme.h from deprecated functions and typedefs.
gpgme.h: ../../src/gpgme.h $(srcdir)/gpgme-h-clean.py
$(PYTHON) $(srcdir)/gpgme-h-clean.py $< >$@
# For VPATH builds we need to copy some files because Python's
# distutils are not VPATH-aware.
-copystamp: $(srcdir)/pyme $(srcdir)/helpers.c $(srcdir)/helpers.h
+copystamp: $(COPY_FILES)
if test "$(srcdir)" != "$(builddir)" ; then cp -r $^ . ; fi
touch $@
diff --git a/lang/python/README b/lang/python/README
new file mode 100644
index 0000000..7ce8894
--- /dev/null
+++ b/lang/python/README
@@ -0,0 +1,57 @@
+PyME - GPGME for Python emacs, please switch to -*- org -*- mode
+=======================
+
+PyMe is a python interface to the GPGME library:
+https://www.gnupg.org/related_software/gpgme/
+
+PyMe uses SWIG to create wrapper functions with automatic type
+conversions. This way most of the functions and types are converted
+from C into Python 3 automatically by SWIG, reducing the maintenance
+cost of the binginds.
+
+* Authors
+
+PyME has been created by John Goerzen, and maintained, developed, and
+cherished by Igor Belyi, Martin Albrecht, Ben McGinnes, and everyone
+who contributed to it in any way.
+
+In 2016 we merged a port of PyME to into the GPGME repository, and
+development will continue there. Please see the VCS history for the
+list of contributors, and if you do find bugs, or want to contribute,
+please get in touch and help maintain PyME.
+
+Please see the section 'History' further down this document for
+references to previous versions.
+
+* Mailing List
+
+For general discussion and help see the gnupg-users mailing list:
+https://lists.gnupg.org/mailman/listinfo/gnupg-users
+
+For development see the gnupg-devel mailing list:
+https://lists.gnupg.org/mailman/listinfo/gnupg-devel
+
+* Bugs
+
+Please report bugs using our bug tracker using the category 'gpgme',
+and topic 'python':
+https://bugs.gnupg.org/gnupg/
+
+* History
+
+ - The bindings have been merged into the GPGME repository in 2016.
+
+ - The latest version of PyME for Python 3.2 and above (as of
+ May, 2015) is v0.9.1.
+ https://git.gnupg.org/gpgme.git/lang/py3-pyme
+
+ - The latest version of PyME for Python 2.6 and 2.7 (as of this
+ writing) is v0.9.0. https://bitbucket.org/malb/pyme
+
+ - A previous version of PyME v0.8.0 can be found on sourceforge:
+ http://pyme.sourceforge.net/
+
+ - A previous version of PyME v0.5.1 which works with GPGME v0.3.15
+ can be found on John Goerzen's PyMe page:
+ http://quux.org/devel/pyme/
+ http://www.complete.org/JohnGoerzen
diff --git a/lang/python/README.rst b/lang/python/README.rst
deleted file mode 100644
index 57df1f2..0000000
--- a/lang/python/README.rst
+++ /dev/null
@@ -1,48 +0,0 @@
-====
-PyME
-====
-
-PyMe is a python interface to the `GPGME
-<https://www.gnupg.org/related_software/gpgme/>`_ library.
-
-PyMe's development model is a `GPGME
-<https://www.gnupg.org/related_software/gpgme/>`_ + Python 3 + `SWIG
-<http://www.swig.org/>`_ combination which means that most of the functions and
-types are converted from C into Python 3 automatically by SWIG. In short, to be
-able to use PyMe you need to be `familiar with GPGME
-<https://www.gnupg.org/documentation/manuals/gpgme/>`_.
-
-
--------
-Authors
--------
-
-* John Goerzen, `Complete.Org <http://www.complete.org/JohnGoerzen>`_, 2002.
-* Igor Belyi, `PyME 0.8 <http://pyme.sourceforge.net/>`_, 2004-2008.
-* Martin Albrecht, `PyME 0.9+ <https://bitbucket.org/malb/pyme>`_, 2014 to present.
-* Ben McGinnes, `PyME Python 3 Port <https://git.gnupg.org/gpgme.git/lang/py3-pyme>`_, 2015 to present.
-
-
-------------
-Mailing List
-------------
-
-PyME's support and development `mailing list
-<http://sourceforge.net/p/pyme/mailman/pyme-help/>`_ is hosted by sourceforge.
-
-
--------
-History
--------
-
-* The latest version of PyME for Python 3.2 and above (as of May, 2015) is v0.9.1.
- https://git.gnupg.org/gpgme.git/lang/py3-pyme
-
-* The latest version of PyME for Python 2.6 and 2.7 (as of this writing) is v0.9.0.
- https://bitbucket.org/malb/pyme
-
-* A previous version of PyME v0.8.0 can be found on sourceforge:
- http://pyme.sourceforge.net/
-
-* A previous version of PyME v0.5.1 which works with GPGME v0.3.15 can be found
- on John Goerzen's PyMe page: http://quux.org/devel/pyme/
diff --git a/lang/python/pyme/__init__.py b/lang/python/pyme/__init__.py
index d06866a..e377f59 100644
--- a/lang/python/pyme/__init__.py
+++ b/lang/python/pyme/__init__.py
@@ -1,36 +1,38 @@
-"""
-Pyme: GPGME Interface for Python
-Copyright (C) 2004 Igor Belyi <belyi at users.sourceforge.net>
-Copyright (C) 2002 John Goerzen <jgoerzen at complete.org>
-
- This library is free software; you can redistribute it and/or
- modify it under the terms of the GNU Lesser General Public
- License as published by the Free Software Foundation; either
- version 2.1 of the License, or (at your option) any later version.
-
- This library is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public
- License along with this library; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+# Copyright (C) 2016 g10 Code GmbH
+# Copyright (C) 2004 Igor Belyi <belyi at users.sourceforge.net>
+# Copyright (C) 2002 John Goerzen <jgoerzen at complete.org>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+
+"""Pyme: GPGME Interface for Python
Welcome to PyME, the GPGME Interface for Python. "Pyme", when prounced,
rhymes with "Pine".
The latest release of this package may be obtained from
+https://www.gnupg.org
+
+Previous releases of this package for Python 2 can be obtained from
http://pyme.sourceforge.net
-Previous releases of this package can be obtained from
-http://quux.org/devel/pyme/
FEATURES
--------
* Feature-rich, full implementation of the GPGME library. Supports
- all GPGME features except interactive editing (coming soon).
- Callback functions may be written in pure Python.
+ all GPGME features. Callback functions may be written in pure
+ Python. Exceptions raised in callbacks are properly propagated.
* Ability to sign, encrypt, decrypt, and verify data.
@@ -50,9 +52,7 @@ defined here -- they correspond directly to certain object types in GPGME
for C. For instance, the following C code:
gpgme_ctx_t context;
-
gpgme_new(&context);
-
...
gpgme_op_encrypt(context, recp, 1, plain, cipher);
@@ -130,8 +130,6 @@ Version information: pyme.version
Utilities: pyme.util
Base classes are documented at pyme.core.
-Classes of pyme.util usually are not instantiated by users
-directly but return by methods of base classes.
"""
diff --git a/lang/python/pyme/core.py b/lang/python/pyme/core.py
index 4b3e08a..293df09 100644
--- a/lang/python/pyme/core.py
+++ b/lang/python/pyme/core.py
@@ -1,3 +1,4 @@
+# Copyright (C) 2016 g10 Code GmbH
# Copyright (C) 2004,2008 Igor Belyi <belyi at users.sourceforge.net>
# Copyright (C) 2002 John Goerzen <jgoerzen at complete.org>
#
@@ -15,14 +16,25 @@
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+"""Core functionality
+
+Core functionality of GPGME wrapped in a object-oriented fashion.
+Provides the 'Context' class for performing cryptographic operations,
+and the 'Data' class describing buffers of data.
+
+"""
+
import weakref
from . import pygpgme
from .errors import errorcheck, GPGMEError
from . import errors
class GpgmeWrapper(object):
- """Base class all Pyme wrappers for GPGME functionality. Not to be
- instantiated directly."""
+ """Base wrapper class
+
+ Not to be instantiated directly.
+
+ """
def __init__(self, wrapped):
self._callback_excinfo = None
@@ -66,7 +78,7 @@ class GpgmeWrapper(object):
raise NotImplementedError()
def __getattr__(self, key):
- """On-the-fly function generation."""
+ """On-the-fly generation of wrapper methods."""
if key[0] == '_' or self._getnameprepend() == None:
return None
name = self._getnameprepend() + key
@@ -98,15 +110,17 @@ class GpgmeWrapper(object):
return wrapper
class Context(GpgmeWrapper):
- """From the GPGME C documentation:
+ """Context for cryptographic operations
+
+ All cryptographic operations in GPGME are performed within a
+ context, which contains the internal state of the operation as
+ well as configuration parameters. By using several contexts you
+ can run several cryptographic operations in parallel, with
+ different configuration.
- * All cryptographic operations in GPGME are performed within a
- * context, which contains the internal state of the operation as well as
- * configuration parameters. By using several contexts you can run
- * several cryptographic operations in parallel, with different
- * configuration.
+ Access to a context must be synchronized.
- Thus, this is the place that you will usually start."""
+ """
def _getctype(self):
return 'gpgme_ctx_t'
@@ -348,18 +362,21 @@ class Context(GpgmeWrapper):
errorcheck(result)
class Data(GpgmeWrapper):
- """From the GPGME C manual:
+ """Data buffer
-* A lot of data has to be exchanged between the user and the crypto
-* engine, like plaintext messages, ciphertext, signatures and information
-* about the keys. The technical details about exchanging the data
-* information are completely abstracted by GPGME. The user provides and
-* receives the data via `gpgme_data_t' objects, regardless of the
-* communication protocol between GPGME and the crypto engine in use.
+ A lot of data has to be exchanged between the user and the crypto
+ engine, like plaintext messages, ciphertext, signatures and
+ information about the keys. The technical details about
+ exchanging the data information are completely abstracted by
+ GPGME. The user provides and receives the data via `gpgme_data_t'
+ objects, regardless of the communication protocol between GPGME
+ and the crypto engine in use.
- This Data class is the implementation of the GpgmeData objects.
+ This Data class is the implementation of the GpgmeData objects.
- Please see the information about __init__ for instantiation."""
+ Please see the information about __init__ for instantiation.
+
+ """
def _getctype(self):
return 'gpgme_data_t'
@@ -393,15 +410,31 @@ class Data(GpgmeWrapper):
(read_cb, write_cb, seek_cb, release_cb[, hook])
- where func is a callback function taking two arguments (count,
- hook) and returning a string of read data, or None on EOF.
- This will supply the read() method for the system.
+ where the first four items are functions implementing reading,
+ writing, seeking the data, and releasing any resources once
+ the data object is deallocated. The functions must match the
+ following prototypes:
+
+ def read(amount, hook=None):
+ return <a b"bytes" object>
+
+ def write(data, hook=None):
+ return <the number of bytes written>
+
+ def seek(offset, whence, hook=None):
+ return <the new file position>
+
+ def release(hook=None):
+ <return value and exceptions are ignored>
+
+ The functions may be bound methods. In that case, you can
+ simply use the 'self' reference instead of using a hook.
If file is specified without any other arguments, then
it must be a filename, and the object will be initialized from
that file.
- Any other use will result in undefined or erroneous behavior."""
+ """
super().__init__(None)
self.data_cbs = None
@@ -488,9 +521,10 @@ class Data(GpgmeWrapper):
"""This wraps the GPGME gpgme_data_new_from_filepart() function.
The argument "file" may be:
- 1. a string specifying a file name, or
- 3. a a file-like object. supporting the fileno() call and the mode
- attribute."""
+ * a string specifying a file name, or
+ * a file-like object supporting the fileno() and the mode attribute.
+
+ """
tmp = pygpgme.new_gpgme_data_t_p()
filename = None
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gpgme.git
More information about the Pkg-gnupg-commit
mailing list