]> git.cworth.org Git - obsolete/notmuch-old/blob - bindings/python/notmuch/globals.py
python: add begin|end_atomic bindings
[obsolete/notmuch-old] / bindings / python / notmuch / globals.py
1 """
2 This file is part of notmuch.
3
4 Notmuch is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by the
6 Free Software Foundation, either version 3 of the License, or (at your
7 option) any later version.
8
9 Notmuch is distributed in the hope that it will be useful, but WITHOUT
10 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
12 for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with notmuch.  If not, see <http://www.gnu.org/licenses/>.
16
17 Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
18 """
19
20 from ctypes import CDLL, c_char_p, c_int
21 from ctypes.util import find_library
22
23 #-----------------------------------------------------------------------------
24 #package-global instance of the notmuch library
25 try:
26     nmlib = CDLL("libnotmuch.so.1")
27 except:
28     raise ImportError("Could not find shared 'notmuch' library.")
29
30
31 class Enum(object):
32     """Provides ENUMS as "code=Enum(['a','b','c'])" where code.a=0 etc..."""
33     def __init__(self, names):
34         for number, name in enumerate(names):
35             setattr(self, name, number)
36
37
38 class Status(Enum):
39     """Enum with a string representation of a notmuch_status_t value."""
40     _status2str = nmlib.notmuch_status_to_string
41     _status2str.restype = c_char_p
42     _status2str.argtypes = [c_int]
43
44     def __init__(self, statuslist):
45         """It is initialized with a list of strings that are available as
46         Status().string1 - Status().stringn attributes.
47         """
48         super(Status, self).__init__(statuslist)
49
50     @classmethod
51     def status2str(self, status):
52         """Get a string representation of a notmuch_status_t value."""
53         # define strings for custom error messages
54         if status == STATUS.NOT_INITIALIZED:
55             return "Operation on uninitialized object impossible."
56         return str(Status._status2str(status))
57
58 STATUS = Status(['SUCCESS',
59   'OUT_OF_MEMORY',
60   'READ_ONLY_DATABASE',
61   'XAPIAN_EXCEPTION',
62   'FILE_ERROR',
63   'FILE_NOT_EMAIL',
64   'DUPLICATE_MESSAGE_ID',
65   'NULL_POINTER',
66   'TAG_TOO_LONG',
67   'UNBALANCED_FREEZE_THAW',
68   'UNBALANCED_ATOMIC',
69   'NOT_INITIALIZED'])
70 """STATUS is a class, whose attributes provide constants that serve as return
71 indicators for notmuch functions. Currently the following ones are defined. For
72 possible return values and specific meaning for each method, see the method
73 description.
74
75   * SUCCESS
76   * OUT_OF_MEMORY
77   * READ_ONLY_DATABASE
78   * XAPIAN_EXCEPTION
79   * FILE_ERROR
80   * FILE_NOT_EMAIL
81   * DUPLICATE_MESSAGE_ID
82   * NULL_POINTER
83   * TAG_TOO_LONG
84   * UNBALANCED_FREEZE_THAW
85   * UNBALANCED_ATOMIC
86   * NOT_INITIALIZED
87
88 Invoke the class method `notmuch.STATUS.status2str` with a status value as
89 argument to receive a human readable string"""
90 STATUS.__name__ = 'STATUS'
91
92
93 class NotmuchError(Exception):
94     def __init__(self, status=None, message=None):
95         """Is initiated with a (notmuch.STATUS[,message=None])"""
96         super(NotmuchError, self).__init__(message, status)
97
98     def __str__(self):
99         if self.args[0] is not None:
100             return self.args[0]
101         else:
102             return STATUS.status2str(self.args[1])
103
104 def _str(value):
105     """Ensure a nicely utf-8 encoded string to pass to libnotmuch
106
107     C++ code expects strings to be well formatted and
108     unicode strings to have no null bytes."""
109     if not isinstance(value, basestring):
110         raise TypeError("Expected str or unicode, got %s" % str(type(value)))
111     if isinstance(value, unicode):
112         return value.encode('UTF-8')
113     return value
114