unofficial mirror of notmuch@notmuchmail.org
 help / color / mirror / code / Atom feed
blob 0c5e015e0e01feb9da330e08c2de951f54ed7797 6891 bytes (raw)
name: bindings/python/notmuch/directory.py 	 # note: path name is non-authoritative(*)

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
"""
This file is part of notmuch.

Notmuch is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.

Notmuch 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 General Public License
for more details.

You should have received a copy of the GNU General Public License
along with notmuch.  If not, see <http://www.gnu.org/licenses/>.

Copyright 2010 Sebastian Spaeth <Sebastian@SSpaeth.de>'
"""

from ctypes import c_uint, c_long
from notmuch.globals import (
    nmlib,
    NotmuchDirectoryP,
    NotmuchFilenamesP
)
from .errors import (
    STATUS,
    NotmuchError,
    NotInitializedError,
)
from .filenames import Filenames

class Directory(object):
    """Represents a directory entry in the notmuch directory

    Modifying attributes of this object will modify the
    database, not the real directory attributes.

    The Directory object is usually derived from another object
    e.g. via :meth:`Database.get_directory`, and will automatically be
    become invalid whenever that parent is deleted. You should
    therefore initialized this object handing it a reference to the
    parent, preventing the parent from automatically being garbage
    collected.
    """

    """notmuch_directory_get_mtime"""
    _get_mtime = nmlib.notmuch_directory_get_mtime
    _get_mtime.argtypes = [NotmuchDirectoryP]
    _get_mtime.restype = c_long

    """notmuch_directory_set_mtime"""
    _set_mtime = nmlib.notmuch_directory_set_mtime
    _set_mtime.argtypes = [NotmuchDirectoryP, c_long]
    _set_mtime.restype = c_uint

    """notmuch_directory_get_child_files"""
    _get_child_files = nmlib.notmuch_directory_get_child_files
    _get_child_files.argtypes = [NotmuchDirectoryP]
    _get_child_files.restype = NotmuchFilenamesP

    """notmuch_directory_get_child_directories"""
    _get_child_directories = nmlib.notmuch_directory_get_child_directories
    _get_child_directories.argtypes = [NotmuchDirectoryP]
    _get_child_directories.restype = NotmuchFilenamesP

    def _assert_dir_is_initialized(self):
        """Raises a NotmuchError(:attr:`STATUS`.NOT_INITIALIZED)
        if dir_p is None"""
        if not self._dir_p:
            raise NotInitializedError()

    def __init__(self, path, dir_p, parent):
        """
        :param path:   The absolute path of the directory object.
        :param dir_p:  The pointer to an internal notmuch_directory_t object.
        :param parent: The object this Directory is derived from
                       (usually a :class:`Database`). We do not directly use
                       this, but store a reference to it as long as
                       this Directory object lives. This keeps the
                       parent object alive.
        """
        self._path = path
        self._dir_p = dir_p
        self._parent = parent

    def set_mtime(self, mtime):
        """Sets the mtime value of this directory in the database

        The intention is for the caller to use the mtime to allow efficient
        identification of new messages to be added to the database. The
        recommended usage is as follows:

        * Read the mtime of a directory from the filesystem

        * Call :meth:`Database.add_message` for all mail files in
          the directory

        * Call notmuch_directory_set_mtime with the mtime read from the
          filesystem.  Then, when wanting to check for updates to the
          directory in the future, the client can call :meth:`get_mtime`
          and know that it only needs to add files if the mtime of the
          directory and files are newer than the stored timestamp.

          .. note::

                :meth:`get_mtime` function does not allow the caller to
                distinguish a timestamp of 0 from a non-existent timestamp. So
                don't store a timestamp of 0 unless you are comfortable with
                that.

        :param mtime: A (time_t) timestamp
        :raises: :exc:`XapianError` a Xapian exception occurred, mtime
                 not stored
        :raises: :exc:`ReadOnlyDatabaseError` the database was opened
                 in read-only mode so directory mtime cannot be modified
        :raises: :exc:`NotInitializedError` the directory object has not
                 been initialized
        """
        self._assert_dir_is_initialized()
        status = Directory._set_mtime(self._dir_p, mtime)

        if status != STATUS.SUCCESS:
            raise NotmuchError(status)

    def get_mtime(self):
        """Gets the mtime value of this directory in the database

        Retrieves a previously stored mtime for this directory.

        :param mtime: A (time_t) timestamp
        :raises: :exc:`NotmuchError`:

                        :attr:`STATUS`.NOT_INITIALIZED
                          The directory has not been initialized
        """
        self._assert_dir_is_initialized()
        return Directory._get_mtime(self._dir_p)

    # Make mtime attribute a property of Directory()
    mtime = property(get_mtime, set_mtime, doc="""Property that allows getting
                     and setting of the Directory *mtime* (read-write)

                     See :meth:`get_mtime` and :meth:`set_mtime` for usage and
                     possible exceptions.""")

    def get_child_files(self):
        """Gets a Filenames iterator listing all the filenames of
        messages in the database within the given directory.

        The returned filenames will be the basename-entries only (not
        complete paths.
        """
        self._assert_dir_is_initialized()
        files_p = Directory._get_child_files(self._dir_p)
        return Filenames(files_p, self)

    def get_child_directories(self):
        """Gets a :class:`Filenames` iterator listing all the filenames of
        sub-directories in the database within the given directory

        The returned filenames will be the basename-entries only (not
        complete paths.
        """
        self._assert_dir_is_initialized()
        files_p = Directory._get_child_directories(self._dir_p)
        return Filenames(files_p, self)

    @property
    def path(self):
        """Returns the absolute path of this Directory (read-only)"""
        return self._path

    def __repr__(self):
        """Object representation"""
        return "<notmuch Directory object '%s'>" % self._path

    _destroy = nmlib.notmuch_directory_destroy
    _destroy.argtypes = [NotmuchDirectoryP]
    _destroy.argtypes = None

    def __del__(self):
        """Close and free the Directory"""
        if self._dir_p is not None:
            self._destroy(self._dir_p)

debug log:

solving 0c5e015 ...
found 0c5e015 in https://yhetil.org/notmuch.git/

(*) Git path names are given by the tree(s) the blob belongs to.
    Blobs themselves have no identifier aside from the hash of its contents.^

Code repositories for project(s) associated with this public inbox

	https://yhetil.org/notmuch.git/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).