telegram-migration 0.1.0__py3-none-any.whl

telegram_migration/__init__.py

@@ -0,0 +1,30 @@
+"""Rebuild a Telegram Desktop chat export in a channel, resumably, with a Telegram bot.
+
+Quick start::
+
+    from telegram_migration import Settings, run
+
+    settings = Settings.from_env()          # reads TELEGRAM_* variables / .env / Colab Secrets
+    run(settings)                           # dry run unless settings.dry_run is False
+
+or from a shell: ``python -m telegram_migration --help``.
+
+Importing this package does not read environment variables or perform file I/O.
+Configuration and filesystem access happen when you call :func:`run` / :func:`run_async`.
+"""
+from ._version import __version__
+from .config import ConfigError, Settings
+
+__all__ = ["ConfigError", "Settings", "__version__", "run", "run_async"]
+
+
+def run(settings=None, **overrides):
+    """Run (or resume) a migration. See :func:`telegram_migration.runner.run`."""
+    from .runner import run as _run
+    return _run(settings, **overrides)
+
+
+async def run_async(settings=None, **overrides):
+    """Coroutine version of :func:`run`. See :func:`telegram_migration.pipeline.run_async`."""
+    from .pipeline import run_async as _run_async
+    return await _run_async(settings, **overrides)

telegram_migration/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

telegram_migration/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

telegram_migration/bigfiles.py

@@ -0,0 +1,174 @@
+"""Oversize-file handling: size check, manual-upload ledger, stop instructions."""
+
+import os
+import re
+from datetime import datetime
+
+from . import config, progress
+
+
+def max_upload_bytes():
+    """The size limit in bytes, or 0 when the check is disabled."""
+    return int(config.settings.max_upload_mb * 1024 * 1024) if config.settings.max_upload_mb else 0
+
+
+def format_mb(n_bytes):
+    return f"{n_bytes / (1024 * 1024):.1f} MB"
+
+
+def find_oversize_media(media):
+    """[(path, kind, size_bytes)] for every file bigger than the limit (strictly greater)."""
+    limit = max_upload_bytes()
+    if not limit:
+        return []
+    out = []
+    for path, kind in media:
+        try:
+            size = os.path.getsize(path)
+        except OSError:
+            continue                      # unreadable here: the upload itself will report it
+        if size > limit:
+            out.append((path, kind, size))
+    return out
+
+
+def load_manual_uploads():
+    """Source message ids you handled by hand, from the manual-uploads file (settings.manual_uploads_file).
+
+    One id per line, optionally followed by the id of the message you posted in
+    the channel (so later replies can link to it):
+        1234
+        1234 5678        # the second number is the destination message id
+    Blank lines and anything after '#' are ignored.
+    Returns (set_of_source_ids, {source_id: destination_id}).
+    """
+    done, mapped = set(), {}
+    if not os.path.exists(config.settings.manual_uploads_file):
+        return done, mapped
+    with open(config.settings.manual_uploads_file, encoding="utf-8") as f:
+        for raw in f:
+            line = raw.split("#", 1)[0].strip()
+            if not line:
+                continue
+            parts = line.replace(",", " ").split()
+            src = re.sub(r"^message", "", parts[0], flags=re.IGNORECASE)
+            if not src.isdigit():
+                print(f"Warning: ignoring unreadable line in {os.path.basename(config.settings.manual_uploads_file)}: {raw.strip()!r}")
+                continue
+            done.add(src)
+            if len(parts) > 1 and parts[1].isdigit():
+                mapped[src] = int(parts[1])
+    return done, mapped
+
+
+def mark_manual_upload(source_id, rel_files):
+    """Append `source_id` to the manual-uploads file (once). True if it is recorded afterwards.
+
+    The line is "<id>    # comment"; load_manual_uploads() ignores the comment, and you can
+    write the channel message id of your upload after the number to link replies to it.
+    """
+    try:
+        done, _mapped = load_manual_uploads()
+        if str(source_id) in done:
+            return True
+        existing = ""
+        if os.path.exists(config.settings.manual_uploads_file):
+            with open(config.settings.manual_uploads_file, encoding="utf-8") as f:
+                existing = f.read()
+        lead = "" if (not existing or existing.endswith("\n")) else "\n"
+        header = "" if existing else (
+            "# Source message ids you uploaded by hand (the script skips them).\n"
+            "# Format:  <id>   or   <id> <channel message id of your upload>   # comment\n")
+        stamp = datetime.now().strftime("%Y-%m-%d %H:%M")
+        files = ", ".join(rel_files)
+        with open(config.settings.manual_uploads_file, "a", encoding="utf-8") as f:
+            f.write(f"{lead}{header}{source_id}    # auto-added {stamp} after an oversize stop: upload {files} by hand\n")
+            f.flush()
+        return True
+    except Exception as exc:
+        print(f"Warning: could not write {config.settings.manual_uploads_file}: {type(exc).__name__}: {exc}")
+        return False
+
+
+def format_oversize_instructions(source_id, data, caption, oversize, last_dest_id, migrated, auto_marked=False):
+    big = {os.path.abspath(p) for p, _k, _s in oversize}
+    ts = data.get("timestamp")
+    when = ts.strftime("%Y-%m-%d %H:%M") if ts else "unknown time"
+    who = data.get("sender") or "unknown sender"
+    lines = [
+        "",
+        "═" * 72,
+        f"STOPPED: message id={source_id} has a file over the {format_mb(max_upload_bytes())} upload limit.",
+        "═" * 72,
+        "None of this message's files were uploaded by the script. It is logged in:",
+        f"    {config.settings.failed_file}",
+        "",
+        f"Upload these file(s) to the channel by hand (original message: {when}, {who}):",
+    ]
+    for path, kind in data["media"]:
+        ap = os.path.abspath(path)
+        try:
+            size = format_mb(os.path.getsize(path))
+        except OSError:
+            size = "size unknown"
+        lines.append(f"    [{kind}] {ap}  ({size}){'   <-- TOO LARGE' if ap in big else ''}")
+    if caption and caption.strip():
+        shown = caption if len(caption) <= 1500 else caption[:1500] + "…"
+        lines += ["", "Caption to paste with it:"] + ["    | " + ln for ln in shown.splitlines()]
+    where = (f"after the {migrated} message(s) already migrated"
+             + (f" (the last one is message #{last_dest_id} in the channel)" if last_dest_id else ""))
+    if auto_marked:
+        lines += [
+            "",
+            "To resume:",
+            f"  1. Upload the file(s) now, BEFORE running the script again, so they land {where}",
+            "     and ahead of the messages that follow.",
+            f"  2. Nothing to edit: message {source_id} is already recorded in",
+            f"         {config.settings.manual_uploads_file}",
+            "     so the next run skips it and continues with the following message.",
+            f"     (Optional: write the channel message id of your upload after the number, e.g.",
+            f"      \"{source_id} 5678\", so replies to this message link to it. To undo, delete the line.)",
+            "  3. Run the script again.",
+            "",
+            "WARNING: if you run the script again BEFORE uploading, this message will be skipped.",
+        ]
+    else:
+        lines += [
+            "",
+            "To resume:",
+            f"  1. Upload the file(s) now, BEFORE running the script again, so they land {where}",
+            "     and ahead of the messages that follow.",
+            f"  2. Add this line to {config.settings.manual_uploads_file}:",
+            f"         {source_id}",
+            "     (optionally add the channel message id of your upload after it, e.g.",
+            f"      \"{source_id} 5678\", so replies to this message link to it).",
+            "  3. Run the script again. It continues with the next message.",
+        ]
+    lines += [
+        "",
+        f"All progress is saved ({migrated} message(s) migrated so far).",
+        "═" * 72,
+    ]
+    return "\n".join(lines)
+
+
+def halt_for_oversize(source_id, data, caption, oversize, id_map, ctx):
+    """Log the message id, print the manual-upload instructions and request a clean stop."""
+    reason = "FILE_TOO_LARGE: " + "; ".join(
+        f"{os.path.relpath(p, config.settings.base_dir)} ({format_mb(sz)} > {format_mb(max_upload_bytes())} limit)"
+        for p, _k, sz in oversize
+    )
+    progress.log_failure(source_id, reason)
+    last_dest = ctx.get("last_dest_id") or (max(id_map.values()) if id_map else None)
+    auto = False
+    if config.settings.auto_mark_manual_on_stop:
+        auto = mark_manual_upload(source_id, [os.path.relpath(p, config.settings.base_dir) for p, _k in data["media"]])
+    print(format_oversize_instructions(source_id, data, caption, oversize, last_dest, len(id_map), auto_marked=auto))
+    ctx["halt"].append(source_id)
+    ctx["stop"] = True
+
+
+def print_oversize_dry_run(source_id, data, oversize):
+    for path, kind, size in oversize:
+        print(f"  [dry] ⚠ id={source_id:<6} OVERSIZE [{kind}] {os.path.abspath(path)} ({format_mb(size)})"
+              f" - a real run stops here")

telegram_migration/cli.py

@@ -0,0 +1,90 @@
+"""Command line: ``python -m telegram_migration`` or the ``telegram-migration`` command."""
+import argparse
+import sys
+
+from ._version import __version__
+
+
+def confirm_target(channel, pending, n_files, settings):
+    print()
+    print("═" * 60)
+    print(f"  Target:  {getattr(channel, 'title', '?')!r}")
+    print(f"  ID:      {getattr(channel, 'id', '?')}")
+    uname = getattr(channel, "username", None)
+    if uname:
+        print(f"  Handle:  @{uname}")
+    print(f"  Files:   {n_files} export file(s)")
+    print(f"  Pending: ~{pending} messages")
+    print("═" * 60)
+    if settings.dry_run:
+        print("DRY RUN — nothing will actually be sent.\n")
+        return True
+    if settings.skip_confirmation:
+        print("SKIP_CONFIRMATION is on — proceeding.\n")
+        return True
+    return input("Send to this channel? [y/N]: ").strip().lower() in ("y", "yes")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="telegram-migration",
+        description="Rebuild a Telegram Desktop chat export in a channel with a Telegram bot. "
+                    "Settings come from the TELEGRAM_* environment variables / .env file; "
+                    "the options below override them. Dry run is ON unless you pass --send.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--env-file", metavar="PATH", help="path of a .env file to load (default: ./.env if present)")
+    parser.add_argument("--export-dir", metavar="PATH", help="folder with messages.html and the media folders")
+    parser.add_argument("--channel", metavar="PEER", help="destination: numeric peer id (-100...) or @username")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--dry-run", dest="dry_run", action="store_true", default=None,
+                      help="preview only; nothing is sent")
+    mode.add_argument("--send", dest="dry_run", action="store_false",
+                      help="really send the messages (turns the dry run off)")
+    parser.add_argument("--yes", dest="skip_confirmation", action="store_true", default=None,
+                        help="do not ask for confirmation before sending")
+    parser.add_argument("--max-upload-mb", type=float, metavar="N",
+                        help="stop at any message with a file larger than this (0 disables)")
+    parser.add_argument("--batch-limit", type=int, metavar="N", help="stop after this many messages")
+    parser.add_argument("--delay", type=float, dest="send_delay_seconds", metavar="SECONDS",
+                        help="seconds to wait between messages")
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+
+    overrides = {}
+    if args.export_dir is not None:
+        overrides["base_dir"] = args.export_dir
+    if args.channel is not None:
+        try:
+            overrides["channel_peer"] = int(args.channel)
+        except ValueError:
+            overrides["channel_peer"] = args.channel
+    for name in ("dry_run", "skip_confirmation", "batch_limit", "send_delay_seconds"):
+        if getattr(args, name) is not None:
+            overrides[name] = getattr(args, name)
+    if args.max_upload_mb is not None:
+        overrides["max_upload_mb"] = args.max_upload_mb or None
+
+    from .config import ConfigError, Settings
+    try:
+        settings = Settings.from_env(env_file=args.env_file, **overrides).validate()
+    except ConfigError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        return 2
+
+    from .runner import run
+    try:
+        result = run(settings)
+    except KeyboardInterrupt:
+        print("\nInterrupted. Progress made so far is saved; run again to resume.", file=sys.stderr)
+        return 130
+    # run() returns True on success, user abort, or a clean oversize stop, and False only
+    # when the migration could not start (no export, or the channel did not resolve).
+    return 0 if result is not False else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

telegram_migration/config.py

@@ -0,0 +1,296 @@
+"""Settings for a migration run.
+
+Build a :class:`Settings` yourself, or call :meth:`Settings.from_env` to read the
+``TELEGRAM_*`` environment variables (a local ``.env`` file and Google Colab Secrets are
+supported). The package modules read the *active* settings through ``config.settings``
+at call time; :func:`use_settings` scopes them to the current thread/async context.
+
+Nothing is read from the environment at import time.
+"""
+from __future__ import annotations
+
+import dataclasses
+import os
+from contextvars import ContextVar
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Mapping, Optional, Tuple, Union
+
+from .constants import BOT_CAPTION_LIMIT, MAX_CAPTION_LIMIT, MIN_TEXT_LIMIT, TEXT_LIMIT
+
+PLACEHOLDER_API_ID = 12345678          # the value shipped in .env.example
+_TRUE = {"1", "true", "yes", "y", "on"}
+
+# Progress files kept inside the export folder: attribute name -> file name.
+_DERIVED_FILES = {
+    "idmap_file": "migration_id_map.jsonl",
+    "failed_file": "failed_messages.txt",
+    "partial_file": "migration_partial_sends.jsonl",
+    "pending_replies_file": "migration_pending_replies.json",
+    "reaction_note_map_file": "migration_reaction_notes.jsonl",
+    "reaction_archive_file": "migration_reactions_archive.jsonl",
+    "reaction_source_file": "migration_reactions_source.jsonl",
+    "reply_audit_file": "migration_reply_audit.jsonl",
+    "format_debug_file": "migration_formatting_dropped.jsonl",
+    "manual_uploads_file": "migration_manual_uploads.txt",
+}
+
+
+class ConfigError(ValueError):
+    """The settings are incomplete or still contain example values."""
+
+
+def _truthy(value: Optional[str], default: bool) -> bool:
+    if value is None or not str(value).strip():
+        return default
+    return str(value).strip().casefold() in _TRUE
+
+
+def load_secret(name: str, env: Optional[Mapping[str, str]] = None) -> str:
+    """Read a value from the environment, then (in Google Colab) from Colab Secrets."""
+    source = os.environ if env is None else env
+    value = (source.get(name, "") or "").strip()
+    if value or env is not None:
+        return value
+    try:
+        from google.colab import userdata  # type: ignore
+        return (userdata.get(name) or "").strip()
+    except Exception:
+        return ""
+
+
+def _load_dotenv(env_file: Optional[str]) -> None:
+    try:
+        from dotenv import load_dotenv
+    except ImportError:
+        print("Warning: python-dotenv is not installed; .env files will be ignored.")
+        return
+    load_dotenv(env_file) if env_file else load_dotenv()
+
+
+@dataclass
+class Settings:
+    """Everything that can be configured. Defaults are the safe ones (dry run on)."""
+
+    # --- Telegram credentials -------------------------------------------------------------
+    api_id: Optional[int] = None
+    api_hash: str = field(default="", repr=False)
+    bot_token: str = field(default="", repr=False)
+    channel_peer: Union[int, str, None] = None     # numeric peer id (-100...) or "@username"
+    session_name: str = "colab_bot_restorer_session"
+
+    # --- where things live ----------------------------------------------------------------
+    base_dir: str = "./telegram_export"            # folder with messages.html, media folders, ...
+    # Progress files; when left as None they are placed inside base_dir.
+    idmap_file: Optional[str] = None
+    failed_file: Optional[str] = None
+    partial_file: Optional[str] = None
+    pending_replies_file: Optional[str] = None
+    reaction_note_map_file: Optional[str] = None
+    reaction_archive_file: Optional[str] = None
+    reaction_source_file: Optional[str] = None
+    reply_audit_file: Optional[str] = None
+    format_debug_file: Optional[str] = None
+    manual_uploads_file: Optional[str] = None
+
+    # --- behaviour --------------------------------------------------------------------------
+    dry_run: bool = True                           # preview only; nothing is sent
+    skip_confirmation: bool = False                # do not ask before sending
+    # Largest file the run will try to upload; a message with a bigger file stops the run
+    # (nothing from it is sent) so it can be uploaded by hand. None or 0 disables the check.
+    # 2000 MiB is believed to be Telegram's MTProto ceiling; verify it with your bot.
+    max_upload_mb: Optional[float] = 2000
+    # On an oversize stop, record that message in manual_uploads_file so the next run skips it.
+    # UPLOAD THE FILE(S) BEFORE RERUNNING, or that message is left out of the channel.
+    auto_mark_manual_on_stop: bool = True
+    batch_limit: int = 1000                        # stop after this many messages (sent + failed)
+    max_retries: int = 5
+    max_flood_waits: int = 10
+    send_delay_seconds: float = 2.5
+    preserve_sender_names: bool = True
+    preserve_reactions_as_annotations: bool = True
+    json_reaction_file_candidates: Tuple[str, ...] = ("result.json", "messages.json")
+    max_json_fallback_mb: int = 512
+    verify_replies: bool = True
+    # Telegram's message limit is 4096 for every account; lower it only to split long text into
+    # shorter parts. Settings.validate() rejects values above Telegram's maximum and below
+    # MIN_TEXT_LIMIT, where the splitter's surrogate-pair handling could produce a chunk
+    # slightly larger than the requested limit.
+    text_limit: int = TEXT_LIMIT
+    # Caption limit for media. A bot account is not Premium, so this is BOT_CAPTION_LIMIT
+    # (1024) rather than MAX_CAPTION_LIMIT (2048, Premium user accounts only).
+    caption_limit: int = BOT_CAPTION_LIMIT
+    # Try a native forward first when the export links the original message; a native
+    # forward cannot carry our timestamp/sender line, so forward_annotate sends it as a reply.
+    native_forward: bool = True
+    forward_annotate: bool = True
+
+    def __post_init__(self) -> None:
+        self.base_dir = os.path.abspath(os.path.expanduser(str(self.base_dir)))
+        for attr, filename in _DERIVED_FILES.items():
+            if getattr(self, attr) is None:
+                setattr(self, attr, os.path.join(self.base_dir, filename))
+
+    # ------------------------------------------------------------------------------------
+    def replace(self, **changes) -> "Settings":
+        """Copy with some fields changed. Changing base_dir moves the progress files too."""
+        if "base_dir" in changes:
+            for attr in _DERIVED_FILES:
+                changes.setdefault(attr, None)
+        return dataclasses.replace(self, **changes)
+
+    def problems(self) -> list:
+        """Human-readable list of what is missing or still an example value."""
+        found = []
+        if self.api_id is None:
+            found.append("TELEGRAM_API_ID is not set")
+        elif self.api_id == PLACEHOLDER_API_ID:
+            found.append("TELEGRAM_API_ID is still the example value; use your own from my.telegram.org")
+        for env_name, value in (("TELEGRAM_API_HASH", self.api_hash), ("TELEGRAM_BOT_TOKEN", self.bot_token)):
+            if not value:
+                found.append(f"{env_name} is not set")
+            elif value.startswith("replace_with"):
+                found.append(f"{env_name} is still the example value")
+        if self.channel_peer in (None, ""):
+            found.append("TELEGRAM_CHANNEL_PEER is not set (numeric peer id or @username)")
+        if not MIN_TEXT_LIMIT <= self.text_limit <= TEXT_LIMIT:
+            found.append(
+                f"text_limit must be between {MIN_TEXT_LIMIT} and {TEXT_LIMIT} "
+                f"(Telegram's maximum; the lower bound avoids a splitter edge case)"
+            )
+        if not MIN_TEXT_LIMIT <= self.caption_limit <= BOT_CAPTION_LIMIT:
+            found.append(
+                f"caption_limit must be between {MIN_TEXT_LIMIT} and {BOT_CAPTION_LIMIT} "
+                f"(the limit for bot accounts; Premium user accounts can reach {MAX_CAPTION_LIMIT}; "
+                f"the lower bound avoids a splitter edge case)"
+            )
+        return found
+
+    def validate(self) -> "Settings":
+        """Raise ConfigError if credentials or the destination are missing."""
+        found = self.problems()
+        if found:
+            raise ConfigError(
+                "; ".join(found) + ". Set them in .env/the environment or as Colab Secrets. "
+                "Never commit credentials to Git."
+            )
+        return self
+
+    @classmethod
+    def from_env(cls, env: Optional[Mapping[str, str]] = None, *, env_file: Optional[str] = None,
+                 use_dotenv: bool = True, **overrides) -> "Settings":
+        """Read the TELEGRAM_* variables. Explicit keyword arguments win over the environment.
+
+        With env=None the process environment is used, a local .env file is loaded first
+        (it never overrides variables that are already set) and Colab Secrets are consulted.
+        Pass a mapping as ``env`` to read from it only (useful in tests).
+        """
+        if env is None and use_dotenv:
+            _load_dotenv(env_file)
+        get = lambda name: load_secret(name, env)          # noqa: E731
+
+        values: dict = {}
+        raw_id = get("TELEGRAM_API_ID")
+        if raw_id:
+            try:
+                values["api_id"] = int(raw_id)
+            except ValueError:
+                raise ConfigError(f"TELEGRAM_API_ID must be a number, got {raw_id!r}") from None
+        values["api_hash"] = get("TELEGRAM_API_HASH")
+        values["bot_token"] = get("TELEGRAM_BOT_TOKEN")
+        raw_peer = get("TELEGRAM_CHANNEL_PEER")
+        if raw_peer:
+            try:
+                values["channel_peer"] = int(raw_peer)
+            except ValueError:
+                values["channel_peer"] = raw_peer
+        source = os.environ if env is None else env
+        if source.get("TELEGRAM_EXPORT_DIR"):
+            values["base_dir"] = source["TELEGRAM_EXPORT_DIR"]
+        if source.get("TELEGRAM_SESSION_NAME"):
+            values["session_name"] = source["TELEGRAM_SESSION_NAME"]
+        values["dry_run"] = _truthy(source.get("TELEGRAM_DRY_RUN"), True)
+        values["skip_confirmation"] = _truthy(source.get("TELEGRAM_SKIP_CONFIRMATION"), False)
+
+        raw = (source.get("TELEGRAM_MAX_UPLOAD_MB") or "").strip().casefold()
+        if raw:
+            values["max_upload_mb"] = None if raw in {"0", "none", "off", "false"} else _number(raw, "TELEGRAM_MAX_UPLOAD_MB", float)
+        raw = (source.get("TELEGRAM_BATCH_LIMIT") or "").strip()
+        if raw:
+            values["batch_limit"] = _number(raw, "TELEGRAM_BATCH_LIMIT", int)
+        raw = (source.get("TELEGRAM_SEND_DELAY") or "").strip()
+        if raw:
+            values["send_delay_seconds"] = _number(raw, "TELEGRAM_SEND_DELAY", float)
+
+        values.update(overrides)
+        return cls(**values)
+
+
+def _number(raw: str, name: str, kind):
+    try:
+        return kind(raw)
+    except ValueError:
+        raise ConfigError(f"{name} must be a number, got {raw!r}") from None
+
+
+# Defaults only: nothing is read from the environment until Settings.from_env() (or run()).
+_default_settings = Settings()
+_active_settings = ContextVar("telegram_migration_settings", default=None)
+
+
+class _SettingsProxy:
+    """Resolve settings in the current async context, falling back to defaults."""
+
+    def __getattr__(self, name):
+        return getattr(get_settings(), name)
+
+    # Read-only on purpose. Writing through the proxy would change whichever Settings happens to be
+    # active (and unittest.mock.patch.object, which restores a value by *deleting* it, would then
+    # leave a field reset to its class default instead of its original value).
+    def __setattr__(self, name, value):
+        raise AttributeError(
+            "config.settings is read-only; build a Settings and activate it with "
+            "config.use_settings(...) or config.set_settings(...)"
+        )
+
+    def __delattr__(self, name):
+        raise AttributeError(
+            "config.settings is read-only; build a Settings and activate it with "
+            "config.use_settings(...) or config.set_settings(...)"
+        )
+
+    def __repr__(self):
+        return repr(get_settings())
+
+
+settings = _SettingsProxy()
+
+
+def get_settings() -> Settings:
+    """Return the settings active in the current thread/async context."""
+    active = _active_settings.get()
+    return active if active is not None else _default_settings
+
+
+def set_settings(new: Settings) -> Settings:
+    """Set fallback settings for callers overriding the default outside `use_settings`."""
+    global _default_settings
+    _default_settings = new
+    return new
+
+
+@contextmanager
+def use_settings(new: Settings):
+    """Temporarily activate `new` in this thread/async context only."""
+    token = _active_settings.set(new)
+    try:
+        yield new
+    finally:
+        _active_settings.reset(token)
+
+
+def resolve_settings(settings_arg: Optional[Settings] = None, **overrides) -> Settings:
+    """`settings_arg` (or Settings.from_env()) with keyword overrides applied."""
+    if settings_arg is None:
+        return Settings.from_env(**overrides)
+    return settings_arg.replace(**overrides) if overrides else settings_arg

telegram_migration/constants.py

@@ -0,0 +1,25 @@
+"""Fixed values that are part of how Telegram and the export work (not user settings)."""
+
+# Telegram's hard limit for the text of one message (every account, Premium included).
+TEXT_LIMIT = 4096
+
+# The largest caption any account can send (Premium user accounts); bots are limited to 1024.
+MAX_CAPTION_LIMIT = 2048
+
+# The caption limit this tool can actually use: the script authenticates with a bot token,
+# and bot accounts cannot be Premium, so 1024 is the effective ceiling.
+BOT_CAPTION_LIMIT = 1024
+
+# The smallest text_limit or caption_limit that makes sense. Below 4, the splitter's
+# surrogate-pair avoidance can produce a chunk that exceeds the requested limit by one
+# UTF-16 unit; Settings.validate() rejects such values so the splitter never faces that
+# choice through the public API.
+MIN_TEXT_LIMIT = 4
+
+# messages.html, messages2.html, ... in a Telegram Desktop HTML export.
+HTML_FILE_PATTERN = r"^messages(\d*)\.html$"
+
+# Sticker files need sticker-specific upload attributes and cannot be captioned like
+# ordinary photos/videos, so their text is sent as a separate message first.
+STICKER_KINDS = ("sticker_static", "sticker_animated", "sticker_video", "sticker_unknown")
+NO_CAPTION_KINDS = ("voice", "round_video", *STICKER_KINDS)