everythingtohtml 0.1.2__py3-none-any.whl

everythingtohtml/_exceptions.py

@@ -0,0 +1,63 @@
+"""Exception hierarchy for everythingtohtml.
+
+The layout mirrors the ergonomics of well-behaved conversion libraries: a single
+base class so callers can ``except EverythingToHtmlException`` and catch anything
+the library raises on purpose.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "EverythingToHtmlException",
+    "UnsupportedFormatException",
+    "FileConversionException",
+    "MissingDependencyException",
+]
+
+
+class EverythingToHtmlException(Exception):
+    """Base class for all exceptions raised by everythingtohtml."""
+
+
+class MissingDependencyException(EverythingToHtmlException):
+    """Raised when a converter needs an optional dependency that is not installed.
+
+    The message tells the user exactly which extra to install, e.g.::
+
+        pip install everythingtohtml[docx]
+    """
+
+
+class UnsupportedFormatException(EverythingToHtmlException):
+    """Raised when no registered converter is able to handle the input."""
+
+
+class FailedConversionAttempt:
+    """Bookkeeping for a converter that accepted the input but then failed.
+
+    Collected so :class:`FileConversionException` can report every attempt rather
+    than only the last traceback, which makes debugging multi-converter inputs far
+    easier.
+    """
+
+    def __init__(self, converter: object, exc_info: object | None = None) -> None:
+        self.converter = converter
+        self.exc_info = exc_info
+
+
+class FileConversionException(EverythingToHtmlException):
+    """Raised when one or more converters accepted the input but all failed."""
+
+    def __init__(
+        self,
+        message: str | None = None,
+        attempts: list[FailedConversionAttempt] | None = None,
+    ) -> None:
+        self.attempts = attempts or []
+        if message is None:
+            if self.attempts:
+                names = ", ".join(type(a.converter).__name__ for a in self.attempts)
+                message = f"All converters that accepted the input failed: {names}"
+            else:
+                message = "File conversion failed."
+        super().__init__(message)

everythingtohtml/_html_builder.py

@@ -0,0 +1,106 @@
+"""Helpers for assembling clean, self-contained HTML documents.
+
+Every converter produces an HTML *fragment* (the meaningful body markup). This
+module wraps fragments into a full document with a small, readable default
+stylesheet so the output looks decent on its own while staying easy to restyle.
+"""
+
+from __future__ import annotations
+
+from html import escape as _escape
+
+__all__ = ["escape_text", "escape_attr", "wrap_document", "DEFAULT_STYLESHEET"]
+
+
+DEFAULT_STYLESHEET = """\
+:root { color-scheme: light dark; }
+* { box-sizing: border-box; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica,
+    Arial, sans-serif;
+  line-height: 1.6;
+  max-width: 50rem;
+  margin: 2rem auto;
+  padding: 0 1rem;
+  color: #1a1a1a;
+  background: #ffffff;
+}
+@media (prefers-color-scheme: dark) {
+  body { color: #e6e6e6; background: #121212; }
+  a { color: #6ea8fe; }
+  table th { background: #1e1e1e; }
+  table td, table th { border-color: #333; }
+  table tr:nth-child(even) td { background: rgba(255,255,255,0.03); }
+  pre, code { background: #1e1e1e; }
+}
+h1, h2, h3 { line-height: 1.25; }
+a { color: #0b5cff; }
+/* Tables: scroll horizontally when wider than the page instead of overflowing. */
+table {
+  border-collapse: collapse;
+  margin: 1rem 0;
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  font-size: 0.95em;
+}
+table td, table th {
+  border: 1px solid #d4d4dc;
+  padding: 0.4rem 0.65rem;
+  text-align: left;
+  vertical-align: top;
+}
+table th { background: #f5f5f5; font-weight: 600; }
+table tr:nth-child(even) td { background: rgba(0,0,0,0.025); }
+/* Office converters wrap cell content in <p>; keep cells compact. */
+table td > p, table th > p { margin: 0.1rem 0; }
+table td > p:only-child, table th > p:only-child { margin: 0; }
+pre {
+  background: #f5f5f5; padding: 1rem; overflow-x: auto; border-radius: 6px;
+}
+code { background: #f5f5f5; padding: 0.1rem 0.3rem; border-radius: 4px; }
+pre code { padding: 0; background: none; }
+blockquote {
+  border-left: 4px solid #ddd; margin: 1rem 0; padding: 0.2rem 1rem; color: #666;
+}
+img { max-width: 100%; height: auto; }
+"""
+
+
+def escape_text(text: str) -> str:
+    """Escape text for safe inclusion in HTML element content."""
+    return _escape(text, quote=False)
+
+
+def escape_attr(text: str) -> str:
+    """Escape text for safe inclusion in a double-quoted HTML attribute."""
+    return _escape(text, quote=True)
+
+
+def wrap_document(
+    body: str,
+    *,
+    title: str | None = None,
+    lang: str = "en",
+    include_style: bool = True,
+    extra_head: str = "",
+) -> str:
+    """Wrap an HTML *fragment* into a complete, standalone HTML5 document."""
+    safe_title = escape_text(title) if title else "Converted Document"
+    style = f"<style>\n{DEFAULT_STYLESHEET}</style>\n" if include_style else ""
+    return (
+        "<!DOCTYPE html>\n"
+        f'<html lang="{escape_attr(lang)}">\n'
+        "<head>\n"
+        '<meta charset="utf-8">\n'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">\n'
+        '<meta name="generator" content="everythingtohtml">\n'
+        f"<title>{safe_title}</title>\n"
+        f"{style}"
+        f"{extra_head}"
+        "</head>\n"
+        "<body>\n"
+        f"{body}\n"
+        "</body>\n"
+        "</html>\n"
+    )

everythingtohtml/_merge.py

@@ -0,0 +1,145 @@
+"""Combine and compare multiple converted documents in a single HTML page.
+
+These helpers operate on the *output* of converters, so they work for any format
+the library supports — merge a folder of Word docs, stack a PDF next to its
+Markdown source, or diff two revisions of a spec.
+"""
+
+from __future__ import annotations
+
+import difflib
+
+from ._html_builder import escape_attr, escape_text, wrap_document
+
+__all__ = ["body_fragment", "plain_text_lines", "build_merged_html", "build_diff_html"]
+
+
+_MERGE_STYLE = """
+.merge-toc { border: 1px solid #ddd; border-radius: 6px; padding: 0.5rem 1rem; margin-bottom: 2rem; }
+.merge-toc ol { margin: 0.3rem 0; }
+.merge-doc { margin-bottom: 3rem; padding-bottom: 2rem; border-bottom: 2px solid #eee; }
+.merge-doc:last-child { border-bottom: none; }
+.merge-doc > h2.merge-title { margin-top: 0; }
+.merge-columns { display: flex; gap: 2rem; align-items: flex-start; }
+.merge-columns .merge-col { flex: 1 1 0; min-width: 0; }
+@media (max-width: 48rem) { .merge-columns { flex-direction: column; } }
+"""
+
+_DIFF_STYLE = """
+table.diff { width: 100%; border-collapse: collapse; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 0.85rem; }
+table.diff td { padding: 0 0.4rem; vertical-align: top; white-space: pre-wrap; word-break: break-word; }
+.diff_header { color: #999; text-align: right; }
+td.diff_header { padding-right: 0.6rem; }
+.diff_next { background: #f3f3f3; }
+.diff_add { background: #d6ffd6; }
+.diff_chg { background: #fff5b1; }
+.diff_sub { background: #ffd6d6; }
+.diff-legend { font-size: 0.85rem; margin: 0.5rem 0 1rem; }
+.diff-legend span { padding: 0.1rem 0.4rem; border-radius: 3px; margin-right: 0.5rem; }
+@media (prefers-color-scheme: dark) {
+  .diff_add { background: #14532d; } .diff_sub { background: #5b1a1a; }
+  .diff_chg { background: #5c4d00; } .diff_next, .diff_header { color: #aaa; }
+}
+"""
+
+
+def body_fragment(html: str) -> str:
+    """Extract the inner ``<body>`` markup from a full HTML document."""
+    from bs4 import BeautifulSoup
+
+    soup = BeautifulSoup(html, "html.parser")
+    body = soup.body
+    return body.decode_contents() if body else soup.decode_contents()
+
+
+def plain_text_lines(html: str) -> list[str]:
+    """Extract visible text from an HTML document as a list of lines."""
+    from bs4 import BeautifulSoup
+
+    soup = BeautifulSoup(html, "html.parser")
+    for tag in soup(["script", "style"]):
+        tag.decompose()
+    text = soup.get_text("\n")
+    return [line.rstrip() for line in text.splitlines() if line.strip()]
+
+
+def build_merged_html(
+    items: list[tuple[str, str]],
+    *,
+    title: str | None = None,
+    layout: str = "stacked",
+    include_toc: bool = True,
+) -> str:
+    """Combine ``(label, body_fragment)`` pairs into one HTML document.
+
+    ``layout="stacked"`` renders documents top-to-bottom with an optional table of
+    contents; ``layout="columns"`` places them side by side for visual comparison.
+    """
+    doc_title = title or "Merged document"
+
+    if layout == "columns":
+        cols = "".join(
+            f'<section class="merge-col"><h2 class="merge-title">{escape_text(label)}</h2>'
+            f"{body}</section>"
+            for label, body in items
+        )
+        body_html = f'<div class="merge-columns">{cols}</div>'
+        return wrap_document(
+            body_html,
+            title=doc_title,
+            extra_head=f"<style>{_MERGE_STYLE}</style>\n",
+        )
+
+    parts: list[str] = []
+    if include_toc and len(items) > 1:
+        links = "".join(
+            f'<li><a href="#doc-{i}">{escape_text(label)}</a></li>'
+            for i, (label, _) in enumerate(items, start=1)
+        )
+        parts.append(f'<nav class="merge-toc"><strong>Contents</strong><ol>{links}</ol></nav>')
+
+    for i, (label, body) in enumerate(items, start=1):
+        parts.append(
+            f'<section class="merge-doc" id="doc-{i}">'
+            f'<h2 class="merge-title">{escape_text(label)}</h2>{body}</section>'
+        )
+
+    return wrap_document(
+        "\n".join(parts),
+        title=doc_title,
+        extra_head=f"<style>{_MERGE_STYLE}</style>\n",
+    )
+
+
+def build_diff_html(
+    left_label: str,
+    left_lines: list[str],
+    right_label: str,
+    right_lines: list[str],
+    *,
+    title: str | None = None,
+    context: bool = True,
+    numlines: int = 3,
+) -> str:
+    """Render a side-by-side line diff of two documents' text content."""
+    differ = difflib.HtmlDiff(wrapcolumn=72)
+    table = differ.make_table(
+        left_lines,
+        right_lines,
+        fromdesc=escape_attr(left_label),
+        todesc=escape_attr(right_label),
+        context=context,
+        numlines=numlines,
+    )
+    legend = (
+        '<p class="diff-legend">'
+        '<span class="diff_add">added</span>'
+        '<span class="diff_chg">changed</span>'
+        '<span class="diff_sub">removed</span></p>'
+    )
+    body = f"<h1>{escape_text(title or 'Document comparison')}</h1>{legend}{table}"
+    return wrap_document(
+        body,
+        title=title or "Document comparison",
+        extra_head=f"<style>{_DIFF_STYLE}</style>\n",
+    )

everythingtohtml/_stream_info.py

@@ -0,0 +1,46 @@
+"""Carries everything we know about an input stream as it flows through converters."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, replace
+
+__all__ = ["StreamInfo"]
+
+
+@dataclass(frozen=True, kw_only=True)
+class StreamInfo:
+    """Immutable bag of hints describing a binary stream.
+
+    Every field is optional. Converters use whichever signals are available
+    (extension, mimetype, magic bytes, declared charset) to decide whether they
+    can handle the stream. Because it is frozen, passing it between converters is
+    safe; use :meth:`copy_and_update` to derive a refined copy.
+    """
+
+    mimetype: str | None = None
+    extension: str | None = None
+    charset: str | None = None
+    filename: str | None = None
+    local_path: str | None = None
+    url: str | None = None
+
+    def copy_and_update(self, *args: StreamInfo | None, **kwargs: object) -> StreamInfo:
+        """Return a new ``StreamInfo`` with non-``None`` values layered on top.
+
+        Accepts other ``StreamInfo`` instances (applied in order) and/or keyword
+        overrides. ``None`` values never overwrite an existing value.
+        """
+        updates: dict[str, object] = {}
+        for arg in args:
+            if arg is None:
+                continue
+            updates.update({k: v for k, v in asdict(arg).items() if v is not None})
+        updates.update({k: v for k, v in kwargs.items() if v is not None})
+        return replace(self, **updates)  # type: ignore[arg-type]
+
+    def normalized_extension(self) -> str | None:
+        """Lower-cased extension with a leading dot, or ``None``."""
+        if not self.extension:
+            return None
+        ext = self.extension.lower()
+        return ext if ext.startswith(".") else f".{ext}"

everythingtohtml/_text_utils.py

@@ -0,0 +1,46 @@
+"""Robust byte-stream-to-``str`` decoding shared by text-based converters."""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+from ._stream_info import StreamInfo
+
+__all__ = ["read_text"]
+
+
+def read_text(file_stream: BinaryIO, stream_info: StreamInfo) -> str:
+    """Decode a binary stream to text.
+
+    Order of preference:
+
+    1. The charset declared on ``stream_info`` (e.g. parsed from an HTTP header).
+    2. UTF-8, which is correct the overwhelming majority of the time.
+    3. ``charset_normalizer``'s best guess for legacy encodings.
+    4. UTF-8 with replacement as a last resort so we never hard-fail.
+    """
+    raw = file_stream.read()
+    if isinstance(raw, str):  # already-decoded stream
+        return raw
+
+    if stream_info.charset:
+        try:
+            return raw.decode(stream_info.charset)
+        except (LookupError, UnicodeDecodeError):
+            pass
+
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        pass
+
+    try:
+        from charset_normalizer import from_bytes
+
+        best = from_bytes(raw).best()
+        if best is not None:
+            return str(best)
+    except Exception:  # pragma: no cover - defensive, charset_normalizer is a dep
+        pass
+
+    return raw.decode("utf-8", errors="replace")

everythingtohtml/converters/__init__.py

@@ -0,0 +1,45 @@
+"""Built-in converters bundled with everythingtohtml.
+
+Each converter is a small, self-contained class implementing the
+:class:`~everythingtohtml._base_converter.DocumentConverter` contract.
+"""
+
+from __future__ import annotations
+
+from ._csv_converter import CsvConverter
+from ._doc_converter import DocConverter
+from ._docx_converter import DocxConverter
+from ._eml_converter import EmlConverter
+from ._epub_converter import EpubConverter
+from ._html_converter import HtmlConverter
+from ._ipynb_converter import IpynbConverter
+from ._json_converter import JsonConverter
+from ._markdown_converter import MarkdownConverter
+from ._odt_converter import OdtConverter
+from ._pdf_converter import PdfConverter
+from ._plain_text_converter import PlainTextConverter
+from ._pptx_converter import PptxConverter
+from ._rss_converter import RssConverter
+from ._rst_converter import RstConverter
+from ._xlsx_converter import XlsxConverter
+from ._yaml_converter import YamlConverter
+
+__all__ = [
+    "CsvConverter",
+    "DocConverter",
+    "DocxConverter",
+    "EmlConverter",
+    "EpubConverter",
+    "HtmlConverter",
+    "IpynbConverter",
+    "JsonConverter",
+    "MarkdownConverter",
+    "OdtConverter",
+    "PdfConverter",
+    "PlainTextConverter",
+    "PptxConverter",
+    "RssConverter",
+    "RstConverter",
+    "XlsxConverter",
+    "YamlConverter",
+]

everythingtohtml/converters/_csv_converter.py

@@ -0,0 +1,73 @@
+"""CSV/TSV -> HTML ``<table>`` using the stdlib csv module with dialect sniffing."""
+
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any, BinaryIO
+
+from .._base_converter import DocumentConverter, DocumentConverterResult
+from .._html_builder import escape_text, wrap_document
+from .._stream_info import StreamInfo
+from .._text_utils import read_text
+
+__all__ = ["CsvConverter"]
+
+_ACCEPTED_EXTENSIONS = {".csv", ".tsv"}
+_ACCEPTED_MIME_TYPES = {"text/csv", "text/tab-separated-values", "application/csv"}
+
+
+class CsvConverter(DocumentConverter):
+    """Render delimited data as an HTML table, treating the first row as headers."""
+
+    priority = DocumentConverter.PRIORITY_SPECIFIC_FILE_FORMAT
+
+    def accepts(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> bool:
+        ext = stream_info.normalized_extension()
+        mimetype = (stream_info.mimetype or "").split(";", 1)[0].strip().lower()
+        return ext in _ACCEPTED_EXTENSIONS or mimetype in _ACCEPTED_MIME_TYPES
+
+    def convert(
+        self,
+        file_stream: BinaryIO,
+        stream_info: StreamInfo,
+        **kwargs: Any,
+    ) -> DocumentConverterResult:
+        text = read_text(file_stream, stream_info)
+        ext = stream_info.normalized_extension()
+
+        delimiter = "\t" if ext == ".tsv" else None
+        if delimiter is None:
+            try:
+                dialect = csv.Sniffer().sniff(text[:8192], delimiters=",;\t|")
+                delimiter = dialect.delimiter
+            except csv.Error:
+                delimiter = ","
+
+        reader = csv.reader(io.StringIO(text), delimiter=delimiter)
+        rows = [row for row in reader]
+
+        title = stream_info.filename
+        if not rows:
+            body = "<p><em>(empty file)</em></p>"
+            return DocumentConverterResult(wrap_document(body, title=title), title=title)
+
+        parts: list[str] = ["<table>"]
+        header, *data_rows = rows
+        parts.append("<thead><tr>")
+        parts.extend(f"<th>{escape_text(cell)}</th>" for cell in header)
+        parts.append("</tr></thead>")
+        parts.append("<tbody>")
+        for row in data_rows:
+            parts.append("<tr>")
+            parts.extend(f"<td>{escape_text(cell)}</td>" for cell in row)
+            parts.append("</tr>")
+        parts.append("</tbody></table>")
+
+        html = wrap_document("".join(parts), title=title)
+        return DocumentConverterResult(html, title=title)