git.notmuchmail.org Git - notmuch/blob - cnotmuch/database.py

   1 import ctypes
   2 from ctypes import c_int, c_char_p, c_void_p
   3 from cnotmuch.globals import nmlib, STATUS, NotmuchError
   4 import logging
   5
   6 class Database(object):
   7     """ Wrapper around a notmuch_database_t
   8
   9     Do note that as soon as we tear down this object, all derived queries,
  10     threads, and messages will be freed as well.
  11     """
  12     #constants
  13     MODE_READ_ONLY = 0
  14     MODE_READ_WRITE = 1
  15
  16     _std_db_path = None
  17     """Class attribute of users default database"""
  18
  19     """notmuch_database_get_path (notmuch_database_t *database)"""
  20     _get_path = nmlib.notmuch_database_get_path
  21     _get_path.restype = c_char_p
  22
  23     """notmuch_database_open (const char *path, notmuch_database_mode_t mode)"""
  24     _open = nmlib.notmuch_database_open
  25     _open.restype = c_void_p
  26
  27     """ notmuch_database_find_message """
  28     _find_message = nmlib.notmuch_database_find_message
  29     _find_message.restype = c_void_p
  30
  31     """notmuch_database_get_all_tags (notmuch_database_t *database)"""
  32     _get_all_tags = nmlib.notmuch_database_get_all_tags
  33     _get_all_tags.restype = c_void_p
  34
  35     """ notmuch_database_create(const char *path):"""
  36     _create = nmlib.notmuch_database_create
  37     _create.restype = c_void_p
  38
  39     def __init__(self, path=None, create=False, status= MODE_READ_ONLY):
  40         """ Open or create a notmuch database
  41
  42         If path is None, we will try to read a users notmuch configuration and
  43         use his default database.
  44         Throws a NotmuchError in case of failure.
  45         """
  46         self._db = None
  47         if path is None:
  48             # no path specified. use a user's default database
  49             if Database._std_db_path is None:
  50                 #the following line throws a NotmuchError if it fails
  51                 Database._std_db_path = self._get_user_default_db()
  52             path = Database._std_db_path
  53
  54         if create == False:
  55             self.open(path, status)
  56         else:
  57             self.create(path, status)
  58
  59     def create(self, path, status=MODE_READ_ONLY):
  60         """ notmuch_database_create(const char *path)
  61
  62         :returns: Raises :exc:`notmuch.NotmuchError` in case
  63                   of any failure (after printing an error message on stderr).
  64         """
  65         res = Database._create(path, status)
  66
  67         if res is None:
  68             raise NotmuchError(
  69                 message="Could not create the specified database")
  70         self._db = res
  71
  72     def open(self, path, status= MODE_READ_ONLY):
  73         """calls notmuch_database_open
  74
  75         :returns: Raises :exc:`notmuch.NotmuchError` in case
  76                   of any failure (after printing an error message on stderr).
  77         """
  78         res = Database._open(path, status)
  79
  80         if res is None:
  81             raise NotmuchError(
  82                 message="Could not open the specified database")
  83         self._db = res
  84
  85     def get_path(self):
  86         """notmuch_database_get_path (notmuch_database_t *database);  """
  87         return Database._get_path(self._db)
  88
  89     def find_message(self, msgid):
  90         """notmuch_database_find_message
  91         :param msgid: The message id
  92         :ptype msgid: string
  93
  94         :returns: Message() or None if no message is found or if an
  95                   out-of-memory situation occurs.
  96         """
  97         if self._db is None:
  98             raise NotmuchError(STATUS.NOT_INITIALIZED)
  99         msg_p = Database._find_message(self._db, msgid)
 100         if msg_p is None:
 101             return None
 102         return Message(msg_p, self)
 103
 104     def get_all_tags(self):
 105         """Return a Tags() object (list of all tags found in the database)
 106
 107         :returns: Tags() object or raises :exc:`NotmuchError` with
 108                   STATUS.NULL_POINTER on error
 109         """
 110         if self._db is None:
 111             raise NotmuchError(STATUS.NOT_INITIALIZED)
 112
 113         tags_p = Database._get_all_tags (self._db)
 114         if tags_p == None:
 115             raise NotmuchError(STATUS.NULL_POINTER)
 116         return Tags(tags_p, self)
 117
 118     def __repr__(self):
 119         return "'Notmuch DB " + self.get_path() + "'"
 120
 121     def __del__(self):
 122         """Close and free the notmuch database if needed"""
 123         if self._db is not None:
 124             logging.debug("Freeing the database now")
 125             nmlib.notmuch_database_close(self._db)
 126
 127     def _get_user_default_db(self):
 128         """ Reads a user's notmuch config and returns his db location
 129
 130         Throws a NotmuchError if it cannot find it"""
 131         from ConfigParser import SafeConfigParser
 132         import os.path
 133         config = SafeConfigParser()
 134         config.read(os.path.expanduser('~/.notmuch-config'))
 135         if not config.has_option('database','path'):
 136             raise NotmuchError(message=
 137                                "No DB path specified and no user default found")
 138         return config.get('database','path')
 139
 140     @property
 141     def db_p(self):
 142         """Returns a pointer to the current notmuch_database_t or None"""
 143         return self._db
 144
 145 #------------------------------------------------------------------------------
 146 class Query(object):
 147     """ Wrapper around a notmuch_query_t
 148
 149     Do note that as soon as we tear down this object, all derived
 150     threads, and messages will be freed as well.
 151     """
 152     # constants
 153     SORT_OLDEST_FIRST = 0
 154     SORT_NEWEST_FIRST = 1
 155     SORT_MESSAGE_ID = 2
 156
 157     """notmuch_query_create"""
 158     _create = nmlib.notmuch_query_create
 159     _create.restype = c_void_p
 160
 161     """notmuch_query_search_messages"""
 162     _search_messages = nmlib.notmuch_query_search_messages
 163     _search_messages.restype = c_void_p
 164
 165     def __init__(self, db, querystr):
 166         """TODO: document"""
 167         self._db = None
 168         self._query = None
 169         self.create(db, querystr)
 170
 171     def create(self, db, querystr):
 172         """db is a Database() and querystr a string
 173
 174         raises NotmuchError STATUS.NOT_INITIALIZED if db is not inited and
 175         STATUS.NULL_POINTER if the query creation failed (too little memory)
 176         """
 177         if db.db_p is None:
 178             raise NotmuchError(STATUS.NOT_INITIALIZED)
 179         # create reference to parent db to keep it alive
 180         self._db = db
 181
 182         # create query, return None if too little mem available
 183         query_p = Query._create(db.db_p, querystr)
 184         if query_p is None:
 185             NotmuchError(STATUS.NULL_POINTER)
 186         self._query = query_p
 187
 188
 189     def search_messages(self):
 190         """notmuch_query_search_messages
 191         Returns Messages() or a raises a NotmuchError()
 192         """
 193         if self._query is None:
 194             raise NotmuchError(STATUS.NOT_INITIALIZED)
 195
 196         msgs_p = Query._search_messages(self._query)
 197
 198         if msgs_p is None:
 199             NotmuchError(STATUS.NULL_POINTER)
 200
 201         return Messages(msgs_p,self)
 202
 203
 204     def __del__(self):
 205         """Close and free the Query"""
 206         if self._query is not None:
 207             logging.debug("Freeing the Query now")
 208             nmlib.notmuch_query_destroy (self._query)
 209
 210 #------------------------------------------------------------------------------
 211 class Tags(object):
 212     """Wrapper around notmuch_tags_t"""
 213
 214     #notmuch_tags_get
 215     _get = nmlib.notmuch_tags_get
 216     _get.restype = c_char_p
 217
 218     def __init__(self, tags_p, db=None):
 219         """
 220         msg_p is a pointer to an notmuch_message_t Structure. If it is None,
 221         we will raise an NotmuchError(STATUS.NULL_POINTER).
 222
 223         Is passed the db these tags are derived from, and saves a
 224         reference to it, so we can automatically delete the db object
 225         once all derived objects are dead.
 226
 227         Tags() provides an iterator over all contained tags. However, you will
 228         only be able to iterate over the Tags once, because the underlying C
 229         function only allows iterating once.
 230         #TODO: make the iterator work more than once and cache the tags in
 231                the Python object.
 232         """
 233         if tags_p is None:
 234             NotmuchError(STATUS.NULL_POINTER)
 235
 236         self._tags = tags_p
 237         self._db = db
 238         logging.debug("Inited Tags derived from %s" %(str(db)))
 239
 240     def __iter__(self):
 241         """ Make Tags an iterator """
 242         return self
 243
 244     def next(self):
 245         if self._tags is None:
 246             raise NotmuchError(STATUS.NOT_INITIALIZED)
 247
 248         if not nmlib.notmuch_tags_valid(self._tags):
 249             self._tags = None
 250             raise StopIteration
 251
 252         tag = Tags._get (self._tags)
 253         nmlib.notmuch_tags_move_to_next(self._tags)
 254         return tag
 255
 256     def __str__(self):
 257         """str() of Tags() is a space separated list of tags
 258
 259         This iterates over the list of Tags and will therefore 'exhaust' Tags()
 260         """
 261         return " ".join(self)
 262
 263     def __del__(self):
 264         """Close and free the notmuch tags"""
 265         if self._tags is not None:
 266             logging.debug("Freeing the Tags now")
 267             nmlib.notmuch_tags_destroy (self._tags)
 268
 269
 270 #------------------------------------------------------------------------------
 271 class Messages(object):
 272     """Wrapper around notmuch_messages_t"""
 273
 274     #notmuch_tags_get
 275     _get = nmlib.notmuch_messages_get
 276     _get.restype = c_void_p
 277
 278     _collect_tags = nmlib.notmuch_messages_collect_tags
 279     _collect_tags.restype = c_void_p
 280
 281     def __init__(self, msgs_p, parent=None):
 282         """
 283         msg_p is a pointer to an notmuch_messages_t Structure. If it is None,
 284         we will raise an NotmuchError(STATUS.NULL_POINTER).
 285
 286         If passed the parent query this Messages() is derived from, it saves a
 287         reference to it, so we can automatically delete the parent query object
 288         once all derived objects are dead.
 289
 290         Messages() provides an iterator over all contained Message()s.
 291         However, you will only be able to iterate over it once,
 292         because the underlying C function only allows iterating once.
 293         #TODO: make the iterator work more than once and cache the tags in
 294                the Python object.
 295         """
 296         if msgs_p is None:
 297             NotmuchError(STATUS.NULL_POINTER)
 298
 299         self._msgs = msgs_p
 300         #store parent, so we keep them alive as long as self  is alive
 301         self._parent = parent
 302         logging.debug("Inited Messages derived from %s" %(str(parent)))
 303
 304     def collect_tags(self):
 305         """ return the Tags() belonging to the messages
 306
 307         Do note that collect_tags will iterate over the messages and
 308         therefore will not allow further iterationsl
 309         Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
 310         """
 311         if self._msgs is None:
 312             raise NotmuchError(STATUS.NOT_INITIALIZED)
 313
 314         # collect all tags (returns NULL on error)
 315         tags_p = Messages._collect_tags (self._msgs)
 316         #reset _msgs as we iterated over it and can do so only once
 317         self._msgs = None
 318
 319         if tags_p == None:
 320             raise NotmuchError(STATUS.NULL_POINTER)
 321         return Tags(tags_p, self)
 322
 323     def __iter__(self):
 324         """ Make Messages an iterator """
 325         return self
 326
 327     def next(self):
 328         if self._msgs is None:
 329             raise NotmuchError(STATUS.NOT_INITIALIZED)
 330
 331         if not nmlib.notmuch_messages_valid(self._msgs):
 332             self._msgs = None
 333             raise StopIteration
 334
 335         msg = Message(Messages._get (self._msgs), self)
 336         nmlib.notmuch_messages_move_to_next(self._msgs)
 337         return msg
 338
 339     def __len__(self):
 340         """ Returns the number of contained messages
 341
 342         :note: As this iterates over the messages, we will not be able to
 343                iterate over them again (as in retrieve them)!
 344         """
 345         if self._msgs is None:
 346             raise NotmuchError(STATUS.NOT_INITIALIZED)
 347
 348         i=0
 349         while nmlib.notmuch_messages_valid(self._msgs):
 350             nmlib.notmuch_messages_move_to_next(self._msgs)
 351             i += 1
 352         self._msgs = None
 353         return i
 354
 355
 356
 357     def __del__(self):
 358         """Close and free the notmuch Messages"""
 359         if self._msgs is not None:
 360             logging.debug("Freeing the Messages now")
 361             nmlib.notmuch_messages_destroy (self._msgs)
 362
 363
 364 #------------------------------------------------------------------------------
 365 class Message(object):
 366     """Wrapper around notmuch_message_t"""
 367
 368     """notmuch_message_get_filename (notmuch_message_t *message)"""
 369     _get_filename = nmlib.notmuch_message_get_filename
 370     _get_filename.restype = c_char_p
 371     """notmuch_message_get_message_id (notmuch_message_t *message)"""
 372     _get_message_id = nmlib.notmuch_message_get_message_id
 373     _get_message_id.restype = c_char_p
 374
 375     """notmuch_message_get_tags (notmuch_message_t *message)"""
 376     _get_tags = nmlib.notmuch_message_get_tags
 377     _get_tags.restype = c_void_p
 378
 379     def __init__(self, msg_p, parent=None):
 380         """
 381         msg_p is a pointer to an notmuch_message_t Structure. If it is None,
 382         we will raise an NotmuchError(STATUS.NULL_POINTER).
 383
 384         Is a 'parent' object is passed which this message is derived from,
 385         we save a reference to it, so we can automatically delete the parent
 386         object once all derived objects are dead.
 387         """
 388         if msg_p is None:
 389             NotmuchError(STATUS.NULL_POINTER)
 390         self._msg = msg_p
 391         #keep reference to parent, so we keep it alive
 392         self._parent = parent
 393         logging.debug("Inited Message derived from %s" %(str(parent)))
 394
 395
 396     def get_message_id(self):
 397         """ return the msg id
 398
 399         Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
 400         """
 401         if self._msg is None:
 402             raise NotmuchError(STATUS.NOT_INITIALIZED)
 403         return Message._get_message_id(self._msg)
 404
 405
 406     def get_filename(self):
 407         """ return the msg filename
 408
 409         Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
 410         """
 411         if self._msg is None:
 412             raise NotmuchError(STATUS.NOT_INITIALIZED)
 413         return Message._get_filename(self._msg)
 414
 415     def get_tags(self):
 416         """ return the msg tags
 417
 418         Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
 419         Raises NotmuchError(STATUS.NULL_POINTER) on error.
 420         """
 421         if self._msg is None:
 422             raise NotmuchError(STATUS.NOT_INITIALIZED)
 423
 424         tags_p = Message._get_tags(self._msg)
 425         if tags_p == None:
 426             raise NotmuchError(STATUS.NULL_POINTER)
 427         return Tags(tags_p, self)
 428
 429     def __del__(self):
 430         """Close and free the notmuch Message"""
 431         if self._msg is not None:
 432             logging.debug("Freeing the Message now")
 433             nmlib.notmuch_message_destroy (self._msg)