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
| | import os
import pathlib
import notmuch2._base as base
import notmuch2._capi as capi
import notmuch2._errors as errors
from ._message import FilenamesIter
__all__ = ["Directory"]
class PathIter(FilenamesIter):
"""Iterator for pathlib.Path objects."""
def __init__(self, parent, iter_p, basepath=""):
self._basepath = basepath
super().__init__(parent, iter_p)
def __next__(self):
fname = super().__next__()
return pathlib.Path(self._basepath, os.fsdecode(fname))
class Directory(base.NotmuchObject):
"""Represents a directory entry in the notmuch database.
This should not be directly created, instead it will be returned
by calling :meth:`Database.directory`. A directory keeps a
reference to the database object since the database object can not
be released while the directory is in use.
Modifying attributes of this object will modify the
database, not the real directory attributes.
:param path: The absolute path of the directory object.
:type path: str, bytes, os.PathLike or pathlib.Path
:param dir_p: The pointer to an internal notmuch_directory_t object.
:type dir_p: C-api notmuch_directory_t
: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.
:type parent: Database
"""
_msg_p = base.MemoryPointer()
def __init__(self, path, dir_p, parent):
"""
"""
self._path = pathlib.Path(path)
self._dir_p = dir_p
self._parent = parent
@property
def alive(self):
if not self._parent.alive:
return False
try:
self._dir_p
except errors.ObjectDestroyedError:
return False
else:
return True
def __del__(self):
"""Close and free the Directory"""
self._destroy()
def _destroy(self):
if self.alive:
capi.lib.notmuch_directory_destroy(self._dir_p)
self._dir_p = None
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.index_file` 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 POSIX timestamp
:type mtime: int or float
: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
"""
ret = capi.lib.notmuch_directory_set_mtime(self._dir_p, int(mtime))
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
def get_mtime(self):
"""Gets the mtime value of this directory in the database
Retrieves a previously stored mtime for this directory.
:returns: A POSIX timestamp
:rtype: int
"""
return capi.lib.notmuch_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 files(self, absolute=False):
"""Gets a :class:`PathIter` iterator listing all the filenames of
messages in the database within the given directory.
:param absolute: `True` to return complete paths, and `False`
to return basename-entries only (not complete paths),
defaults to `False`
:type absolute: boolean, optional
:returns: An iterator yielding :class:`pathlib.Path` instances.
:rtype: PathIter
"""
fnames_p = capi.lib.notmuch_directory_get_child_files(self._dir_p)
return PathIter(self, fnames_p, self.path if absolute else "")
def directories(self, absolute=False):
"""Gets a :class:`PathIter` iterator listing all the filenames of
sub-directories in the database within the given directory.
:param absolute: `True` to return complete paths, and `False`
to return basename-entries only (not complete paths),
defaults to `False`
:type absolute: boolean, optional
:returns: An iterator yielding :class:`pathlib.Path` instances.
:rtype: PathIter
"""
fnames_p = capi.lib.notmuch_directory_get_child_directories(self._dir_p)
return PathIter(self, fnames_p, self.path if absolute else "")
@property
def path(self):
"""the absolute path of this Directory as a :class:`pathlib.Path` instance.
:rtype: pathlib.Path
"""
return self._path
def __repr__(self):
"""Object representation"""
return '<Directory(path={self.path})>'.format(self=self)
|