fylepy 0.1.0__py3-none-any.whl

fyle/_core/fetcher.py

@@ -0,0 +1,68 @@
+"""URL fetcher — built on ``httpx`` with timeout and max_bytes safety limits.
+
+Defaults: ``timeout=30s`` and ``max_bytes=100MB``. Override via environment
+variables ``FYLE_HTTP_TIMEOUT`` and ``FYLE_HTTP_MAX_BYTES``.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ..errors import DownloadError
+
+DEFAULT_TIMEOUT: float = 30.0
+DEFAULT_MAX_BYTES: int = 100 * 1024 * 1024  # 100 MB
+
+
+def _env_float(name: str, default: float) -> float:
+    v = os.environ.get(name)
+    if not v:
+        return default
+    try:
+        return float(v)
+    except ValueError:
+        return default
+
+
+def _env_int(name: str, default: int) -> int:
+    v = os.environ.get(name)
+    if not v:
+        return default
+    try:
+        return int(v)
+    except ValueError:
+        return default
+
+
+def fetch(url: str) -> tuple[bytes, Optional[str]]:
+    """Fetch ``url`` and return ``(bytes, content_type)``.
+
+    Timeouts, network errors, and responses exceeding ``max_bytes`` are all
+    raised as ``fyle.DownloadError`` (wrapping the underlying ``httpx`` error).
+    """
+    try:
+        import httpx
+    except ImportError as e:  # pragma: no cover
+        raise DownloadError("httpx is required for URL fetching: pip install httpx") from e
+
+    timeout = _env_float("FYLE_HTTP_TIMEOUT", DEFAULT_TIMEOUT)
+    max_bytes = _env_int("FYLE_HTTP_MAX_BYTES", DEFAULT_MAX_BYTES)
+
+    try:
+        with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+            with client.stream("GET", url) as resp:
+                resp.raise_for_status()
+                content_type = resp.headers.get("content-type")
+                buf = bytearray()
+                for chunk in resp.iter_bytes():
+                    buf.extend(chunk)
+                    if len(buf) > max_bytes:
+                        raise DownloadError(
+                            f"Response exceeds max_bytes={max_bytes}. "
+                            f"Override via FYLE_HTTP_MAX_BYTES env var."
+                        )
+                return bytes(buf), content_type
+    except DownloadError:
+        raise
+    except httpx.HTTPError as e:
+        raise DownloadError(f"Failed to fetch {url!r}: {e}") from e

fyle/_core/registry.py

@@ -0,0 +1,107 @@
+"""Reader registry — populated at build time, read-only at runtime.
+
+Not a public extension point. ``_register`` is invoked only from
+``_readers/base.py`` via ``__init_subclass__``; users must not register their own.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..errors import ReaderNotFoundError
+
+# Reader name -> Reader class.
+_BY_NAME: dict[str, type] = {}
+# Format name -> list of Reader classes, preserving registration order.
+_BY_FORMAT: dict[str, list[type]] = {}
+# Format name -> default Reader class for that format.
+_DEFAULTS: dict[str, type] = {}
+
+
+def _register(cls: type) -> None:
+    """Invoked by the Reader base class from ``__init_subclass__``."""
+    name = getattr(cls, "name", None)
+    formats = getattr(cls, "formats", None)
+    if not name or not formats:
+        raise RuntimeError(
+            f"Reader {cls.__name__} must define class attrs `name: str` and `formats: tuple[str, ...]`"
+        )
+    if name in _BY_NAME and _BY_NAME[name] is not cls:
+        raise RuntimeError(f"Reader name conflict: {name!r}")
+    _BY_NAME[name] = cls
+
+    is_default = bool(getattr(cls, "is_default", False))
+    for fmt in formats:
+        bucket = _BY_FORMAT.setdefault(fmt, [])
+        if cls not in bucket:
+            bucket.append(cls)
+        if is_default:
+            existing = _DEFAULTS.get(fmt)
+            if existing is not None and existing is not cls:
+                raise RuntimeError(
+                    f"Multiple default readers for format {fmt!r}: "
+                    f"{existing.name} and {cls.name}"
+                )
+            _DEFAULTS[fmt] = cls
+
+
+def validate() -> None:
+    """Startup check: every registered format must have exactly one default reader.
+
+    Fail fast if any format has readers but no default marked ``is_default=True``.
+    """
+    for fmt, readers in _BY_FORMAT.items():
+        if fmt not in _DEFAULTS:
+            raise RuntimeError(
+                f"Format {fmt!r} has readers {[r.name for r in readers]} "
+                f"but no default (is_default=True). Fix at startup."
+            )
+
+
+def resolve(fmt: str, name: Optional[str] = None) -> type:
+    """Resolve a Reader class from a format and optional reader name.
+
+    - ``name=None``: return the default reader for ``fmt``; if no reader is
+      registered for ``fmt``, raise ``ReaderNotFoundError``.
+    - ``name`` given but not registered: raise ``ReaderNotFoundError``.
+    - ``name`` given but does not support ``fmt``: raise ``ReaderNotFoundError``.
+    """
+    if name is None:
+        default_cls = _DEFAULTS.get(fmt)
+        if default_cls is None:
+            raise ReaderNotFoundError(
+                f"No reader registered for format {fmt!r}. "
+                f"Available: {sorted(_DEFAULTS)}"
+            )
+        return default_cls
+
+    cls = _BY_NAME.get(name)
+    if cls is None:
+        raise ReaderNotFoundError(
+            f"Reader {name!r} not found. Available: {sorted(_BY_NAME)}"
+        )
+    if fmt not in cls.formats:
+        raise ReaderNotFoundError(
+            f"Reader {name!r} does not support format {fmt!r} "
+            f"(supports: {list(cls.formats)})"
+        )
+    return cls
+
+
+def list_all() -> dict[str, list[str]]:
+    """Return ``{fmt: [name, ...]}``.
+
+    The default reader for each format is placed first and suffixed with ``*``.
+    Backs the public ``fyle.readers()`` helper.
+    """
+    out: dict[str, list[str]] = {}
+    for fmt, readers in _BY_FORMAT.items():
+        default_cls = _DEFAULTS.get(fmt)
+        names: list[str] = []
+        if default_cls is not None:
+            names.append(f"{default_cls.name}*")
+        for cls in readers:
+            if cls is default_cls:
+                continue
+            names.append(cls.name)
+        out[fmt] = names
+    return out

fyle/_core/sniffer.py

@@ -0,0 +1,251 @@
+"""Format sniffer — three-path detection: extension + magic bytes + HTTP Content-Type.
+
+Used by ``fyle.open`` to pick the right reader for a given input.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional, Union
+
+from ..errors import UnsupportedFormatError
+
+# Plain-text-ish extensions. Everything here routes to the ``text`` format
+# and is handled by the passthrough PlainTextReader. The list is intentionally
+# broad: source code, structured data, config, logs and lightweight markup are
+# all legitimate "feed this to an LLM" inputs for a file → LLM SDK.
+#
+# Excluded on purpose:
+# - ``.md`` / ``.markdown`` / ``.html`` / ``.htm`` / ``.csv``: have dedicated
+#   readers with structural extraction.
+# - Binary / office formats (``.pdf`` / ``.docx`` / ``.xlsx`` / images / audio):
+#   obviously not plain text.
+_TEXT_EXTS: tuple[str, ...] = (
+    # Generic plaintext
+    ".txt", ".text", ".readme",
+    # Python
+    ".py", ".pyi", ".pyx", ".pyw",
+    # JavaScript / TypeScript / web frontend sources
+    ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx",
+    ".vue", ".svelte", ".astro",
+    # Stylesheet sources (treated as plaintext — fyle is not a CSS parser)
+    ".css", ".scss", ".sass", ".less", ".styl",
+    # JVM family
+    ".java", ".kt", ".kts", ".scala", ".sc", ".groovy",
+    ".clj", ".cljs", ".cljc",
+    # Systems / native
+    ".c", ".h", ".cc", ".cpp", ".cxx", ".hpp", ".hh", ".hxx", ".inl",
+    ".m", ".mm", ".rs", ".go", ".swift", ".zig", ".d", ".nim",
+    # .NET
+    ".cs", ".fs", ".fsx", ".vb",
+    # Dynamic / scripting
+    ".rb", ".php", ".pl", ".pm", ".lua", ".dart",
+    ".r", ".jl", ".hs", ".ml", ".mli",
+    ".ex", ".exs", ".erl", ".hrl",
+    ".elm", ".purs", ".cr", ".rkt",
+    # Shell / batch
+    ".sh", ".bash", ".zsh", ".fish", ".ksh",
+    ".ps1", ".psm1", ".psd1", ".bat", ".cmd",
+    # Structured data
+    ".json", ".jsonl", ".ndjson", ".json5",
+    ".yaml", ".yml",
+    ".toml",
+    ".xml", ".plist", ".rss", ".atom", ".svg",
+    ".tsv",
+    # Config / env
+    ".ini", ".cfg", ".conf", ".properties", ".env",
+    ".editorconfig", ".gitignore", ".gitattributes", ".dockerignore",
+    ".npmrc", ".nvmrc", ".prettierrc", ".eslintrc", ".babelrc",
+    # Build / lock
+    ".mk", ".cmake", ".gradle", ".sbt", ".bazel", ".bzl",
+    ".lock",
+    # SQL / query
+    ".sql", ".psql", ".cql", ".hql", ".sparql", ".graphql", ".gql",
+    # Lightweight markup (beyond Markdown / HTML which have their own readers)
+    ".rst", ".adoc", ".asciidoc", ".tex", ".bib", ".org", ".textile",
+    # Templates / template-ish sources
+    ".hbs", ".handlebars", ".mustache", ".njk", ".liquid",
+    ".ejs", ".pug", ".jade", ".jinja", ".jinja2", ".j2", ".tmpl", ".tpl",
+    # IDLs / schemas
+    ".proto", ".thrift", ".avsc", ".capnp", ".fbs", ".smithy",
+    # Diagrams / dev meta
+    ".dot", ".mmd", ".puml", ".drawio",
+    # Logs / diffs / patches
+    ".log", ".diff", ".patch",
+    # Misc
+    ".resx",
+)
+
+# File extension -> format name.
+_EXT_MAP: dict[str, str] = {
+    ".pdf": "pdf",
+    ".docx": "docx",
+    ".xlsx": "xlsx",
+    ".pptx": "pptx",
+    ".db": "sqlite",
+    ".sqlite": "sqlite",
+    ".sqlite3": "sqlite",
+    # Archive containers. The ``archive`` reader extracts to disk and
+    # reports a Markdown listing; it deliberately does not parse contents.
+    # Note: OOXML formats (.docx / .xlsx / .pptx) and SQLite databases are
+    # technically ZIP-based or have their own magic; they are handled by
+    # dedicated readers above and take precedence via extension.
+    ".zip": "archive",
+    ".tar": "archive",
+    ".gz": "archive",
+    ".tgz": "archive",
+    ".bz2": "archive",
+    ".tbz2": "archive",
+    ".xz": "archive",
+    ".txz": "archive",
+    ".md": "markdown",
+    ".markdown": "markdown",
+    ".html": "html",
+    ".htm": "html",
+    ".csv": "csv",
+    ".png": "image",
+    ".jpg": "image",
+    ".jpeg": "image",
+    ".webp": "image",
+    ".m4a": "audio",
+    ".mp3": "audio",
+    ".wav": "audio",
+    ".mp4": "video",
+    ".m4v": "video",
+    ".mov": "video",
+    ".avi": "video",
+    ".mkv": "video",
+    ".webm": "video",
+    **{ext: "text" for ext in _TEXT_EXTS},
+}
+
+# HTTP Content-Type -> format name.
+_MIME_MAP: dict[str, str] = {
+    "application/pdf": "pdf",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+    "application/vnd.sqlite3": "sqlite",
+    "application/x-sqlite3": "sqlite",
+    # Archive MIME types → archive reader (extract + list).
+    "application/zip": "archive",
+    "application/x-zip-compressed": "archive",
+    "application/x-tar": "archive",
+    "application/gzip": "archive",
+    "application/x-gzip": "archive",
+    "application/x-bzip2": "archive",
+    "application/x-xz": "archive",
+    "text/markdown": "markdown",
+    "text/html": "html",
+    "application/xhtml+xml": "html",
+    "text/plain": "text",
+    "text/csv": "csv",
+    "application/csv": "csv",
+    # Structured text data — treat as plaintext for LLM consumption.
+    "application/json": "text",
+    "application/ld+json": "text",
+    "application/yaml": "text",
+    "application/x-yaml": "text",
+    "application/toml": "text",
+    "application/xml": "text",
+    "text/xml": "text",
+    "image/svg+xml": "text",
+    "application/javascript": "text",
+    "text/javascript": "text",
+    "application/typescript": "text",
+    "application/x-sh": "text",
+    "image/png": "image",
+    "image/jpeg": "image",
+    "image/webp": "image",
+    "audio/mp4": "audio",
+    "audio/mpeg": "audio",
+    "audio/wav": "audio",
+    "audio/x-wav": "audio",
+    "video/mp4": "video",
+    "video/quicktime": "video",
+    "video/x-msvideo": "video",
+    "video/x-matroska": "video",
+    "video/webm": "video",
+}
+
+
+def _sniff_magic(data: bytes) -> Optional[str]:
+    """Detect format from magic bytes. Covers the main v1 formats."""
+    if len(data) == 0:
+        return None
+    if data.startswith(b"%PDF-"):
+        return "pdf"
+    # SQLite: the header is exactly "SQLite format 3\x00" (16 bytes).
+    # Extensions like ``.db`` are ambiguous in the wild, so magic-byte
+    # detection is the authoritative check.
+    if data.startswith(b"SQLite format 3\x00"):
+        return "sqlite"
+    # PNG
+    if data.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image"
+    # JPEG
+    if data.startswith(b"\xff\xd8\xff"):
+        return "image"
+    # WEBP: RIFF....WEBP
+    if data.startswith(b"RIFF") and len(data) >= 12 and data[8:12] == b"WEBP":
+        return "image"
+    # WAV: RIFF....WAVE
+    if data.startswith(b"RIFF") and len(data) >= 12 and data[8:12] == b"WAVE":
+        return "audio"
+    # MP3: ID3 tag or MPEG frame header.
+    if data.startswith(b"ID3"):
+        return "audio"
+    if len(data) >= 2 and data[0] == 0xFF and (data[1] & 0xE0) == 0xE0:
+        return "audio"
+    # HTML: common opening tags.
+    head = data[:256].lstrip().lower()
+    if head.startswith(b"<!doctype html") or head.startswith(b"<html"):
+        return "html"
+    # OOXML / ZIP containers need extension or Content-Type to disambiguate;
+    # return None so the caller falls back to the extension path.
+    return None
+
+
+def detect(
+    src: Union[str, Path, bytes, bytearray],
+    *,
+    source_name: Optional[str] = None,
+    content_type: Optional[str] = None,
+) -> str:
+    """Detect the format name.
+
+    Detection priority:
+    1. HTTP Content-Type (passed by the caller in URL mode).
+    2. File extension from ``source_name`` or a string-valued ``src``.
+    3. Magic bytes.
+
+    Raises ``UnsupportedFormatError`` if all three paths fail.
+    """
+    fmt: Optional[str] = None
+
+    # 1. Content-Type (preferred in URL mode).
+    if content_type:
+        mime = content_type.split(";", 1)[0].strip().lower()
+        fmt = _MIME_MAP.get(mime)
+        # Generic ``text/*`` fallback: any unrecognised ``text/*`` subtype
+        # (e.g. ``text/x-python``, ``text/vnd.something``) routes to the
+        # plaintext reader. Never downgrades a format we already mapped.
+        if fmt is None and mime.startswith("text/"):
+            fmt = "text"
+
+    # 2. File extension.
+    name = source_name
+    if fmt is None and name is None and isinstance(src, (str, Path)):
+        name = str(src)
+    if fmt is None and name:
+        ext = Path(name).suffix.lower()
+        fmt = _EXT_MAP.get(ext)
+
+    # 3. Magic bytes.
+    if fmt is None and isinstance(src, (bytes, bytearray)):
+        fmt = _sniff_magic(bytes(src[:512]))
+
+    if fmt is None:
+        raise UnsupportedFormatError(
+            f"Cannot detect format (source_name={source_name!r}, content_type={content_type!r})"
+        )
+    return fmt

fyle/_readers/__init__.py

@@ -0,0 +1,32 @@
+"""Import every reader subpackage to trigger auto-registration.
+
+Reader subclasses register themselves via ``__init_subclass__`` in
+``base.py``, which only fires once the defining module is imported. This
+file is therefore the single place that decides which readers are available
+at runtime — add one ``from . import <subpkg>`` line per new reader subpackage.
+
+File-name convention inside each subpackage: every reader implementation
+file is named after its *core driver library* (for example ``mammoth.py``,
+``markdownify.py``, ``openpyxl.py``, ``pymupdf4llm.py``, ``stdlib.py``).
+Post-processors (e.g. ``tabulate``, ``beautifulsoup4``) do not determine
+the file name. This keeps the door open for same-format alternative
+implementations to co-exist under their own library names.
+"""
+# Batch 1 (v0.2): text family — text / markdown / csv.
+# Batch 2 (v0.3): structured documents — docx / html / xlsx.
+# Batch 3 (v0.4): pptx / image.
+# Batch 4 (placeholder): audio / video — reserve the format slots; readers
+# raise ``NotImplementedReaderError`` until concrete backends land.
+from . import pdf  # noqa: F401
+from . import text  # noqa: F401
+from . import markdown  # noqa: F401
+from . import csv  # noqa: F401
+from . import docx  # noqa: F401
+from . import html  # noqa: F401
+from . import xlsx  # noqa: F401
+from . import pptx  # noqa: F401
+from . import image  # noqa: F401
+from . import sqlite  # noqa: F401
+from . import archive  # noqa: F401
+from . import audio  # noqa: F401
+from . import video  # noqa: F401

fyle/_readers/_md_structure.py

@@ -0,0 +1,208 @@
+"""Markdown structural extraction shared by every reader whose ``Page.text``
+is Markdown (currently: ``markdown``, ``docx``, ``html``).
+
+The contract is deliberately narrow: given a Markdown string, return the
+``Table`` and ``Image`` objects that appear in it. Page text itself is not
+modified — this is *extraction only*, so the caller's passthrough / rendering
+decisions remain untouched.
+
+Design notes:
+- Parsing is delegated to ``markdown-it-py`` (GFM-like, with the table
+  plugin enabled). We never regex-parse Markdown structure ourselves
+  (see design doc §12.0).
+- HTML ``<img>`` tags embedded in the Markdown are picked up via
+  BeautifulSoup when ``include_html_img=True``. This matters in practice
+  because:
+    - README / docs frequently write logos and badges as ``<img>`` for
+      width / alignment control;
+    - ``markdownify`` (used by docx & html readers) preserves HTML fragments
+      it can't map to Markdown.
+- Image ``data_url`` may be a ``data:image/...;base64,...`` URL (DOCX /
+  PDF / HTML inline images) or a plain ``http(s)://`` URL (Markdown
+  references). Both are valid per the ``Image`` contract.
+- Every failure path is non-fatal: if markdown-it-py or bs4 fail we append
+  a warning and return whatever we managed to collect. The reader's main
+  job (producing ``Page.text``) should never be blocked by optional
+  structural extraction.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .._core.document import Image, Table
+
+
+def extract_tables(
+    md_text: str,
+    *,
+    page: int = 1,
+    warnings: Optional[list[str]] = None,
+) -> list[Table]:
+    """Extract GFM pipe tables from Markdown.
+
+    ``table.text`` is a verbatim slice of the source (using ``token.map``),
+    not a re-render. ``table.rows`` contains string cells.
+    """
+    warnings = warnings if warnings is not None else []
+    try:
+        from markdown_it import MarkdownIt
+    except ImportError:
+        warnings.append("markdown-it-py not installed; skipping table extraction")
+        return []
+    try:
+        md_parser = MarkdownIt().enable("table")
+        tokens = md_parser.parse(md_text)
+    except Exception as e:
+        warnings.append(f"markdown parse failed; tables not extracted: {e}")
+        return []
+
+    lines = md_text.splitlines(keepends=True)
+    tables: list[Table] = []
+    i = 0
+    while i < len(tokens):
+        tok = tokens[i]
+        if tok.type == "table_open":
+            headers, rows, advance = _walk_table(tokens, i)
+            table_md = ""
+            if tok.map:
+                start, end = tok.map  # half-open
+                table_md = "".join(lines[start:end]).rstrip("\n")
+            tables.append(
+                Table(
+                    text=table_md,
+                    rows=rows,
+                    headers=headers,
+                    page=page,
+                )
+            )
+            i = advance
+        else:
+            i += 1
+    return tables
+
+
+def _walk_table(tokens, start_idx: int) -> tuple[list[str], list[list[str]], int]:
+    """Collect ``(headers, body_rows, index_after_table_close)`` from tokens.
+
+    markdown-it-py table token shape::
+
+        table_open
+          thead_open
+            tr_open
+              th_open, inline (cell), th_close  ...
+            tr_close
+          thead_close
+          tbody_open
+            tr_open
+              td_open, inline (cell), td_close  ...
+            tr_close
+            ...
+          tbody_close
+        table_close
+    """
+    headers: list[str] = []
+    rows: list[list[str]] = []
+    current_row: list[str] = []
+    in_thead = False
+
+    i = start_idx + 1
+    while i < len(tokens):
+        tok = tokens[i]
+        t = tok.type
+        if t == "table_close":
+            return headers, rows, i + 1
+        if t == "thead_open":
+            in_thead = True
+        elif t == "thead_close":
+            in_thead = False
+        elif t == "tr_open":
+            current_row = []
+        elif t == "tr_close":
+            if in_thead:
+                headers = current_row
+            else:
+                rows.append(current_row)
+        elif t == "inline":
+            current_row.append(tok.content)
+        i += 1
+    return headers, rows, i
+
+
+def extract_images(
+    md_text: str,
+    *,
+    page: int = 1,
+    warnings: Optional[list[str]] = None,
+    include_html_img: bool = True,
+) -> list[Image]:
+    """Extract image references from Markdown.
+
+    Two sources are consulted and the results are concatenated:
+
+    1. Native Markdown ``![alt](url)`` tokens via markdown-it-py.
+    2. HTML ``<img src="..." alt="...">`` tags via BeautifulSoup
+       (only when ``include_html_img=True``).
+
+    ``data_url`` carries whatever URL appeared in the source: a ``data:``
+    URL for inline base64 images (DOCX, PDF, HTML inline), or a plain
+    ``http(s)://`` URL for referenced images. The reader does not fetch
+    remote URLs — that is an application concern.
+    """
+    warnings = warnings if warnings is not None else []
+    images: list[Image] = []
+
+    # 1. Markdown native images.
+    try:
+        from markdown_it import MarkdownIt
+        md_parser = MarkdownIt().enable("table")
+        tokens = md_parser.parse(md_text)
+        for tok in tokens:
+            children = getattr(tok, "children", None) or []
+            for child in children:
+                if child.type == "image":
+                    src = ""
+                    if getattr(child, "attrs", None):
+                        src = child.attrs.get("src") or ""
+                    alt = (child.content or "").strip()
+                    if src:
+                        images.append(
+                            Image(
+                                data_url=src,
+                                data=b"",
+                                caption=alt or None,
+                                page=page,
+                            )
+                        )
+    except ImportError:
+        warnings.append(
+            "markdown-it-py not installed; skipping Markdown image extraction"
+        )
+    except Exception as e:
+        warnings.append(f"Markdown image extraction failed: {e}")
+
+    # 2. HTML <img> tags mixed into the Markdown (common for badges / logos).
+    if include_html_img:
+        try:
+            from bs4 import BeautifulSoup
+            soup = BeautifulSoup(md_text, "html.parser")
+            for tag in soup.find_all("img"):
+                src = (tag.get("src") or "").strip()
+                if not src:
+                    continue
+                alt = (tag.get("alt") or "").strip()
+                images.append(
+                    Image(
+                        data_url=src,
+                        data=b"",
+                        caption=alt or None,
+                        page=page,
+                    )
+                )
+        except ImportError:
+            warnings.append(
+                "beautifulsoup4 not installed; skipping HTML <img> extraction"
+            )
+        except Exception as e:
+            warnings.append(f"HTML <img> extraction failed: {e}")
+
+    return images