svg-ultralight 0.47.0__py3-none-any.whl → 0.50.1__py3-none-any.whl

svg_ultralight/read_svg.py

@@ -0,0 +1,58 @@
+"""Read SVG file and extract text content.
+
+Note about svg resolution: Despite the fact that vector graphics have effectively
+infinite resolution, ePub apparently uses the actual geometry size to determine the
+resolution of the image. For images ike a business card drawn in real-world inches
+(3.5" width), an ePub will assume a size of 3.5 pixels. There may be some unit for
+the width and height variables (for InDesign, it's pnt) that addresses this, but I
+don't trust it to be consistent across ePub readers. I adjust the units to something
+large, then use CSS to scale it down to the correct size.
+
+:author: Shay Hill
+:created: 2025-07-28
+"""
+
+import os
+from pathlib import Path
+
+from lxml import etree
+from lxml.etree import _Element as EtreeElement  # pyright: ignore[reportPrivateUsage]
+
+import svg_ultralight as su
+
+
+def get_bounding_box_from_root(root: EtreeElement) -> su.BoundingBox:
+    """Extract bounding box from SVG root element.
+
+    :param root: the root element of the SVG file
+    :raise ValueError: if the viewBox attribute is not present
+
+    """
+    viewbox = root.get("viewBox", "")
+    try:
+        x, y, width, height = map(float, viewbox.split())
+    except ValueError as e:
+        msg = f"Invalid or missing viewBox attribute: '{viewbox}'"
+        raise ValueError(msg) from e
+    return su.BoundingBox(x, y, width, height)
+
+
+def parse(svg_file: str | os.PathLike[str]) -> su.BoundElement:
+    """Import an SVG file and return an SVG object.
+
+    :param svg_file: Path to the SVG file.
+    :return: A BoundElement containing the SVG content and the svg viewBox as a
+        BoundingBox.
+
+    Near equivalent to `etree.parse(file).getroot()`, but returns a BoundElement
+    instance. This will only work with SVG files that have a viewBox attribute.
+    """
+    with Path(svg_file).open("r", encoding="utf-8") as f:
+        root = etree.parse(f).getroot()
+    if len(root) == 1:
+        elem = root[0]
+    else:
+        elem = su.new_element("g")
+        elem.extend(list(root))
+    bbox = get_bounding_box_from_root(root)
+    return su.BoundElement(elem, bbox)

svg_ultralight/root_elements.py

@@ -1,87 +1,87 @@
-"""Build root elements in various ways.
-
-:author: Shay Hill
-:created: 2023-09-23
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from svg_ultralight.bounding_boxes import bound_helpers as bound
-from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
-from svg_ultralight.main import new_svg_root
-
-if TYPE_CHECKING:
-    from lxml.etree import (
-        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
-    )
-
-    from svg_ultralight.attrib_hints import ElemAttrib, OptionalElemAttribMapping
-    from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
-    from svg_ultralight.layout import PadArg
-
-
-def _viewbox_args_from_bboxes(*bboxes: BoundingBox) -> dict[str, float]:
-    """Create x_, y_, width_, height_ new_svg_root arguments from bounding boxes.
-
-    :param bbox: bounding boxes to merge
-    :return: dict of new_svg_root arguments
-    """
-    merged = BoundingBox.merged(*bboxes)
-    return {
-        "x_": merged.x,
-        "y_": merged.y,
-        "width_": merged.width,
-        "height_": merged.height,
-    }
-
-
-def new_svg_root_around_bounds(
-    *bounded: SupportsBounds | EtreeElement,
-    pad_: PadArg = 0,
-    print_width_: float | str | None = None,
-    print_height_: float | str | None = None,
-    dpu_: float = 1,
-    nsmap: dict[str | None, str] | None = None,
-    attrib: OptionalElemAttribMapping = None,
-    **attributes: ElemAttrib,
-) -> EtreeElement:
-    """Create svg root around BoundElements.
-
-    :param bounded: BoundingBox istances, BoundElement instances, PaddedText
-        instances, or any other EtreeElement instances. Anything that isn't a
-        bounding box or SupportsBounds will be ignored.
-    :param pad_: optionally increase viewBox by pad in all directions. Acceps a
-        single value or a tuple of values applied to (cycled over) top, right,
-        bottom, left. pad can be floats or dimension strings*
-    :param print_width_: optionally explicitly set unpadded width in units
-        (float) or a dimension string*
-    :param print_height_: optionally explicitly set unpadded height in units
-        (float) or a dimension string*
-    :param dpu_: dots per unit. Scale the output by this factor. This is
-        different from print_width_ and print_height_ in that dpu_ scales the
-        *padded* output.
-    :param nsmap: optionally pass a namespace map of your choosing
-    :param attrib: optionally pass additional attributes as a mapping instead of as
-        anonymous kwargs. This is useful for pleasing the linter when unpacking a
-        dictionary into a function call.
-    :param attributes: element attribute names and values
-    :return: root svg element
-    :raise ValueError: if no bounding boxes are found in bounded
-    """
-    attributes.update(attrib or {})
-    bbox = bound.new_bbox_union(*bounded)
-    viewbox = _viewbox_args_from_bboxes(bbox)
-    return new_svg_root(
-        x_=viewbox["x_"],
-        y_=viewbox["y_"],
-        width_=viewbox["width_"],
-        height_=viewbox["height_"],
-        pad_=pad_,
-        print_width_=print_width_,
-        print_height_=print_height_,
-        dpu_=dpu_,
-        nsmap=nsmap,
-        attrib=attributes,
-    )
+"""Build root elements in various ways.
+
+:author: Shay Hill
+:created: 2023-09-23
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from svg_ultralight.bounding_boxes import bound_helpers as bound
+from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
+from svg_ultralight.main import new_svg_root
+
+if TYPE_CHECKING:
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
+
+    from svg_ultralight.attrib_hints import ElemAttrib, OptionalElemAttribMapping
+    from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
+    from svg_ultralight.layout import PadArg
+
+
+def _viewbox_args_from_bboxes(*bboxes: BoundingBox) -> dict[str, float]:
+    """Create x_, y_, width_, height_ new_svg_root arguments from bounding boxes.
+
+    :param bbox: bounding boxes to merge
+    :return: dict of new_svg_root arguments
+    """
+    merged = BoundingBox.merged(*bboxes)
+    return {
+        "x_": merged.x,
+        "y_": merged.y,
+        "width_": merged.width,
+        "height_": merged.height,
+    }
+
+
+def new_svg_root_around_bounds(
+    *bounded: SupportsBounds | EtreeElement,
+    pad_: PadArg = 0,
+    print_width_: float | str | None = None,
+    print_height_: float | str | None = None,
+    dpu_: float = 1,
+    nsmap: dict[str | None, str] | None = None,
+    attrib: OptionalElemAttribMapping = None,
+    **attributes: ElemAttrib,
+) -> EtreeElement:
+    """Create svg root around BoundElements.
+
+    :param bounded: BoundingBox istances, BoundElement instances, PaddedText
+        instances, or any other EtreeElement instances. Anything that isn't a
+        bounding box or SupportsBounds will be ignored.
+    :param pad_: optionally increase viewBox by pad in all directions. Acceps a
+        single value or a tuple of values applied to (cycled over) top, right,
+        bottom, left. pad can be floats or dimension strings*
+    :param print_width_: optionally explicitly set unpadded width in units
+        (float) or a dimension string*
+    :param print_height_: optionally explicitly set unpadded height in units
+        (float) or a dimension string*
+    :param dpu_: dots per unit. Scale the output by this factor. This is
+        different from print_width_ and print_height_ in that dpu_ scales the
+        *padded* output.
+    :param nsmap: optionally pass a namespace map of your choosing
+    :param attrib: optionally pass additional attributes as a mapping instead of as
+        anonymous kwargs. This is useful for pleasing the linter when unpacking a
+        dictionary into a function call.
+    :param attributes: element attribute names and values
+    :return: root svg element
+    :raise ValueError: if no bounding boxes are found in bounded
+    """
+    attributes.update(attrib or {})
+    bbox = bound.new_bbox_union(*bounded)
+    viewbox = _viewbox_args_from_bboxes(bbox)
+    return new_svg_root(
+        x_=viewbox["x_"],
+        y_=viewbox["y_"],
+        width_=viewbox["width_"],
+        height_=viewbox["height_"],
+        pad_=pad_,
+        print_width_=print_width_,
+        print_height_=print_height_,
+        dpu_=dpu_,
+        nsmap=nsmap,
+        attrib=attributes,
+    )