everythingtohtml 0.1.2__py3-none-any.whl

everythingtohtml/__about__.py

@@ -0,0 +1,3 @@
+"""Version information for everythingtohtml."""
+
+__version__ = "0.1.2"

everythingtohtml/__init__.py

@@ -0,0 +1,34 @@
+"""everythingtohtml — convert (almost) any file into clean, self-contained HTML.
+
+Quick start
+-----------
+>>> from everythingtohtml import EverythingToHtml
+>>> eth = EverythingToHtml()
+>>> result = eth.convert("document.docx")   # doctest: +SKIP
+>>> open("document.html", "w", encoding="utf-8").write(result.html)  # doctest: +SKIP
+"""
+
+from __future__ import annotations
+
+from .__about__ import __version__
+from ._base_converter import DocumentConverter, DocumentConverterResult
+from ._everything_to_html import EverythingToHtml
+from ._exceptions import (
+    EverythingToHtmlException,
+    FileConversionException,
+    MissingDependencyException,
+    UnsupportedFormatException,
+)
+from ._stream_info import StreamInfo
+
+__all__ = [
+    "__version__",
+    "EverythingToHtml",
+    "DocumentConverter",
+    "DocumentConverterResult",
+    "StreamInfo",
+    "EverythingToHtmlException",
+    "FileConversionException",
+    "MissingDependencyException",
+    "UnsupportedFormatException",
+]

everythingtohtml/__main__.py

@@ -0,0 +1,130 @@
+"""Command-line interface for everythingtohtml.
+
+Examples
+--------
+    everythingtohtml report.docx > report.html
+    everythingtohtml data.csv -o data.html
+    everythingtohtml https://example.com/feed.rss
+    cat notes.md | everythingtohtml --extension .md > notes.html
+
+    # merge several documents into one HTML (great for Word files)
+    everythingtohtml a.docx b.docx c.doc -o merged.html
+    everythingtohtml old.docx new.docx --columns -o side-by-side.html
+
+    # compare two documents with a highlighted line diff
+    everythingtohtml old.docx new.docx --diff -o changes.html
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from .__about__ import __version__
+from ._everything_to_html import EverythingToHtml
+from ._exceptions import EverythingToHtmlException
+from ._stream_info import StreamInfo
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="everythingtohtml",
+        description="Convert files, URLs, or stdin into clean, self-contained HTML.",
+    )
+    parser.add_argument(
+        "sources",
+        nargs="*",
+        help="One or more paths/URLs. Two or more are merged; omit (or '-') for stdin.",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        help="Write HTML to this file instead of stdout.",
+    )
+    parser.add_argument(
+        "-e",
+        "--extension",
+        help="Hint the source extension (e.g. '.md') when reading from stdin.",
+    )
+    parser.add_argument(
+        "-m",
+        "--mimetype",
+        help="Hint the source mimetype when it cannot be inferred.",
+    )
+    parser.add_argument(
+        "--charset",
+        help="Hint the source character encoding (e.g. 'utf-8').",
+    )
+    parser.add_argument(
+        "--columns",
+        action="store_true",
+        help="When merging multiple sources, lay them out side by side.",
+    )
+    parser.add_argument(
+        "--diff",
+        action="store_true",
+        help="Compare exactly two sources with a highlighted line diff.",
+    )
+    parser.add_argument(
+        "--no-toc",
+        action="store_true",
+        help="When merging, omit the table of contents.",
+    )
+    parser.add_argument(
+        "--use-plugins",
+        action="store_true",
+        help="Load third-party converter plugins registered via entry points.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"everythingtohtml {__version__}",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    stream_info = StreamInfo(
+        extension=args.extension,
+        mimetype=args.mimetype,
+        charset=args.charset,
+    )
+    engine = EverythingToHtml(enable_plugins=args.use_plugins)
+    sources = args.sources
+
+    try:
+        if args.diff:
+            if len(sources) != 2:
+                parser.error("--diff requires exactly two sources")
+            result = engine.diff(sources[0], sources[1])
+        elif len(sources) > 1:
+            result = engine.merge(
+                sources,
+                layout="columns" if args.columns else "stacked",
+                include_toc=not args.no_toc,
+            )
+        elif len(sources) == 1 and sources[0] != "-":
+            result = engine.convert(sources[0], stream_info=stream_info)
+        else:
+            data = sys.stdin.buffer.read()
+            result = engine.convert(data, stream_info=stream_info)
+    except EverythingToHtmlException as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as handle:
+            handle.write(result.html)
+    else:
+        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        sys.stdout.write(result.html)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

everythingtohtml/_base_converter.py

@@ -0,0 +1,78 @@
+"""The converter contract and the result object every converter returns."""
+
+from __future__ import annotations
+
+from typing import Any, BinaryIO
+
+from ._stream_info import StreamInfo
+
+__all__ = ["DocumentConverter", "DocumentConverterResult"]
+
+
+class DocumentConverterResult:
+    """The output of a successful conversion.
+
+    The canonical payload is :attr:`html`. ``text_content`` is provided as an
+    alias so code written against markdown-style converters keeps working when
+    pointed at this library, and ``str(result)`` yields the HTML directly.
+    """
+
+    def __init__(
+        self,
+        html: str,
+        *,
+        title: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.html = html
+        self.title = title
+        self.metadata = metadata or {}
+
+    @property
+    def text_content(self) -> str:
+        """Alias for :attr:`html` (drop-in compatibility with markdown converters)."""
+        return self.html
+
+    @text_content.setter
+    def text_content(self, value: str) -> None:
+        self.html = value
+
+    def __str__(self) -> str:
+        return self.html
+
+
+class DocumentConverter:
+    """Base class for all converters.
+
+    A converter answers two questions:
+
+    * :meth:`accepts` — *can* I handle this stream? (cheap, no side effects)
+    * :meth:`convert` — *do* the conversion and return HTML.
+
+    ``accepts`` must not consume the stream destructively: read what you need to
+    sniff, then ``seek(0)`` back. ``convert`` may read freely; the engine resets
+    the stream before handing it to each converter.
+    """
+
+    # Higher priority converters are tried first. Specific format converters use
+    # low numbers; greedy catch-alls (plain text) use high numbers.
+    PRIORITY_SPECIFIC_FILE_FORMAT = 0.0
+    PRIORITY_GENERIC_FILE_FORMAT = 10.0
+
+    priority: float = PRIORITY_SPECIFIC_FILE_FORMAT
+
+    def accepts(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> bool:
+        raise NotImplementedError
+
+    def convert(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        raise NotImplementedError

everythingtohtml/_everything_to_html.py

@@ -0,0 +1,408 @@
+"""The :class:`EverythingToHtml` engine: detection, dispatch, and plugins."""
+
+from __future__ import annotations
+
+import io
+import mimetypes
+import os
+import sys
+from collections.abc import Iterable
+from typing import Any, BinaryIO
+from urllib.parse import unquote, urlparse
+from urllib.request import url2pathname
+
+from ._base_converter import DocumentConverter, DocumentConverterResult
+from ._exceptions import (
+    FailedConversionAttempt,
+    FileConversionException,
+    MissingDependencyException,
+    UnsupportedFormatException,
+)
+from ._stream_info import StreamInfo
+from .converters import (
+    CsvConverter,
+    DocConverter,
+    DocxConverter,
+    EmlConverter,
+    EpubConverter,
+    HtmlConverter,
+    IpynbConverter,
+    JsonConverter,
+    MarkdownConverter,
+    OdtConverter,
+    PdfConverter,
+    PlainTextConverter,
+    PptxConverter,
+    RssConverter,
+    RstConverter,
+    XlsxConverter,
+    YamlConverter,
+)
+
+__all__ = ["EverythingToHtml"]
+
+_PLUGIN_ENTRY_POINT_GROUP = "everythingtohtml.converter"
+
+# Built-in converters, registered in dependency-light first order. Specific
+# formats are registered after the catch-all so that, on ties, they win.
+_BUILTIN_CONVERTERS: tuple[type[DocumentConverter], ...] = (
+    PlainTextConverter,
+    HtmlConverter,
+    MarkdownConverter,
+    CsvConverter,
+    JsonConverter,
+    YamlConverter,
+    IpynbConverter,
+    RssConverter,
+    RstConverter,
+    EmlConverter,
+    EpubConverter,
+    OdtConverter,
+    DocConverter,
+    DocxConverter,
+    XlsxConverter,
+    PptxConverter,
+    PdfConverter,
+)
+
+
+class _Registration:
+    __slots__ = ("converter", "priority", "index")
+
+    def __init__(self, converter: DocumentConverter, index: int) -> None:
+        self.converter = converter
+        self.priority = converter.priority
+        self.index = index
+
+
+class EverythingToHtml:
+    """Convert files, streams, and URIs into clean, self-contained HTML.
+
+    Example
+    -------
+    >>> from everythingtohtml import EverythingToHtml
+    >>> eth = EverythingToHtml()
+    >>> result = eth.convert("README.md")
+    >>> result.html.startswith("<!DOCTYPE html>")
+    True
+    """
+
+    def __init__(
+        self,
+        *,
+        enable_builtins: bool = True,
+        enable_plugins: bool = False,
+    ) -> None:
+        self._registrations: list[_Registration] = []
+        self._next_index = 0
+        if enable_builtins:
+            for converter_cls in _BUILTIN_CONVERTERS:
+                self.register_converter(converter_cls())
+        if enable_plugins:
+            self.load_plugins()
+
+    # -- registration ------------------------------------------------------
+
+    def register_converter(self, converter: DocumentConverter) -> None:
+        """Add a converter. Later registrations win ties against earlier ones."""
+        self._registrations.append(_Registration(converter, self._next_index))
+        self._next_index += 1
+
+    def load_plugins(self) -> None:
+        """Discover and register third-party converters via entry points.
+
+        A plugin advertises a callable under the ``everythingtohtml.converter``
+        entry-point group; the callable receives this engine and registers its
+        own converters. See ``docs/PLUGINS.md``.
+        """
+        from importlib.metadata import entry_points
+
+        for ep in entry_points(group=_PLUGIN_ENTRY_POINT_GROUP):
+            register = ep.load()
+            register(self)
+
+    @property
+    def _ordered(self) -> list[DocumentConverter]:
+        # Lowest priority number first; for equal priority, most-recently
+        # registered first (so plugins and later converters can override).
+        ordered = sorted(self._registrations, key=lambda r: (r.priority, -r.index))
+        return [r.converter for r in ordered]
+
+    # -- public conversion API --------------------------------------------
+
+    def convert(
+        self,
+        source: str | os.PathLike[str] | bytes | BinaryIO,
+        *,
+        stream_info: StreamInfo | None = None,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert ``source`` to HTML.
+
+        ``source`` may be a local path, a URI (``http``, ``https``, ``file``,
+        ``data``), raw ``bytes``, or an already-open binary stream.
+        """
+        if isinstance(source, (str, os.PathLike)):
+            text = os.fspath(source)
+            if _looks_like_uri(text):
+                return self.convert_uri(text, stream_info=stream_info, **kwargs)
+            return self.convert_local(text, stream_info=stream_info, **kwargs)
+        if isinstance(source, (bytes, bytearray)):
+            return self.convert_stream(io.BytesIO(bytes(source)), stream_info=stream_info, **kwargs)
+        return self.convert_stream(source, stream_info=stream_info, **kwargs)
+
+    def convert_local(
+        self,
+        path: str | os.PathLike[str],
+        *,
+        stream_info: StreamInfo | None = None,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert a file on the local filesystem."""
+        path = os.fspath(path)
+        base = StreamInfo(
+            local_path=path,
+            filename=os.path.basename(path),
+            extension=_ext(path),
+            mimetype=mimetypes.guess_type(path)[0],
+        )
+        guessed = base.copy_and_update(stream_info)
+        with open(path, "rb") as stream:
+            return self._convert(stream, guessed, **kwargs)
+
+    def convert_stream(
+        self,
+        stream: BinaryIO,
+        *,
+        stream_info: StreamInfo | None = None,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert an open binary stream.
+
+        The stream must be seekable; if it is not, it is buffered into memory.
+        """
+        if not stream.seekable():
+            stream = io.BytesIO(stream.read())
+        guessed = stream_info or StreamInfo()
+        return self._convert(stream, guessed, **kwargs)
+
+    def convert_uri(
+        self,
+        uri: str,
+        *,
+        stream_info: StreamInfo | None = None,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert content addressed by a URI (``http(s)``, ``file``, ``data``)."""
+        uri = uri.strip()
+        parsed = urlparse(uri)
+        scheme = parsed.scheme.lower()
+
+        if scheme == "file":
+            local = url2pathname(parsed.path)
+            return self.convert_local(local, stream_info=stream_info, **kwargs)
+        if scheme == "data":
+            stream, info = _read_data_uri(uri)
+            return self._convert(stream, info.copy_and_update(stream_info), **kwargs)
+        if scheme in ("http", "https"):
+            stream, info = _fetch_http(uri)
+            return self._convert(stream, info.copy_and_update(stream_info), **kwargs)
+        raise UnsupportedFormatException(f"Unsupported URI scheme: {scheme!r}")
+
+    # -- multi-document composition ---------------------------------------
+
+    def merge(
+        self,
+        sources: Iterable[str | os.PathLike[str] | bytes | BinaryIO],
+        *,
+        title: str | None = None,
+        layout: str = "stacked",
+        include_toc: bool = True,
+        labels: list[str] | None = None,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Convert several sources and combine them into one HTML document.
+
+        ``layout="stacked"`` (default) renders them top-to-bottom with a table of
+        contents; ``layout="columns"`` places them side by side for comparison.
+        Each document's detected title is used as its heading unless ``labels`` is
+        given. Great for collating or comparing a set of Word documents.
+        """
+        from ._merge import body_fragment, build_merged_html
+
+        items: list[tuple[str, str]] = []
+        for index, source in enumerate(sources):
+            result = self.convert(source, **kwargs)
+            label = (
+                labels[index]
+                if labels and index < len(labels)
+                else (result.title or _source_label(source, index))
+            )
+            items.append((label, body_fragment(result.html)))
+
+        if not items:
+            raise ValueError("merge() requires at least one source")
+
+        html = build_merged_html(items, title=title, layout=layout, include_toc=include_toc)
+        return DocumentConverterResult(html, title=title)
+
+    def diff(
+        self,
+        left: str | os.PathLike[str] | bytes | BinaryIO,
+        right: str | os.PathLike[str] | bytes | BinaryIO,
+        *,
+        title: str | None = None,
+        left_label: str | None = None,
+        right_label: str | None = None,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        """Render a side-by-side line diff of two sources' text content."""
+        from ._merge import build_diff_html, plain_text_lines
+
+        left_result = self.convert(left, **kwargs)
+        right_result = self.convert(right, **kwargs)
+
+        html = build_diff_html(
+            left_label or left_result.title or _source_label(left, 0),
+            plain_text_lines(left_result.html),
+            right_label or right_result.title or _source_label(right, 1),
+            plain_text_lines(right_result.html),
+            title=title,
+        )
+        return DocumentConverterResult(html, title=title or "Document comparison")
+
+    # -- internals ---------------------------------------------------------
+
+    def _convert(
+        self,
+        stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        enriched = self._sniff(stream, stream_info)
+
+        attempts: list[FailedConversionAttempt] = []
+        missing_dependency: MissingDependencyException | None = None
+        for converter in self._ordered:
+            stream.seek(0)
+            try:
+                if not converter.accepts(stream, enriched, **kwargs):
+                    continue
+            except Exception:  # a misbehaving accepts() should not abort dispatch
+                continue
+
+            stream.seek(0)
+            try:
+                return converter.convert(stream, enriched, **kwargs)
+            except MissingDependencyException as exc:
+                # Remember the first actionable "install this extra" signal so it
+                # can be surfaced if nothing else handles the input.
+                if missing_dependency is None:
+                    missing_dependency = exc
+                attempts.append(FailedConversionAttempt(converter, sys.exc_info()))
+            except Exception:
+                attempts.append(FailedConversionAttempt(converter, sys.exc_info()))
+
+        # A missing optional dependency is the most useful thing to report, so it
+        # takes precedence over the generic "all converters failed" message.
+        if missing_dependency is not None:
+            raise missing_dependency
+        if attempts:
+            raise FileConversionException(attempts=attempts)
+        raise UnsupportedFormatException(
+            "No converter could handle this input "
+            f"(extension={enriched.extension!r}, mimetype={enriched.mimetype!r}). "
+            "It may need an optional extra; see 'pip install everythingtohtml[all]'."
+        )
+
+    @staticmethod
+    def _sniff(stream: BinaryIO, stream_info: StreamInfo) -> StreamInfo:
+        """Fill in missing extension/mimetype hints from magic bytes."""
+        if stream_info.extension and stream_info.mimetype:
+            return stream_info
+
+        pos = stream.tell()
+        header = stream.read(2048)
+        stream.seek(pos)
+        if not header:
+            return stream_info
+
+        try:
+            import puremagic
+
+            matches = puremagic.magic_string(header)
+        except Exception:
+            return stream_info
+
+        if not matches:
+            return stream_info
+
+        best = matches[0]
+        updates: dict[str, object] = {}
+        if not stream_info.extension and getattr(best, "extension", None):
+            updates["extension"] = best.extension
+        if not stream_info.mimetype and getattr(best, "mime_type", None):
+            updates["mimetype"] = best.mime_type
+        return stream_info.copy_and_update(**updates) if updates else stream_info
+
+
+# -- module-level helpers --------------------------------------------------
+
+
+def _ext(path: str) -> str | None:
+    ext = os.path.splitext(path)[1]
+    return ext or None
+
+
+def _source_label(source: object, index: int) -> str:
+    """A human-friendly label for a source in merged/diffed output."""
+    if isinstance(source, (str, os.PathLike)):
+        return os.path.basename(os.fspath(source)) or os.fspath(source)
+    return f"Document {index + 1}"
+
+
+def _looks_like_uri(text: str) -> bool:
+    """True if ``text`` has a URI scheme rather than being a local path.
+
+    A single-character "scheme" is treated as a Windows drive letter (``C:\\...``)
+    and therefore *not* a URI. Recognised URI schemes are dispatched by
+    :meth:`EverythingToHtml.convert_uri`, which rejects unsupported ones.
+    """
+    scheme = urlparse(text).scheme.lower()
+    return bool(scheme) and len(scheme) > 1
+
+
+def _read_data_uri(uri: str) -> tuple[BinaryIO, StreamInfo]:
+    import base64
+
+    header, _, data = uri[len("data:") :].partition(",")
+    is_base64 = header.endswith(";base64")
+    mimetype = header.split(";", 1)[0] or None
+    charset = None
+    for part in header.split(";"):
+        if part.startswith("charset="):
+            charset = part[len("charset=") :]
+    raw = base64.b64decode(data) if is_base64 else unquote(data).encode("utf-8")
+    ext = mimetypes.guess_extension(mimetype) if mimetype else None
+    return io.BytesIO(raw), StreamInfo(mimetype=mimetype, charset=charset, extension=ext)
+
+
+def _fetch_http(uri: str) -> tuple[BinaryIO, StreamInfo]:
+    from urllib.request import Request, urlopen
+
+    request = Request(uri, headers={"User-Agent": "everythingtohtml"})
+    with urlopen(request, timeout=30) as response:  # noqa: S310 - scheme checked by caller
+        raw = response.read()
+        content_type = response.headers.get_content_type()
+        charset = response.headers.get_content_charset()
+        final_url = response.geturl()
+
+    path = urlparse(final_url).path
+    filename = os.path.basename(path) or None
+    return io.BytesIO(raw), StreamInfo(
+        mimetype=content_type or None,
+        charset=charset,
+        extension=_ext(path),
+        filename=filename,
+        url=final_url,
+    )