odt2web 0.8.0__py3-none-any.whl

odt2web/__init__.py

@@ -0,0 +1,25 @@
+"""odt2web - Python library to convert ODT documents into HTML/CSS."""
+
+from __future__ import annotations
+
+from .convert import check, convert, convert_bytes
+from .extensibility import get_default_renderers, register_renderer, unregister_renderer
+from .model import Document, Metadata
+from .reader import InvalidOdtError, OdtPackage, read_odt_bytes, read_odt_file
+from .result import Asset, ConversionResult, Warning, WarningLevel
+
+__all__ = [
+    "convert",
+    "convert_bytes",
+    "check",
+    "ConversionResult",
+    "Asset",
+    "Metadata",
+    "Warning",
+    "WarningLevel",
+    "InvalidOdtError",
+    "register_renderer",
+    "unregister_renderer",
+]
+
+__version__ = "0.8.0"

odt2web/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

odt2web/assets.py

@@ -0,0 +1,82 @@
+"""Asset extraction."""
+
+
+from __future__ import annotations
+
+import posixpath
+
+from .model import Document, Image
+from .reader import OdtPackage
+from .result import Asset
+from .security import is_safe_relative_path
+
+_MEDIA_TYPE_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".bmp": "image/bmp",
+    ".webp": "image/webp",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+}
+
+
+def _guess_media_type(path: str) -> str | None:
+    ext = posixpath.splitext(path)[1].lower()
+    return _MEDIA_TYPE_BY_EXT.get(ext)
+
+
+def extract_assets(document: Document, package: OdtPackage, assets_dir: str = "assets") -> list[Asset]:
+
+    assets: list[Asset] = []
+    seen: dict[str, str] = {}  # original_path -> output_path (avoids duplicates)
+    counter = 1
+
+    def visit_images(nodes):
+        nonlocal counter
+        for node in nodes:
+            if isinstance(node, Image) and not node.linked:
+                original = node.src
+                if not original or not is_safe_relative_path(original):
+                    continue
+                if original not in package.resources:
+                    continue  # missing/invalid resource
+                if original in seen:
+                    node.src = seen[original]
+                    continue
+                ext = posixpath.splitext(original)[1] or ".bin"
+                output_name = f"image-{counter:03d}{ext}"
+                counter += 1
+                output_path = posixpath.join(assets_dir, output_name)
+                data = package.resources[original]
+                assets.append(
+                    Asset(
+                        original_path=original,
+                        output_path=output_path,
+                        data=data,
+                        media_type=_guess_media_type(original),
+                    )
+                )
+                seen[original] = output_path
+                node.src = output_path
+            children = getattr(node, "children", None)
+            if children:
+                visit_images(children)
+            items = getattr(node, "items", None)
+            if items:
+                for item in items:
+                    visit_images(item.children)
+            rows = getattr(node, "rows", None)
+            if rows:
+                for row in rows:
+                    for cell in row.cells:
+                        visit_images(cell.children)
+
+    for section in document.sections:
+        visit_images(section.children)
+    for note in document.notes.values():
+        visit_images(note.children)
+
+    return assets

odt2web/cli.py

@@ -0,0 +1,139 @@
+"""Command-line interface (spec section 15).
+
+    odt2web artigo.odt
+    odt2web artigo.odt -o dist/
+    odt2web artigo.odt --css
+    odt2web artigo.odt --assets assets/
+    odt2web artigo.odt --fragment
+    odt2web artigo.odt --config config.yaml
+    odt2web --check artigo.odt
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__, check, convert
+from .reader import InvalidOdtError
+from .result import WarningLevel
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="odt2web",
+        description="Converts OpenDocument Text (.odt) documents to HTML/CSS.",
+    )
+    parser.add_argument("input", help="Path to the .odt file")
+    parser.add_argument(
+        "-o", "--output-dir", dest="output_dir", default=None,
+        help="Output directory (saves index.html, style.css and assets/)",
+    )
+    parser.add_argument(
+        "--css", dest="css", action=argparse.BooleanOptionalAction, default=None,
+        help="Automatically generates CSS (default: enabled; use --no-css to disable)",
+    )
+    parser.add_argument(
+        "--extract-images", dest="extract_images", action=argparse.BooleanOptionalAction,
+        default=None, help="Extract embedded images (default: enabled)",
+    )
+    parser.add_argument(
+        "--assets", dest="assets_dir", default=None,
+        help="Subdirectory for extracted assets (default: assets)",
+    )
+    parser.add_argument(
+        "--allow-raw-html", dest="allow_raw_html", action=argparse.BooleanOptionalAction,
+        default=None,
+        help="Outputs ':::html' ... ':::' blocks as literal HTML, without escaping. "
+             "(default: disabled – only enable for documents from trusted authors)",
+    )
+    doc_group = parser.add_mutually_exclusive_group()
+    doc_group.add_argument(
+        "--fragment", dest="document", action="store_false", default=None,
+        help="Generates only the HTML fragment (without doctype/html/head/body); "
+             "without this option, a complete HTML document is generated by default.",
+    )
+    doc_group.add_argument(
+        "--document", dest="document", action="store_true", default=None,
+        help="Forces the generation of a complete HTML document (CLI default)",
+    )
+    parser.add_argument(
+        "--config", dest="config", default=None,
+        help="YAML configuration file",
+    )
+    parser.add_argument(
+        "--check", dest="check_only", action="store_true",
+        help="It only validates the document, without generating HTML.",
+    )
+    parser.add_argument(
+        "--html-filename", dest="html_filename", default="index.html",
+        help="Name of the generated HTML file within --output-dir (default: index.html)",
+    )
+    parser.add_argument(
+        "--css-filename", dest="css_filename", default="style.css",
+        help="Name of the generated CSS file within --output-dir (default: style.css)",
+    )
+    parser.add_argument("--version", action="version", version=f"odt2web {__version__}")
+    return parser
+
+
+def _print_warnings(warnings, *, file=sys.stderr) -> None:
+    for warning in warnings:
+        prefix = {
+            WarningLevel.INFO: "info",
+            WarningLevel.WARNING: "warning",
+            WarningLevel.ERROR: "error",
+        }.get(warning.level, "warning")
+        source = f" ({warning.source})" if warning.source else ""
+        print(f"[{prefix}]{source} {warning.message}", file=file)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.check_only:
+            warnings = check(args.input)
+            _print_warnings(warnings, file=sys.stdout)
+            errors = [w for w in warnings if w.level == WarningLevel.ERROR]
+            print(f"OK: {args.input} is a valid .odt document."
+                  f"({len(warnings)} warning(s))")
+            return 1 if errors else 0
+
+        kwargs: dict = {"output_dir": args.output_dir, "config": args.config}
+        if args.css is not None:
+            kwargs["css"] = args.css
+        if args.extract_images is not None:
+            kwargs["extract_images"] = args.extract_images
+        if args.assets_dir is not None:
+            kwargs["assets_dir"] = args.assets_dir
+        if args.allow_raw_html is not None:
+            kwargs["allow_raw_html"] = args.allow_raw_html
+        # unlike the API, the CLI generates a full document by default
+        # (more useful for standalone use); --fragment/--document override this.
+        kwargs["document"] = args.document if args.document is not None else True
+
+        result = convert(args.input, **kwargs)
+    except InvalidOdtError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    except FileNotFoundError:
+        print(f"Error: file not found: {args.input}", file=sys.stderr)
+        return 2
+
+    if args.output_dir:
+        result.write(args.output_dir, html_filename=args.html_filename,
+                      css_filename=args.css_filename)
+        print(f"Saved in {args.output_dir}/{args.html_filename}"
+              + (f" e {args.output_dir}/{args.css_filename}" if result.css else ""))
+    else:
+        sys.stdout.write(result.html)
+        if not result.html.endswith("\n"):
+            sys.stdout.write("\n")
+
+    _print_warnings(result.warnings)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

odt2web/codeblocks.py

@@ -0,0 +1,87 @@
+"""Code blocks. 
+"""
+from __future__ import annotations
+
+from .model import CodeBlock, LineBreak, Link, Paragraph, Section, Span, Text
+from .styles import resolve_style_mapping
+
+
+def _literal_text(nodes: list) -> str:
+    """Extracts the literal text of a paragraph, ignoring inline
+    formatting (bold/italic/links) but preserving manual line breaks as
+    '\\n' - used to avoid corrupting code."""
+    parts: list[str] = []
+    for node in nodes:
+        if isinstance(node, Text):
+            parts.append(node.value)
+        elif isinstance(node, (Span, Link)):
+            parts.append(_literal_text(node.children))
+        elif isinstance(node, LineBreak):
+            parts.append("\n")
+    return "".join(parts)
+
+
+def _strip_language_fence(lines: list[str]) -> tuple[str | None, list[str]]:
+    """If the first line is a Markdown-style marker ('```python'),
+    removes it and returns the indicated language."""
+    if lines and lines[0].strip().startswith("```"):
+        lang = lines[0].strip()[3:].strip()
+        return (lang or None), lines[1:]
+    return None, lines
+
+
+def _language_from_css_class(css_class: str | None) -> str | None:
+    if css_class and css_class.startswith("language-"):
+        return css_class[len("language-"):]
+    return None
+
+
+def _merge_children(children: list, style_map: dict) -> list:
+    result: list = []
+    i = 0
+    n = len(children)
+
+    while i < n:
+        node = children[i]
+
+        if isinstance(node, Paragraph):
+            mapping = resolve_style_mapping(node.style_candidates, style_map)
+            tag, attrs = mapping if mapping is not None else ("p", {})
+            if tag == "pre":
+                css_class = attrs.get("class")
+                j = i
+                paragraph_lines: list[str] = []
+                while j < n and isinstance(children[j], Paragraph):
+                    m2 = resolve_style_mapping(children[j].style_candidates, style_map)
+                    t2, a2 = m2 if m2 is not None else ("p", {})
+                    if t2 != "pre" or a2.get("class") != css_class:
+                        break
+                    paragraph_lines.append(_literal_text(children[j].children))
+                    j += 1
+
+                # each paragraph may contain multiple internal lines
+                # (manual line breaks); flatten everything into a list of
+                # lines before looking for the language marker.
+                lines: list[str] = []
+                for para_text in paragraph_lines:
+                    lines.extend(para_text.split("\n"))
+
+                fence_lang, lines = _strip_language_fence(lines)
+                language = fence_lang or _language_from_css_class(css_class)
+
+                result.append(CodeBlock(
+                    code="\n".join(lines), language=language, css_class=css_class,
+                ))
+                i = j
+                continue
+
+        result.append(node)
+        i += 1
+
+    return result
+
+
+def merge_code_blocks(sections: list[Section], style_map: dict) -> None:
+    
+    for section in sections:
+        section.children = _merge_children(section.children, style_map)

odt2web/config.py

@@ -0,0 +1,74 @@
+"""YAML-based configuration.
+
+Example of an accepted config file:
+
+    output:
+      document: false
+      css: true
+      assets: assets
+      allow_raw_html: false
+
+    columns:
+      enabled: true
+
+    styles:
+      Title: h1
+      Heading 1: h2
+      Heading 2: h3
+      Quotation: blockquote
+      Lead:
+        tag: p
+        class: lead
+"""
+from __future__ import annotations
+
+import yaml
+
+
+class ConfigError(Exception):
+    pass
+
+
+def load_config(path: str) -> dict:
+    with open(path, "r", encoding="utf-8") as fh:
+        try:
+            data = yaml.safe_load(fh)
+        except yaml.YAMLError as exc:
+            raise ConfigError(f"Error reading YAML config '{path}': {exc}") from exc
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(
+            f"YAML config '{path}' must have a mapping at the root "
+            f"(e.g. 'output:', 'styles:'), not {type(data).__name__}"
+        )
+    return data
+
+
+def config_to_options(data: dict) -> dict:
+    """Converts the YAML structure into a kwargs dict compatible with
+    the convert()/convert_bytes() signature."""
+    options: dict = {}
+
+    output = data.get("output") or {}
+    if "document" in output:
+        options["document"] = bool(output["document"])
+    if "css" in output:
+        options["css"] = bool(output["css"])
+    if "assets" in output:
+        options["assets_dir"] = str(output["assets"])
+    if "allow_raw_html" in output:
+        options["allow_raw_html"] = bool(output["allow_raw_html"])
+    if "extract_images" in output:
+        options["extract_images"] = bool(output["extract_images"])
+
+    columns = data.get("columns") or {}
+    if "enabled" in columns and not columns["enabled"]:
+        # disables column detection by forcing 1 column in every section
+        options["disable_columns"] = True
+
+    styles = data.get("styles")
+    if styles:
+        options["style_map"] = dict(styles)
+
+    return options

odt2web/convert.py

@@ -0,0 +1,186 @@
+"""High-level conversion pipeline."""
+
+
+from __future__ import annotations
+
+from .assets import extract_assets
+from .codeblocks import merge_code_blocks
+from .css import generate_css
+from .extensibility import get_default_renderers
+from .metadata import parse_metadata
+from .model import Document
+from .parser import parse_document
+from .reader import OdtPackage, read_odt_bytes, read_odt_file
+from .renderer import render_document, wrap_full_document
+from .result import ConversionResult, Warning, WarningLevel
+
+
+def _disable_columns(document: Document) -> None:
+    for section in document.sections:
+        section.columns = 1
+        section.column_gap = None
+        section.column_rule = None
+
+
+def _build_result(
+    package: OdtPackage,
+    *,
+    css: bool = True,
+    extract_images: bool = True,
+    assets_dir: str = "assets",
+    document: bool = False,
+    style_map: dict | None = None,
+    custom_renderers: dict | None = None,
+    disable_columns: bool = False,
+    allow_raw_html: bool = False,
+) -> ConversionResult:
+    doc_model = parse_document(package)
+    doc_model.metadata = parse_metadata(package.meta_xml, package.content_xml)
+
+    if disable_columns:
+        _disable_columns(doc_model)
+
+    merge_code_blocks(doc_model.sections, style_map or {})
+
+    if extract_images:
+        assets = extract_assets(doc_model, package, assets_dir=assets_dir)
+    else:
+        assets = []
+        doc_model.warnings.append(
+            "extract_images=False: images were not extracted; the "
+            "original paths from the ODT package were kept in the HTML "
+            "and may not resolve correctly"
+        )
+
+    renderers = get_default_renderers()
+    if custom_renderers:
+        renderers.update(custom_renderers)
+
+    body_html, render_ctx = render_document(
+        doc_model, style_map=style_map or {}, custom_renderers=renderers,
+        allow_raw_html=allow_raw_html,
+    )
+
+    css_text = generate_css(render_ctx) if css else None
+
+    if document:
+        html = wrap_full_document(body_html, css_text, doc_model.metadata)
+    else:
+        html = body_html
+
+    warnings = [Warning(message=w, level=WarningLevel.WARNING, source="parser")
+                for w in doc_model.warnings]
+    warnings += [Warning(message=w, level=WarningLevel.WARNING, source="renderer")
+                 for w in render_ctx.warnings]
+
+    return ConversionResult(
+        html=html,
+        css=css_text,
+        assets=assets,
+        metadata=doc_model.metadata,
+        front_matter=doc_model.front_matter,
+        warnings=warnings,
+    )
+
+
+# the library's "real" defaults, applied only after explicit arguments
+# and the YAML config have already been considered (lets the config
+# override the default when the caller doesn't pass the argument).
+_LIBRARY_DEFAULTS = dict(
+    css=True, extract_images=True, assets_dir="assets", document=False,
+    allow_raw_html=False,
+)
+
+
+def _merge_options(*, css, extract_images, assets_dir, document, style_map,
+                    custom_renderers, allow_raw_html, config) -> tuple[dict, bool]:
+    from .config import config_to_options, load_config
+
+    # only arguments the caller actually passed (different from the
+    # None sentinel) go into the dict; the rest is left to the
+    # config/defaults.
+    explicit = {
+        "css": css, "extract_images": extract_images, "assets_dir": assets_dir,
+        "document": document, "allow_raw_html": allow_raw_html,
+    }
+    options: dict = {k: v for k, v in explicit.items() if v is not None}
+    if style_map is not None:
+        options["style_map"] = style_map
+    if custom_renderers is not None:
+        options["custom_renderers"] = custom_renderers
+
+    disable_columns = False
+    if config:
+        file_options = config_to_options(load_config(config))
+        for key, value in file_options.items():
+            if key == "style_map":
+                merged = dict(value)
+                merged.update(style_map or {})
+                options["style_map"] = merged
+            elif key == "disable_columns":
+                disable_columns = value
+            elif key not in options:
+                options[key] = value
+
+    for key, default in _LIBRARY_DEFAULTS.items():
+        options.setdefault(key, default)
+
+    return options, disable_columns
+
+
+def convert(
+    path: str,
+    *,
+    output_dir: str | None = None,
+    css: bool | None = None,
+    extract_images: bool | None = None,
+    assets_dir: str | None = None,
+    document: bool | None = None,
+    style_map: dict | None = None,
+    custom_renderers: dict | None = None,
+    allow_raw_html: bool | None = None,
+    config: str | None = None,
+) -> ConversionResult:
+    """Converts an .odt file into HTML/CSS."""
+
+    options, disable_columns = _merge_options(
+        css=css, extract_images=extract_images, assets_dir=assets_dir,
+        document=document, style_map=style_map, custom_renderers=custom_renderers,
+        allow_raw_html=allow_raw_html, config=config,
+    )
+    package = read_odt_file(path)
+    result = _build_result(package, disable_columns=disable_columns, **options)
+    if output_dir:
+        result.write(output_dir)
+    return result
+
+
+def convert_bytes(
+    data: bytes,
+    *,
+    css: bool | None = None,
+    extract_images: bool | None = None,
+    assets_dir: str | None = None,
+    document: bool | None = None,
+    style_map: dict | None = None,
+    custom_renderers: dict | None = None,
+    allow_raw_html: bool | None = None,
+    config: str | None = None,
+) -> ConversionResult:
+    """Same as convert(), but from in-memory bytes (section 2)."""
+    options, disable_columns = _merge_options(
+        css=css, extract_images=extract_images, assets_dir=assets_dir,
+        document=document, style_map=style_map, custom_renderers=custom_renderers,
+        allow_raw_html=allow_raw_html, config=config,
+    )
+    package = read_odt_bytes(data)
+    return _build_result(package, disable_columns=disable_columns, **options)
+
+
+def check(path: str) -> list[Warning]:
+    """Validates an .odt document without generating HTML."""
+
+    package = read_odt_file(path)
+    doc_model = parse_document(package)
+    return [Warning(message=w, level=WarningLevel.WARNING, source="parser")
+            for w in doc_model.warnings]