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 | class Where:
"""Lazy IMAP search; runs on iterate, list, count or exists."""
CHUNK_SIZE = 100
def __init__(
self,
*,
client: imaplib.IMAP4_SSL,
mailbox: MailBox,
query: Optional[QueryLike] = None,
) -> None:
self._client = client
self._mailbox = mailbox
self._q = _to_expr(query) if query is not None else Q.all()
self._cached_uids: Optional[list[str]] = None
def _uids(self) -> list[str]:
if self._cached_uids is not None:
return self._cached_uids
from email_profile.clients.imap.mailbox import _quote
Status.state(self._client.select(_quote(self._mailbox.name)))
data = Status.state(self._client.uid("search", None, self._q.mount()))
search = SearchParser(data)
self._cached_uids = search.uids()
if len(self._cached_uids) > 50_000:
logger.warning(
"Cached %d UIDs for mailbox %s. Consider using pagination.",
len(self._cached_uids),
self._mailbox.name,
)
return self._cached_uids
def clear_cache(self) -> Where:
"""Drop cached UIDs so the next call hits IMAP again."""
self._cached_uids = None
return self
def count(self) -> int:
"""How many messages match — no body fetched."""
return len(self._uids())
def exists(self) -> bool:
"""True if at least one message matches."""
return self.count() > 0
def uids(self) -> list[str]:
return list(self._uids())
def first(self) -> Optional[Message]:
for msg in self.messages(chunk_size=1):
return msg
return None
def last(self) -> Optional[Message]:
uids = self._uids()
if not uids:
return None
original = self._cached_uids
self._cached_uids = [uids[-1]]
try:
for msg in self.messages(chunk_size=1):
return msg
return None
finally:
self._cached_uids = original
def list(self) -> list[Message]:
return list(self.messages())
def __len__(self) -> int:
return self.count()
def __bool__(self) -> bool:
return self.exists()
def __getitem__(self, index: int | slice) -> Message | list[Message]:
uids = self._uids()
selected = uids[index]
if isinstance(selected, str):
selected = [selected]
original = self._cached_uids
self._cached_uids = selected
try:
result = list(self.messages())
if isinstance(index, int):
return result[0] if result else None
return result
finally:
self._cached_uids = original
def __iter__(self) -> Iterator[Message]:
return self.messages()
def messages(
self,
*,
mode: FetchMode = "full",
chunk_size: Optional[int] = None,
on_progress: Optional[Callable[[int, int], None]] = None,
) -> Iterator[Message]:
"""Stream matching messages, fetched in chunks. Wrap in ``list()``
if you need a materialized list.
``mode``:
- ``"full"`` — RFC822 with attachments (default).
- ``"text"`` — headers + body, no attachments (~50x lighter).
- ``"headers"`` — headers only (cheapest).
``chunk_size`` overrides ``CHUNK_SIZE`` for this call. Larger values
ride faster servers; smaller ones survive flaky links.
``on_progress`` is called with ``(done, total)`` after each chunk.
"""
spec = _FETCH_SPECS.get(mode)
if spec is None:
raise ValueError(
f"Unknown fetch mode {mode!r}. Use one of: {sorted(_FETCH_SPECS)}"
)
size = chunk_size or self.CHUNK_SIZE
uids = self._uids()
total = len(uids)
fetcher = Fetch(
client=self._client,
mailbox=self._mailbox,
spec=spec,
chunk_size=size,
)
done = 0
exhausted = False
try:
for fetched in fetcher.chunks(uids):
done = min(done + size, total)
logger.info(
"Fetched %d/%d messages from %s (mode=%s)",
done,
total,
self._mailbox.name,
mode,
)
if on_progress is not None:
on_progress(done, total)
for entry in fetched:
if not isinstance(entry, tuple):
continue
raw_uid, raw_message = entry
try:
uid = FetchParser((raw_uid, b""))._parse_uid()
yield Message.from_raw(
uid=uid or "0",
mailbox=self._mailbox.name,
raw=raw_message,
)
except Exception:
uid_text = (
raw_uid.decode(errors="replace")
if raw_uid
else "?"
)
logger.exception(
"Failed to parse message uid=%s mailbox=%s",
uid_text,
self._mailbox.name,
)
continue
exhausted = True
finally:
if exhausted:
self.clear_cache()
def __repr__(self) -> str:
return (
f"Where(mailbox={self._mailbox.name!r}, query={self._q.mount()!r})"
)
|