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@g10code.com>
This commit is contained in:
Justus Winter
parent
7eef399d89
commit
5492853d7b
@ -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 $@
|
||||
|
||||
|
||||
57
lang/python/README
Normal file
57
lang/python/README
Normal file
@ -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
|
||||
@ -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/
|
||||
@ -1,36 +1,38 @@
|
||||
"""
|
||||
Pyme: GPGME Interface for Python
|
||||
Copyright (C) 2004 Igor Belyi <belyi@users.sourceforge.net>
|
||||
Copyright (C) 2002 John Goerzen <jgoerzen@complete.org>
|
||||
# Copyright (C) 2016 g10 Code GmbH
|
||||
# Copyright (C) 2004 Igor Belyi <belyi@users.sourceforge.net>
|
||||
# Copyright (C) 2002 John Goerzen <jgoerzen@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
|
||||
|
||||
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.
|
||||
|
||||
"""
|
||||
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
# Copyright (C) 2016 g10 Code GmbH
|
||||
# Copyright (C) 2004,2008 Igor Belyi <belyi@users.sourceforge.net>
|
||||
# Copyright (C) 2002 John Goerzen <jgoerzen@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.
|
||||
|
||||
Thus, this is the place that you will usually start."""
|
||||
Access to a context must be synchronized.
|
||||
|
||||
"""
|
||||
|
||||
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user