Skip to content

Restore

email_profile.clients.imap.restore.Restore

Restore from local storage/files back to an IMAP server (storage -> server).

Source code in email_profile/clients/imap/restore.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
class Restore:
    """Restore from local storage/files back to an IMAP server (storage -> server)."""

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

    def orchestrate(
        self,
        storage: StorageABC,
        mailbox: Optional[str] = None,
        skip_duplicates: bool = True,
        max_workers: int = 3,
    ) -> int:
        """Restore all mailboxes with progress and parallel upload."""
        self._session.require()

        ids_by_mailbox: dict[str, list[str]] = {}

        for message_id in storage.ids():
            raw = storage.get(message_id)
            if raw is None or not raw.file:
                continue
            if mailbox and raw.mailbox != mailbox:
                continue
            ids_by_mailbox.setdefault(raw.mailbox, []).append(message_id)
            del raw

        if not ids_by_mailbox:
            return 0

        total_count = 0
        lock = Lock()
        progress = Progress()

        def restore_one(
            box_name: str, message_ids: list[str], retries: int = 3
        ) -> int:
            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]✗[/] {box_name} — connection failed: {exc}"
                        )
                    return 0

                try:
                    _ensure_mailbox(session, box_name)

                    with lock:
                        task = progress.add_task(
                            f"  [cyan]{box_name}", total=len(message_ids)
                        )

                    result = self.restore_mailbox(
                        session,
                        box_name,
                        message_ids,
                        storage=storage,
                        skip_duplicates=skip_duplicates,
                    )

                    with lock:
                        progress.update(task, visible=False)
                        progress.console.print(
                            f"  [green]✓[/] {box_name} — "
                            f"{result['uploaded']} uploaded, "
                            f"{result['skipped']} skipped"
                        )

                    return result["uploaded"]
                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]✗[/] {box_name} — restore failed: {exc}"
                        )
                    return 0
                finally:
                    session.close()

            return 0

        with (
            progress,
            ThreadPoolExecutor(
                max_workers=min(max_workers, len(ids_by_mailbox))
            ) as pool,
        ):
            futures = {
                pool.submit(restore_one, box_name, msg_ids): box_name
                for box_name, msg_ids in ids_by_mailbox.items()
            }
            for future in as_completed(futures):
                total_count += future.result()

        return total_count

    @staticmethod
    def restore_mailbox(
        session: ImapClient,
        box_name: str,
        message_ids: list[str],
        *,
        storage: StorageABC,
        skip_duplicates: bool = True,
    ) -> dict[str, int]:
        """Restore a single mailbox. Returns {'uploaded': N, 'skipped': N}.

        Messages are loaded from *storage* one at a time so that only
        one RFC-822 body is kept in memory per iteration, avoiding OOM
        on large backups.
        """

        server_ids: set[str] = set()
        if skip_duplicates:
            server_ids = _server_message_ids(session.client, box_name)

        uploaded = 0
        skipped = 0

        for mid in message_ids:
            if skip_duplicates and mid in server_ids:
                skipped += 1
                continue

            raw = storage.get(mid)
            if raw is None or not raw.file:
                continue

            server_ids.add(mid)

            date = EmailParser(raw.file).date()
            session.mailboxes[box_name].append(
                raw.file, flags=raw.flags, date=date
            )
            uploaded += 1
            del raw

        return {"uploaded": uploaded, "skipped": skipped}

__init__(session)

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

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

Restore all mailboxes with progress and parallel upload.

Source code in email_profile/clients/imap/restore.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
141
142
143
144
def orchestrate(
    self,
    storage: StorageABC,
    mailbox: Optional[str] = None,
    skip_duplicates: bool = True,
    max_workers: int = 3,
) -> int:
    """Restore all mailboxes with progress and parallel upload."""
    self._session.require()

    ids_by_mailbox: dict[str, list[str]] = {}

    for message_id in storage.ids():
        raw = storage.get(message_id)
        if raw is None or not raw.file:
            continue
        if mailbox and raw.mailbox != mailbox:
            continue
        ids_by_mailbox.setdefault(raw.mailbox, []).append(message_id)
        del raw

    if not ids_by_mailbox:
        return 0

    total_count = 0
    lock = Lock()
    progress = Progress()

    def restore_one(
        box_name: str, message_ids: list[str], retries: int = 3
    ) -> int:
        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]✗[/] {box_name} — connection failed: {exc}"
                    )
                return 0

            try:
                _ensure_mailbox(session, box_name)

                with lock:
                    task = progress.add_task(
                        f"  [cyan]{box_name}", total=len(message_ids)
                    )

                result = self.restore_mailbox(
                    session,
                    box_name,
                    message_ids,
                    storage=storage,
                    skip_duplicates=skip_duplicates,
                )

                with lock:
                    progress.update(task, visible=False)
                    progress.console.print(
                        f"  [green]✓[/] {box_name} — "
                        f"{result['uploaded']} uploaded, "
                        f"{result['skipped']} skipped"
                    )

                return result["uploaded"]
            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]✗[/] {box_name} — restore failed: {exc}"
                    )
                return 0
            finally:
                session.close()

        return 0

    with (
        progress,
        ThreadPoolExecutor(
            max_workers=min(max_workers, len(ids_by_mailbox))
        ) as pool,
    ):
        futures = {
            pool.submit(restore_one, box_name, msg_ids): box_name
            for box_name, msg_ids in ids_by_mailbox.items()
        }
        for future in as_completed(futures):
            total_count += future.result()

    return total_count

restore_mailbox(session, box_name, message_ids, *, storage, skip_duplicates=True) staticmethod

Restore a single mailbox. Returns {'uploaded': N, 'skipped': N}.

Messages are loaded from storage one at a time so that only one RFC-822 body is kept in memory per iteration, avoiding OOM on large backups.

Source code in email_profile/clients/imap/restore.py 
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
@staticmethod
def restore_mailbox(
    session: ImapClient,
    box_name: str,
    message_ids: list[str],
    *,
    storage: StorageABC,
    skip_duplicates: bool = True,
) -> dict[str, int]:
    """Restore a single mailbox. Returns {'uploaded': N, 'skipped': N}.

    Messages are loaded from *storage* one at a time so that only
    one RFC-822 body is kept in memory per iteration, avoiding OOM
    on large backups.
    """

    server_ids: set[str] = set()
    if skip_duplicates:
        server_ids = _server_message_ids(session.client, box_name)

    uploaded = 0
    skipped = 0

    for mid in message_ids:
        if skip_duplicates and mid in server_ids:
            skipped += 1
            continue

        raw = storage.get(mid)
        if raw is None or not raw.file:
            continue

        server_ids.add(mid)

        date = EmailParser(raw.file).date()
        session.mailboxes[box_name].append(
            raw.file, flags=raw.flags, date=date
        )
        uploaded += 1
        del raw

    return {"uploaded": uploaded, "skipped": skipped}