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
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
| | import collections
import contextlib
import os
import pathlib
import weakref
import notmuch2._base as base
import notmuch2._capi as capi
import notmuch2._errors as errors
import notmuch2._tags as tags
__all__ = ['Message']
class Message(base.NotmuchObject):
"""An email message stored in the notmuch database.
This should not be directly created, instead it will be returned
by calling methods on :class:`Database`. A message keeps a
reference to the database object since the database object can not
be released while the message is in use.
Note that this represents a message in the notmuch database. For
full email functionality you may want to use the :mod:`email`
package from Python's standard library. You could e.g. create
this as such::
notmuch_msg = db.get_message(msgid) # or from a query
parser = email.parser.BytesParser(policy=email.policy.default)
with notmuch_msg.path.open('rb) as fp:
email_msg = parser.parse(fp)
Most commonly the functionality provided by notmuch is sufficient
to read email however.
Messages are considered equal when they have the same message ID.
This is how libnotmuch treats messages as well, the
:meth:`pathnames` function returns multiple results for
duplicates.
:param parent: The parent object. This is probably one off a
:class:`Database`, :class:`Thread` or :class:`Query`.
:type parent: NotmuchObject
:param db: The database instance this message is associated with.
This could be the same as the parent.
:type db: Database
:param msg_p: The C pointer to the ``notmuch_message_t``.
:type msg_p: <cdata>
:param dup: Whether the message was a duplicate on insertion.
:type dup: None or bool
"""
_msg_p = base.MemoryPointer()
def __init__(self, parent, msg_p, *, db):
self._parent = parent
self._msg_p = msg_p
self._db = db
@property
def alive(self):
if not self._parent.alive:
return False
try:
self._msg_p
except errors.ObjectDestroyedError:
return False
else:
return True
def __del__(self):
self._destroy()
def _destroy(self):
if self.alive:
capi.lib.notmuch_message_destroy(self._msg_p)
self._msg_p = None
@property
def messageid(self):
"""The message ID as a string.
The message ID is decoded with the ignore error handler. This
is fine as long as the message ID is well formed. If it is
not valid ASCII then this will be lossy. So if you need to be
able to write the exact same message ID back you should use
:attr:`messageidb`.
Note that notmuch will decode the message ID value and thus
strip off the surrounding ``<`` and ``>`` characters. This is
different from Python's :mod:`email` package behaviour which
leaves these characters in place.
:returns: The message ID.
:rtype: :class:`BinString`, this is a normal str but calling
bytes() on it will return the original bytes used to create
it.
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_get_message_id(self._msg_p)
return base.BinString(capi.ffi.string(ret))
@property
def threadid(self):
"""The thread ID.
The thread ID is decoded with the surrogateescape error
handler so that it is possible to reconstruct the original
thread ID if it is not valid UTF-8.
:returns: The thread ID.
:rtype: :class:`BinString`, this is a normal str but calling
bytes() on it will return the original bytes used to create
it.
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_get_thread_id(self._msg_p)
return base.BinString(capi.ffi.string(ret))
@property
def path(self):
"""A pathname of the message as a pathlib.Path instance.
If multiple files in the database contain the same message ID
this will be just one of the files, chosen at random.
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_get_filename(self._msg_p)
return pathlib.Path(os.fsdecode(capi.ffi.string(ret)))
@property
def pathb(self):
"""A pathname of the message as a bytes object.
See :attr:`path` for details, this is the same but does return
the path as a bytes object which is faster but less convenient.
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_get_filename(self._msg_p)
return capi.ffi.string(ret)
def filenames(self):
"""Return an iterator of all files for this message.
If multiple files contained the same message ID they will all
be returned here. The files are returned as intances of
:class:`pathlib.Path`.
:returns: Iterator yielding :class:`pathlib.Path` instances.
:rtype: iter
:raises ObjectDestroyedError: if used after destoryed.
"""
fnames_p = capi.lib.notmuch_message_get_filenames(self._msg_p)
return PathIter(self, fnames_p)
def filenamesb(self):
"""Return an iterator of all files for this message.
This is like :meth:`pathnames` but the files are returned as
byte objects instead.
:returns: Iterator yielding :class:`bytes` instances.
:rtype: iter
:raises ObjectDestroyedError: if used after destoryed.
"""
fnames_p = capi.lib.notmuch_message_get_filenames(self._msg_p)
return FilenamesIter(self, fnames_p)
@property
def ghost(self):
"""Indicates whether this message is a ghost message.
A ghost message if a message which we know exists, but it has
no files or content associated with it. This can happen if
it was referenced by some other message. Only the
:attr:`messageid` and :attr:`threadid` attributes are valid
for it.
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_get_flag(
self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_GHOST)
return bool(ret)
@property
def excluded(self):
"""Indicates whether this message was excluded from the query.
When a message is created from a search, sometimes messages
that where excluded by the search query could still be
returned by it, e.g. because they are part of a thread
matching the query. the :meth:`Database.query` method allows
these messages to be flagged, which results in this property
being set to *True*.
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_get_flag(
self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_EXCLUDED)
return bool(ret)
@property
def date(self):
"""The message date as an integer.
The time the message was sent as an integer number of seconds
since the *epoch*, 1 Jan 1970. This is derived from the
message's header, you can get the original header value with
:meth:`header`.
:raises ObjectDestroyedError: if used after destoryed.
"""
return capi.lib.notmuch_message_get_date(self._msg_p)
def header(self, name):
"""Return the value of the named header.
Returns the header from notmuch, some common headers are
stored in the database, others are read from the file.
Headers are returned with their newlines stripped and
collapsed concatenated together if they occur multiple times.
You may be better off using the standard library email
package's ``email.message_from_file(msg.path.open())`` if that
is not sufficient for you.
:param header: Case-insensitive header name to retrieve.
:type header: str or bytes
:returns: The header value, an empty string if the header is
not present.
:rtype: str
:raises LookupError: if the header is not present.
:raises NullPointerError: For unexpected notmuch errors.
:raises ObjectDestroyedError: if used after destoryed.
"""
# The returned is supposedly guaranteed to be UTF-8. Header
# names must be ASCII as per RFC x822.
if isinstance(name, str):
name = name.encode('ascii')
ret = capi.lib.notmuch_message_get_header(self._msg_p, name)
if ret == capi.ffi.NULL:
raise errors.NullPointerError()
hdr = capi.ffi.string(ret)
if not hdr:
raise LookupError
return hdr.decode(encoding='utf-8')
@property
def tags(self):
"""The tags associated with the message.
This behaves as a set. But removing and adding items to the
set removes and adds them to the message in the database.
:raises ReadOnlyDatabaseError: When manipulating tags on a
database opened in read-only mode.
:raises ObjectDestroyedError: if used after destoryed.
"""
try:
ref = self._cached_tagset
except AttributeError:
tagset = None
else:
tagset = ref()
if tagset is None:
tagset = tags.MutableTagSet(
self, '_msg_p', capi.lib.notmuch_message_get_tags)
self._cached_tagset = weakref.ref(tagset)
return tagset
@contextlib.contextmanager
def frozen(self):
"""Context manager to freeze the message state.
This allows you to perform atomic tag updates::
with msg.frozen():
msg.tags.clear()
msg.tags.add('foo')
Using This would ensure the message never ends up with no tags
applied at all.
It is safe to nest calls to this context manager.
:raises ReadOnlyDatabaseError: if the database is opened in
read-only mode.
:raises UnbalancedFreezeThawError: if you somehow managed to
call __exit__ of this context manager more than once. Why
did you do that?
:raises ObjectDestroyedError: if used after destoryed.
"""
ret = capi.lib.notmuch_message_freeze(self._msg_p)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
self._frozen = True
try:
yield
except Exception:
# Only way to "rollback" these changes is to destroy
# ourselves and re-create. Behold.
msgid = self.messageid
self._destroy()
with contextlib.suppress(Exception):
new = self._db.find(msgid)
self._msg_p = new._msg_p
new._msg_p = None
del new
raise
else:
ret = capi.lib.notmuch_message_thaw(self._msg_p)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
self._frozen = False
@property
def properties(self):
"""A map of arbitrary key-value pairs associated with the message.
Be aware that properties may be used by other extensions to
store state in. So delete or modify with care.
The properties map is somewhat special. It is essentially a
multimap-like structure where each key can have multiple
values. Therefore accessing a single item using
:meth:`PropertiesMap.get` or :meth:`PropertiesMap.__getitem__`
will only return you the *first* item if there are multiple
and thus are only recommended if you know there to be only one
value.
Instead the map has an additional :meth:`PropertiesMap.all`
method which can be used to retrieve all properties of a given
key. This method also allows iterating of a a subset of the
keys starting with a given prefix.
"""
try:
ref = self._cached_props
except AttributeError:
props = None
else:
props = ref()
if props is None:
props = PropertiesMap(self, '_msg_p')
self._cached_props = weakref.ref(props)
return props
def replies(self):
"""Return an iterator of all replies to this message.
This method will only work if the message was created from a
thread. Otherwise it will yield no results.
:returns: An iterator yielding :class:`Message` instances.
:rtype: MessageIter
"""
# The notmuch_messages_valid call accepts NULL and this will
# become an empty iterator, raising StopIteration immediately.
# Hence no return value checking here.
msgs_p = capi.lib.notmuch_message_get_replies(self._msg_p)
return MessageIter(self, msgs_p, db=self._db)
def __hash__(self):
return hash(self.messageid)
def __eq__(self, other):
if isinstance(other, self.__class__):
return self.messageid == other.messageid
class FilenamesIter(base.NotmuchIter):
"""Iterator for binary filenames objects."""
def __init__(self, parent, iter_p):
super().__init__(parent, iter_p,
fn_destroy=capi.lib.notmuch_filenames_destroy,
fn_valid=capi.lib.notmuch_filenames_valid,
fn_get=capi.lib.notmuch_filenames_get,
fn_next=capi.lib.notmuch_filenames_move_to_next)
def __next__(self):
fname = super().__next__()
return capi.ffi.string(fname)
class PathIter(FilenamesIter):
"""Iterator for pathlib.Path objects."""
def __next__(self):
fname = super().__next__()
return pathlib.Path(os.fsdecode(fname))
class PropertiesMap(base.NotmuchObject, collections.abc.MutableMapping):
"""A mutable mapping to manage properties.
Both keys and values of properties are supposed to be UTF-8
strings in libnotmuch. However since the uderlying API uses
bytestrings you can use either str or bytes to represent keys and
all returned keys and values use :class:`BinString`.
Also be aware that ``iter(this_map)`` will return duplicate keys,
while the :class:`collections.abc.KeysView` returned by
:meth:`keys` is a :class:`collections.abc.Set` subclass. This
means the former will yield duplicate keys while the latter won't.
It also means ``len(list(iter(this_map)))`` could be different
than ``len(this_map.keys())``. ``len(this_map)`` will correspond
with the lenght of the default iterator.
Be aware that libnotmuch exposes all of this as iterators, so
quite a few operations have O(n) performance instead of the usual
O(1).
"""
Property = collections.namedtuple('Property', ['key', 'value'])
_marker = object()
def __init__(self, msg, ptr_name):
self._msg = msg
self._ptr = lambda: getattr(msg, ptr_name)
@property
def alive(self):
if not self._msg.alive:
return False
try:
self._ptr
except errors.ObjectDestroyedError:
return False
else:
return True
def _destroy(self):
pass
def __iter__(self):
"""Return an iterator which iterates over the keys.
Be aware that a single key may have multiple values associated
with it, if so it will appear multiple times here.
"""
iter_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
return PropertiesKeyIter(self, iter_p)
def __len__(self):
iter_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
it = base.NotmuchIter(
self, iter_p,
fn_destroy=capi.lib.notmuch_message_properties_destroy,
fn_valid=capi.lib.notmuch_message_properties_valid,
fn_get=capi.lib.notmuch_message_properties_key,
fn_next=capi.lib.notmuch_message_properties_move_to_next,
)
return len(list(it))
def __getitem__(self, key):
"""Return **the first** peroperty associated with a key."""
if isinstance(key, str):
key = key.encode('utf-8')
value_pp = capi.ffi.new('char**')
ret = capi.lib.notmuch_message_get_property(self._ptr(), key, value_pp)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
if value_pp[0] == capi.ffi.NULL:
raise KeyError
return base.BinString.from_cffi(value_pp[0])
def keys(self):
"""Return a :class:`collections.abc.KeysView` for this map.
Even when keys occur multiple times this is a subset of set()
so will only contain them once.
"""
return collections.abc.KeysView({k: None for k in self})
def items(self):
"""Return a :class:`collections.abc.ItemsView` for this map.
The ItemsView treats a ``(key, value)`` pair as unique, so
dupcliate ``(key, value)`` pairs will be merged together.
However duplicate keys with different values will be returned.
"""
items = set()
props_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
while capi.lib.notmuch_message_properties_valid(props_p):
key = capi.lib.notmuch_message_properties_key(props_p)
value = capi.lib.notmuch_message_properties_value(props_p)
items.add((base.BinString.from_cffi(key),
base.BinString.from_cffi(value)))
capi.lib.notmuch_message_properties_move_to_next(props_p)
capi.lib.notmuch_message_properties_destroy(props_p)
return PropertiesItemsView(items)
def values(self):
"""Return a :class:`collecions.abc.ValuesView` for this map.
All unique property values are included in the view.
"""
values = set()
props_p = capi.lib.notmuch_message_get_properties(self._ptr(), b'', 0)
while capi.lib.notmuch_message_properties_valid(props_p):
value = capi.lib.notmuch_message_properties_value(props_p)
values.add(base.BinString.from_cffi(value))
capi.lib.notmuch_message_properties_move_to_next(props_p)
capi.lib.notmuch_message_properties_destroy(props_p)
return PropertiesValuesView(values)
def __setitem__(self, key, value):
"""Add a key-value pair to the properties.
You may prefer to use :meth:`add` for clarity since this
method usually implies implicit overwriting of an existing key
if it exists, while for properties this is not the case.
"""
self.add(key, value)
def add(self, key, value):
"""Add a key-value pair to the properties."""
if isinstance(key, str):
key = key.encode('utf-8')
if isinstance(value, str):
value = value.encode('utf-8')
ret = capi.lib.notmuch_message_add_property(self._ptr(), key, value)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
def __delitem__(self, key):
"""Remove all properties with this key."""
if isinstance(key, str):
key = key.encode('utf-8')
ret = capi.lib.notmuch_message_remove_all_properties(self._ptr(), key)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
def remove(self, key, value):
"""Remove a key-value pair from the properties."""
if isinstance(key, str):
key = key.encode('utf-8')
if isinstance(value, str):
value = value.encode('utf-8')
ret = capi.lib.notmuch_message_remove_property(self._ptr(), key, value)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
def pop(self, key, default=_marker):
try:
value = self[key]
except KeyError:
if default is self._marker:
raise
else:
return default
else:
self.remove(key, value)
return value
def popitem(self):
try:
key = next(iter(self))
except StopIteration:
raise KeyError
value = self.pop(key)
return (key, value)
def clear(self):
ret = capi.lib.notmuch_message_remove_all_properties(self._ptr(),
capi.ffi.NULL)
if ret != capi.lib.NOTMUCH_STATUS_SUCCESS:
raise errors.NotmuchError(ret)
def getall(self, prefix='', *, exact=False):
"""Return an iterator yielding all properties for a given key prefix.
The returned iterator yields all peroperties which start with
a given key prefix as ``(key, value)`` namedtuples. If called
with ``exact=True`` then only properties which exactly match
the prefix are returned, those a key longer than the prefix
will not be included.
:param prefix: The prefix of the key.
"""
if isinstance(prefix, str):
prefix = prefix.encode('utf-8')
props_p = capi.lib.notmuch_message_get_properties(self._ptr(),
prefix, exact)
return PropertiesIter(self, props_p)
class PropertiesKeyIter(base.NotmuchIter):
def __init__(self, parent, iter_p):
super().__init__(
parent,
iter_p,
fn_destroy=capi.lib.notmuch_message_properties_destroy,
fn_valid=capi.lib.notmuch_message_properties_valid,
fn_get=capi.lib.notmuch_message_properties_key,
fn_next=capi.lib.notmuch_message_properties_move_to_next)
def __next__(self):
item = super().__next__()
return base.BinString.from_cffi(item)
class PropertiesIter(base.NotmuchIter):
def __init__(self, parent, iter_p):
super().__init__(
parent,
iter_p,
fn_destroy=capi.lib.notmuch_message_properties_destroy,
fn_valid=capi.lib.notmuch_message_properties_valid,
fn_get=capi.lib.notmuch_message_properties_key,
fn_next=capi.lib.notmuch_message_properties_move_to_next,
)
def __next__(self):
if not self._fn_valid(self._iter_p):
self._destroy()
raise StopIteration
key = capi.lib.notmuch_message_properties_key(self._iter_p)
value = capi.lib.notmuch_message_properties_value(self._iter_p)
capi.lib.notmuch_message_properties_move_to_next(self._iter_p)
return PropertiesMap.Property(base.BinString.from_cffi(key),
base.BinString.from_cffi(value))
class PropertiesItemsView(collections.abc.Set):
__slots__ = ('_items',)
def __init__(self, items):
self._items = items
@classmethod
def _from_iterable(self, it):
return set(it)
def __len__(self):
return len(self._items)
def __contains__(self, item):
return item in self._items
def __iter__(self):
yield from self._items
collections.abc.ItemsView.register(PropertiesItemsView)
class PropertiesValuesView(collections.abc.Set):
__slots__ = ('_values',)
def __init__(self, values):
self._values = values
def __len__(self):
return len(self._values)
def __contains__(self, value):
return value in self._values
def __iter__(self):
yield from self._values
collections.abc.ValuesView.register(PropertiesValuesView)
class MessageIter(base.NotmuchIter):
def __init__(self, parent, msgs_p, *, db):
self._db = db
super().__init__(parent, msgs_p,
fn_destroy=capi.lib.notmuch_messages_destroy,
fn_valid=capi.lib.notmuch_messages_valid,
fn_get=capi.lib.notmuch_messages_get,
fn_next=capi.lib.notmuch_messages_move_to_next)
def __next__(self):
msg_p = super().__next__()
return Message(self, msg_p, db=self._db)
|