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
| | 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 PurePathIter(FilenamesIter):
"""Iterator for pathlib.PurePath objects."""
def __next__(self):
fname = super().__next__()
return pathlib.PurePath(os.fsdecode(fname))
class Directory(base.NotmuchObject):
"""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.
"""
_msg_p = base.MemoryPointer()
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
@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 (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
"""
ret = capi.lib.notmuch_directory_set_mtime(self._dir_p, 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.
:param mtime: A (time_t) timestamp
:raises: :exc:`NotmuchError`:
:attr:`STATUS`.NOT_INITIALIZED
The directory has not been initialized
"""
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 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.
"""
fnames_p = capi.lib.notmuch_directory_get_child_files(self._dir_p)
return PurePathIter(self, fnames_p)
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.
"""
fnames_p = capi.lib.notmuch_directory_get_child_directories(self._dir_p)
return PurePathIter(self, fnames_p)
@property
def path(self):
"""Returns the absolute path of this Directory (read-only)"""
return self._path
def __repr__(self):
"""Object representation"""
try:
self._dir_p
except errors.ObjectDestroyedError:
return '<Directory(path={self.path}) (exhausted)>'.format(self=self)
else:
return '<Directory(path={self.path})>'.format(self=self)
|