Skip to content

Sync

email_profile.clients.imap.sync.Sync

Sync server state into local storage (server -> storage).

Source code in email_profile/clients/imap/sync.py
 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
class Sync:
    """Sync server state into local storage (server -> storage)."""

    def __init__(self, session: ImapClient) -> None:
        self._session = session

    def orchestrate(
        self,
        storage: StorageABC,
        mailbox: Optional[str] = None,
        mailbox_names: Optional[list[str]] = None,
        max_workers: int = 3,
        skip_duplicates: bool = True,
    ) -> SyncResult:
        """Sync one or all mailboxes with progress and parallel fetch."""

        names = (
            [mailbox]
            if mailbox
            else mailbox_names or list(self._session.mailboxes)
        )
        combined = SyncResult(mailbox=mailbox or "*")
        lock = Lock()
        progress = Progress()

        def sync_one(name: str, retries: int = 3) -> SyncResult:
            task = None

            for attempt in range(retries):
                session = ImapClient(
                    server=self._session.server,
                    user=self._session.user,
                    password=self._session.password,
                    port=self._session.port,
                    ssl=self._session.ssl,
                )

                try:
                    session.connect()
                except Exception as exc:
                    if attempt < retries - 1:
                        time.sleep(2**attempt)
                        continue
                    with lock:
                        progress.console.print(
                            f"  [red]✗[/] {name} — connection failed: {exc}"
                        )
                    return SyncResult(mailbox=name)

                try:
                    box = session.mailboxes[name]
                    server_count = box.where().count()

                    with lock:
                        task = progress.add_task(
                            f"  [cyan]{name}",
                            total=max(server_count, 1),
                            completed=1 if server_count == 0 else 0,
                        )

                    def on_progress(done: int, total: int, _task=task) -> None:
                        with lock:
                            progress.update(_task, completed=done, total=total)

                    result = self.sync(
                        box,
                        storage,
                        on_progress=on_progress,
                        skip_duplicates=skip_duplicates,
                    )

                    with lock:
                        progress.update(task, visible=False)
                        msg = (
                            f"  [green]✓[/] {name} — "
                            f"{result.inserted} new, "
                            f"{result.updated} updated, "
                            f"{result.skipped} skipped"
                        )
                        if result.has_errors:
                            msg += f", [red]{len(result.errors)} errors[/]"
                        progress.console.print(msg)

                    return result
                except Exception as exc:
                    if attempt < retries - 1:
                        time.sleep(2**attempt)
                        continue
                    if task is not None:
                        with lock:
                            progress.update(task, visible=False)
                    with lock:
                        progress.console.print(
                            f"  [red]✗[/] {name} — sync failed: {exc}"
                        )
                    return SyncResult(mailbox=name)
                finally:
                    session.close()

            return SyncResult(mailbox=name)

        with (
            progress,
            ThreadPoolExecutor(
                max_workers=min(max_workers, len(names))
            ) as pool,
        ):
            futures = {pool.submit(sync_one, name): name for name in names}
            for future in as_completed(futures):
                combined = combined.merge(future.result())

        return combined

    def sync(
        self,
        mailbox: MailBox,
        storage: StorageABC,
        on_progress: Optional[Callable[[int, int], None]] = None,
        skip_duplicates: bool = True,
    ) -> SyncResult:
        """Sync one mailbox from IMAP into local storage."""

        result = SyncResult(mailbox=mailbox.name)
        server_uids = mailbox.where().uids()
        total = len(server_uids)

        client = mailbox._client
        if client is None:
            return result

        if skip_duplicates:
            existing_ids = storage.ids(mailbox.name)
            server_msg_ids = Fetch.fetch_message_ids(client, server_uids)
            new_uids = [
                uid
                for uid, mid in server_msg_ids.items()
                if mid not in existing_ids
            ]
        else:
            new_uids = server_uids

        result.skipped = total - len(new_uids)

        if on_progress is not None:
            on_progress(result.skipped, total)

        if not new_uids:
            return result

        done = result.skipped

        fetch = Fetch(
            client=client,
            mailbox=mailbox,
            spec=F.rfc822() + F.flags(),
            chunk_size=CHUNK_FETCH,
        )

        for entry in fetch.parsed(new_uids):
            done += 1

            raw = RawSerializer(
                message_id=entry.message_id,
                uid=entry.uid,
                mailbox=mailbox.name,
                flags=entry.flags,
                file=entry.text(),
            )

            try:
                if storage.save(raw):
                    result.inserted += 1
                else:
                    result.updated += 1
            except Exception as exc:
                logger.error("Failed to save %s: %s", raw.message_id, exc)
                result.errors.append(f"{raw.message_id}: {exc}")

            if on_progress is not None:
                on_progress(done, total)

        return result

__init__(session)

Source code in email_profile/clients/imap/sync.py
32
33
def __init__(self, session: ImapClient) -> None:
    self._session = session

orchestrate(storage, mailbox=None, mailbox_names=None, max_workers=3, skip_duplicates=True)

Sync one or all mailboxes with progress and parallel fetch.

Source code in email_profile/clients/imap/sync.py
 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
def orchestrate(
    self,
    storage: StorageABC,
    mailbox: Optional[str] = None,
    mailbox_names: Optional[list[str]] = None,
    max_workers: int = 3,
    skip_duplicates: bool = True,
) -> SyncResult:
    """Sync one or all mailboxes with progress and parallel fetch."""

    names = (
        [mailbox]
        if mailbox
        else mailbox_names or list(self._session.mailboxes)
    )
    combined = SyncResult(mailbox=mailbox or "*")
    lock = Lock()
    progress = Progress()

    def sync_one(name: str, retries: int = 3) -> SyncResult:
        task = None

        for attempt in range(retries):
            session = ImapClient(
                server=self._session.server,
                user=self._session.user,
                password=self._session.password,
                port=self._session.port,
                ssl=self._session.ssl,
            )

            try:
                session.connect()
            except Exception as exc:
                if attempt < retries - 1:
                    time.sleep(2**attempt)
                    continue
                with lock:
                    progress.console.print(
                        f"  [red]✗[/] {name} — connection failed: {exc}"
                    )
                return SyncResult(mailbox=name)

            try:
                box = session.mailboxes[name]
                server_count = box.where().count()

                with lock:
                    task = progress.add_task(
                        f"  [cyan]{name}",
                        total=max(server_count, 1),
                        completed=1 if server_count == 0 else 0,
                    )

                def on_progress(done: int, total: int, _task=task) -> None:
                    with lock:
                        progress.update(_task, completed=done, total=total)

                result = self.sync(
                    box,
                    storage,
                    on_progress=on_progress,
                    skip_duplicates=skip_duplicates,
                )

                with lock:
                    progress.update(task, visible=False)
                    msg = (
                        f"  [green]✓[/] {name} — "
                        f"{result.inserted} new, "
                        f"{result.updated} updated, "
                        f"{result.skipped} skipped"
                    )
                    if result.has_errors:
                        msg += f", [red]{len(result.errors)} errors[/]"
                    progress.console.print(msg)

                return result
            except Exception as exc:
                if attempt < retries - 1:
                    time.sleep(2**attempt)
                    continue
                if task is not None:
                    with lock:
                        progress.update(task, visible=False)
                with lock:
                    progress.console.print(
                        f"  [red]✗[/] {name} — sync failed: {exc}"
                    )
                return SyncResult(mailbox=name)
            finally:
                session.close()

        return SyncResult(mailbox=name)

    with (
        progress,
        ThreadPoolExecutor(
            max_workers=min(max_workers, len(names))
        ) as pool,
    ):
        futures = {pool.submit(sync_one, name): name for name in names}
        for future in as_completed(futures):
            combined = combined.merge(future.result())

    return combined

sync(mailbox, storage, on_progress=None, skip_duplicates=True)

Sync one mailbox from IMAP into local storage.

Source code in email_profile/clients/imap/sync.py
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
def sync(
    self,
    mailbox: MailBox,
    storage: StorageABC,
    on_progress: Optional[Callable[[int, int], None]] = None,
    skip_duplicates: bool = True,
) -> SyncResult:
    """Sync one mailbox from IMAP into local storage."""

    result = SyncResult(mailbox=mailbox.name)
    server_uids = mailbox.where().uids()
    total = len(server_uids)

    client = mailbox._client
    if client is None:
        return result

    if skip_duplicates:
        existing_ids = storage.ids(mailbox.name)
        server_msg_ids = Fetch.fetch_message_ids(client, server_uids)
        new_uids = [
            uid
            for uid, mid in server_msg_ids.items()
            if mid not in existing_ids
        ]
    else:
        new_uids = server_uids

    result.skipped = total - len(new_uids)

    if on_progress is not None:
        on_progress(result.skipped, total)

    if not new_uids:
        return result

    done = result.skipped

    fetch = Fetch(
        client=client,
        mailbox=mailbox,
        spec=F.rfc822() + F.flags(),
        chunk_size=CHUNK_FETCH,
    )

    for entry in fetch.parsed(new_uids):
        done += 1

        raw = RawSerializer(
            message_id=entry.message_id,
            uid=entry.uid,
            mailbox=mailbox.name,
            flags=entry.flags,
            file=entry.text(),
        )

        try:
            if storage.save(raw):
                result.inserted += 1
            else:
                result.updated += 1
        except Exception as exc:
            logger.error("Failed to save %s: %s", raw.message_id, exc)
            result.errors.append(f"{raw.message_id}: {exc}")

        if on_progress is not None:
            on_progress(done, total)

    return result