python: Add an idiomatic interface.
[gpgme.git] / lang / python / pyme / __init__.py
1 # Copyright (C) 2016 g10 Code GmbH
2 # Copyright (C) 2004 Igor Belyi <belyi@users.sourceforge.net>
3 # Copyright (C) 2002 John Goerzen <jgoerzen@complete.org>
4 #
5 # This library is free software; you can redistribute it and/or
6 # modify it under the terms of the GNU Lesser General Public
7 # License as published by the Free Software Foundation; either
8 # version 2.1 of the License, or (at your option) any later version.
9 #
10 # This library is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13 # Lesser General Public License for more details.
14 #
15 # You should have received a copy of the GNU Lesser General Public
16 # License along with this library; if not, write to the Free Software
17 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
18
19 """Pyme: GPGME Interface for Python
20
21 Welcome to PyME, the GPGME Interface for Python.  "Pyme", when prounced,
22 rhymes with "Pine".
23
24 The latest release of this package may be obtained from
25 https://www.gnupg.org
26
27 Previous releases of this package for Python 2 can be obtained from
28 http://pyme.sourceforge.net
29
30 FEATURES
31 --------
32
33  * Feature-rich, full implementation of the GPGME library.  Supports
34    all GPGME features.  Callback functions may be written in pure
35    Python.  Exceptions raised in callbacks are properly propagated.
36
37  * Ability to sign, encrypt, decrypt, and verify data.
38
39  * Ability to list keys, export and import keys, and manage the keyring.
40
41  * Fully object-oriented with convenient classes and modules.
42
43 QUICK EXAMPLE
44 -------------
45
46     >>> import pyme
47     >>> with pyme.Context() as c:
48     >>> with pyme.Context() as c:
49     ...     cipher, _, _ = c.encrypt("Hello world :)".encode(),
50     ...                              passphrase="abc")
51     ...     c.decrypt(cipher, passphrase="abc")
52     ...
53     (b'Hello world :)',
54      <pyme.results.DecryptResult object at 0x7f5ab8121080>,
55      <pyme.results.VerifyResult object at 0x7f5ab81219b0>)
56
57 GENERAL OVERVIEW
58 ----------------
59
60 For those of you familiar with GPGME, you will be right at home here.
61
62 Pyme is, for the most part, a direct interface to the C GPGME
63 library.  However, it is re-packaged in a more Pythonic way --
64 object-oriented with classes and modules.  Take a look at the classes
65 defined here -- they correspond directly to certain object types in GPGME
66 for C.  For instance, the following C code:
67
68 gpgme_ctx_t context;
69 gpgme_new(&context);
70 ...
71 gpgme_op_encrypt(context, recp, 1, plain, cipher);
72
73 Translates into the following Python code:
74
75 context = core.Context()
76 ...
77 context.op_encrypt(recp, 1, plain, cipher)
78
79 The Python module automatically does error-checking and raises Python
80 exception pyme.errors.GPGMEError when GPGME signals an error. getcode()
81 and getsource() of this exception return code and source of the error.
82
83 IMPORTANT NOTE
84 --------------
85 This documentation only covers a small subset of available GPGME functions and
86 methods.  Please consult the documentation for the C library
87 for comprehensive coverage.
88
89 This library uses Python's reflection to automatically detect the methods
90 that are available for each class, and as such, most of those methods
91 do not appear explicitly anywhere. You can use dir() python built-in command
92 on an object to see what methods and fields it has but their meaning can
93 be found only in GPGME documentation.
94
95 FOR MORE INFORMATION
96 --------------------
97 PYME3 homepage: https://www.gnupg.org/
98 GPGME documentation: https://www.gnupg.org/documentation/manuals/gpgme/
99
100 """
101
102 __all__ = ['core', 'errors', 'constants', 'util', 'callbacks', 'version']
103
104 from .core import Context
105 from .core import Data