Files and directories¶
Filenames
– An iterator over filenames¶
-
class
Filenames
(files_p, parent)¶ Represents a list of filenames as returned by notmuch
Objects of this class implement the iterator protocol.
Note
The underlying library only provides a one-time iterator (it cannot reset the iterator to the start). Thus iterating over the function will “exhaust” the list of tags, and a subsequent iteration attempt will raise a
NotInitializedError
. Also note, that any function that uses iteration (nearly all) will also exhaust the tags. So both:for name in filenames: print name
as well as:
list_of_names = list(names)
and even a simple:
#str() iterates over all tags to construct a space separated list print(str(filenames))
will “exhaust” the Filenames. However, you can use
Message.get_filenames()
repeatedly to get fresh Filenames objects to perform various actions on filenames.Parameters: - files_p (
ctypes.c_void_p
) – A pointer to an underlying notmuch_tags_t structure. These are not publicly exposed, so a user will almost never instantiate aTags
object herself. They are usually handed back as a result, e.g. inDatabase.get_all_tags()
. tags_p must be valid, we will raise anNullPointerError
if it is None. - parent – The parent object (ie
Message
these filenames are derived from, and saves a reference to it, so we can automatically delete the db object once all derived objects are dead.
-
__len__
()¶
Warning
__len__()
was removed in version 0.22 as it exhausted the iterator and broke list(Filenames()). Use len(list(names)) instead.- files_p (
Directory
– A directory entry in the database¶
-
class
Directory
(path, dir_p, parent)¶ 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
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.Parameters: - path – The absolute path of the directory object.
- dir_p – The pointer to an internal notmuch_directory_t object.
- parent – The object this Directory is derived from
(usually a
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.
-
get_child_files
()¶ 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.
-
get_child_directories
()¶ Gets a
Filenames
iterator listing all the filenames of sub-directories in the database within the given directoryThe returned filenames will be the basename-entries only (not complete paths.
-
get_mtime
()¶ Gets the mtime value of this directory in the database
Retrieves a previously stored mtime for this directory.
Parameters: mtime – A (time_t) timestamp
Raises: STATUS
.NOT_INITIALIZEDThe directory has not been initialized
-
set_mtime
(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
Database.index_file()
for all mail files in the directoryCall 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
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
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.
Parameters: mtime – A (time_t) timestamp Raises: XapianError
a Xapian exception occurred, mtime not storedRaises: ReadOnlyDatabaseError
the database was opened in read-only mode so directory mtime cannot be modifiedRaises: NotInitializedError
the directory object has not been initialized
-
mtime
¶ Property that allows getting and setting of the Directory mtime (read-write)
See
get_mtime()
andset_mtime()
for usage and possible exceptions.
-
path
¶ Returns the absolute path of this Directory (read-only)