git.notmuchmail.org Git - notmuch/blob - bindings/python/notmuch/filename.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 from ctypes import c_char_p
  20 from notmuch.globals import (
  21     nmlib,
  22     NullPointerError,
  23     NotInitializedError,
  24     NotmuchMessageP,
  25     NotmuchFilenamesP,
  26     Python3StringMixIn,
  27 )
  28
  29
  30 class Filenames(Python3StringMixIn):
  31     """Represents a list of filenames as returned by notmuch
  32
  33     This object contains the Filenames iterator. The main function is
  34     as_generator() which will return a generator so we can do a Filenamesth an
  35     iterator over a list of notmuch filenames. Do note that the underlying
  36     library only provides a one-time iterator (it cannot reset the iterator to
  37     the start). Thus iterating over the function will "exhaust" the list of
  38     tags, and a subsequent iteration attempt will raise a
  39     :exc:`NotInitializedError`. Also note, that any function that uses
  40     iteration (nearly all) will also exhaust the tags. So both::
  41
  42       for name in filenames: print name
  43
  44     as well as::
  45
  46        number_of_names = len(names)
  47
  48     and even a simple::
  49
  50        #str() iterates over all tags to construct a space separated list
  51        print(str(filenames))
  52
  53     will "exhaust" the Filenames. However, you can use
  54     :meth:`Message.get_filenames` repeatedly to get fresh Filenames
  55     objects to perform various actions on filenames.
  56     """
  57
  58     #notmuch_filenames_get
  59     _get = nmlib.notmuch_filenames_get
  60     _get.argtypes = [NotmuchFilenamesP]
  61     _get.restype = c_char_p
  62
  63     def __init__(self, files_p, parent):
  64         """
  65         :param files_p: A pointer to an underlying *notmuch_tags_t*
  66              structure. These are not publically exposed, so a user
  67              will almost never instantiate a :class:`Tags` object
  68              herself. They are usually handed back as a result,
  69              e.g. in :meth:`Database.get_all_tags`.  *tags_p* must be
  70              valid, we will raise an :exc:`NullPointerError`
  71              if it is `None`.
  72         :type files_p: :class:`ctypes.c_void_p`
  73         :param parent: The parent object (ie :class:`Message` these
  74              filenames are derived from, and saves a
  75              reference to it, so we can automatically delete the db object
  76              once all derived objects are dead.
  77         """
  78         if not files_p:
  79             raise NullPointerError()
  80
  81         self._files = files_p
  82         #save reference to parent object so we keep it alive
  83         self._parent = parent
  84
  85     _valid = nmlib.notmuch_filenames_valid
  86     _valid.argtypes = [NotmuchFilenamesP]
  87     _valid.restype = bool
  88
  89     _move_to_next = nmlib.notmuch_filenames_move_to_next
  90     _move_to_next.argtypes = [NotmuchFilenamesP]
  91     _move_to_next.restype = None
  92
  93     def as_generator(self):
  94         """Return generator of Filenames
  95
  96         This is the main function that will usually be used by the
  97         user."""
  98         if not self._files:
  99             raise NotInitializedError()
 100
 101         while self._valid(self._files):
 102             yield Filenames._get(self._files).decode('utf-8', 'ignore')
 103             self._move_to_next(self._files)
 104
 105         self._files = None
 106
 107     def __unicode__(self):
 108         """Represent Filenames() as newline-separated list of full paths
 109
 110         .. note:: As this iterates over the filenames, we will not be
 111                able to iterate over them again (as in retrieve them)! If
 112                the tags have been exhausted already, this will raise a
 113                :exc:`NotInitializedError` on subsequent
 114                attempts. However, you can use
 115                :meth:`Message.get_filenames` repeatedly to perform
 116                various actions on filenames.
 117         """
 118         return "\n".join(self)
 119
 120     _destroy = nmlib.notmuch_filenames_destroy
 121     _destroy.argtypes = [NotmuchMessageP]
 122     _destroy.restype = None
 123
 124     def __del__(self):
 125         """Close and free the notmuch filenames"""
 126         if self._files is not None:
 127             self._destroy(self._files)