svg-ultralight 0.64.0__py3-none-any.whl → 0.73.1__py3-none-any.whl

svg_ultralight/font_tools/font_info.py

@@ -36,10 +36,7 @@ installed on my system.
 - 7 of 389 have y-bounds differences from Pango, but the line_gap values may still be
   useful.
 
-- 4 of 389 have x-bounds differences from Pango. A hybrid function `pad_text_mix`
-  uses the x-bounds from Inkscape/Pango and the y-bounds from this module. The 11
-  total mismatched font bounds appear to all be from fonts with liguatures, which I
-  have not implemented.
+- 4 of 389 have x-bounds differences from Pango.
 
 I have provided the `check_font_tools_alignment` function to check an existing font
 for compatilibilty with Inkscape's text layout. If that returns (NO_ERROR, None),
@@ -76,7 +73,7 @@ Disadvantages:
   test to see how well your bounding boxes fit if you're using an unfamiliar font.
 
 - does not support `font-variant`, `font-kerning`, `text-anchor`, and other
-  attributes that `pad_text` would through Inkscape.
+  attributes that `pad_text_inkscape` would through Inkscape.
 
 See the padded_text_initializers module for how to create a PaddedText instance using
 fontTools and this module.
@@ -98,6 +95,7 @@ from __future__ import annotations
 import functools as ft
 import itertools as it
 import logging
+import weakref
 from contextlib import suppress
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
@@ -107,13 +105,10 @@ from fontTools.pens.boundsPen import BoundsPen
 from fontTools.ttLib import TTFont
 from paragraphs import par
 from svg_path_data import format_svgd_shortest, get_cpts_from_svgd, get_svgd_from_cpts
+from typing_extensions import Self
 
 from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
-from svg_ultralight.constructors.new_element import (
-    new_element,
-    new_sub_element,
-    update_element,
-)
+from svg_ultralight.constructors.new_element import new_element, new_sub_element
 from svg_ultralight.strings import svg_matrix
 
 if TYPE_CHECKING:
@@ -127,7 +122,7 @@ if TYPE_CHECKING:
 logging.getLogger("fontTools").setLevel(logging.ERROR)
 
 
-_ESCAPE_CHARS = {
+DATA_TEXT_ESCAPE_CHARS = {
     "&": "&",
     "<": "&lt;",
     ">": "&gt;",
@@ -144,7 +139,7 @@ def _sanitize_svg_data_text(text: str) -> str:
     :param text: The input string to sanitize.
     :return: The sanitized string with XML characters escaped.
     """
-    for char, escape_seq in _ESCAPE_CHARS.items():
+    for char, escape_seq in DATA_TEXT_ESCAPE_CHARS.items():
         text = text.replace(char, escape_seq)
     return text
 
@@ -289,14 +284,46 @@ class PathPen(BasePen):
 class FTFontInfo:
     """Hide all the type kludging necessary to use fontTools."""
 
-    def __init__(self, font_path: str | os.PathLike[str]) -> None:
+    def __new__(cls, font: str | os.PathLike[str] | Self) -> Self:
+        """Create a new FTFontInfo instance as a context manager."""
+        if isinstance(font, FTFontInfo):
+            return font
+        instance = super().__new__(cls)
+        _ = weakref.finalize(instance, instance.__close__)
+        return instance
+
+    def __init__(self, font: str | os.PathLike[str] | Self) -> None:
         """Initialize the SUFont with a path to a TTF font file."""
-        self._path = Path(font_path)
+        if self is font:
+            return
+        if isinstance(font, FTFontInfo):
+            msg = "Unexpected Error, should have been caught in __new__."
+            raise TypeError(msg)
+        self._ttfont_local_to_instance = True
+        self._path = Path(font)
         if not self.path.exists():
             msg = f"Font file '{self.path}' does not exist."
             raise FileNotFoundError(msg)
         self._font = TTFont(self.path)
 
+    def __close__(self) -> None:
+        """Close the font file."""
+        self._font.close()
+
+    def maybe_close(self) -> None:
+        """Close the TTFont instance if it is was opened by this instance."""
+        if self._ttfont_local_to_instance:
+            self.__close__()
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        """Exit the context manager."""
+        del exc_type, exc_value, traceback
+        self.maybe_close()
+
     @property
     def path(self) -> Path:
         """Return the path to the font file."""
@@ -367,6 +394,64 @@ class FTFontInfo:
             msg = f"Font '{self.path}' does not have a 'hhea' table: {e}"
             raise ValueError(msg) from e
 
+    @property
+    def ascent(self) -> int:
+        """Get the ascent for the font.
+
+        :return: The ascent for the font.
+        """
+        with suppress(KeyError, AttributeError):
+            return self.font["os2"].sTypoAscender
+        with suppress(KeyError, AttributeError):
+            return self.font["hhea"].ascent
+        msg = f"Failed to find ascent for font '{self.path}'."
+        raise AttributeError(msg)
+
+    @property
+    def descent(self) -> int:
+        """Get the descent for the font.
+
+        :return: The descent for the font.
+        """
+        with suppress(KeyError, AttributeError):
+            return self.font["os2"].sTypoDescender
+        with suppress(KeyError, AttributeError):
+            return self.font["hhea"].descent
+        msg = f"Failed to find descent for font '{self.path}'."
+        raise AttributeError(msg)
+
+    @property
+    def line_gap(self) -> int:
+        """Get the cap height for the font.
+
+        :return: The (often 0) line gap for the font.
+        """
+        with suppress(KeyError, AttributeError):
+            return self.font["os2"].sTypoLineGap
+        with suppress(KeyError, AttributeError):
+            return self.font["hhea"].lineGap
+        return 0
+
+    @property
+    def cap_height(self) -> int:
+        """Get the cap height for the font.
+
+        :return: The cap height for the font.
+        """
+        with suppress(KeyError, AttributeError):
+            return self.font["os2"].sCapHeight
+        return self.get_char_bounds("H")[3]
+
+    @property
+    def x_height(self) -> int:
+        """Get the x-height for the font.
+
+        :return: The x-height for the font.
+        """
+        with suppress(KeyError, AttributeError):
+            return self.font["os2"].sxHeight  # rare
+        return self.get_char_bounds("x")[3]
+
     def get_glyph_name(self, char: str) -> str:
         """Get the glyph name for a character in the font.
 
@@ -544,15 +629,25 @@ class FTTextInfo:
         descent: float | None = None,
     ) -> None:
         """Initialize the SUText with text, a SUFont instance, and font size."""
-        if isinstance(font, FTFontInfo):
-            self._font = font
-        else:
-            self._font = FTFontInfo(font)
-        self._text = text.rstrip(" ")
+        self._font = FTFontInfo(font)
+        self._text = text
         self._font_size = font_size or self._font.units_per_em
         self._ascent = ascent
         self._descent = descent
 
+    def __close__(self) -> None:
+        """Close the font file."""
+        self._font.maybe_close()
+
+    def __enter__(self) -> Self:
+        """Enter the context manager."""
+        return self
+
+    def __exit__(self, exc_type: object, exc_value: object, traceback: object) -> None:
+        """Exit the context manager."""
+        del exc_type, exc_value, traceback
+        self.__close__()
+
     @property
     def font(self) -> FTFontInfo:
         """Return the font information."""
@@ -597,21 +692,6 @@ class FTTextInfo:
             )
         return group
 
-    def new_chars_group_element(self, **attributes: ElemAttrib) -> EtreeElement:
-        """Return an svg group element with a path for each character in the text."""
-        names = map(self.font.get_glyph_name, self.text)
-        svgds = self.font.get_text_svgd_by_char(self.text)
-        group = new_element("g", **attributes)
-        for name, svgd in zip(names, svgds, strict=True):
-            data_text = _sanitize_svg_data_text(name)
-            _ = new_sub_element(group, "path", data_text=data_text, d=svgd)
-        matrix_vals = (self.scale, 0, 0, -self.scale, 0, 0)
-        group.attrib["transform"] = svg_matrix(matrix_vals)
-        stroke_width = group.attrib.get("stroke-width")
-        if stroke_width:
-            _ = update_element(group, stroke_width=float(stroke_width) / self.scale)
-        return group
-
     @property
     def bbox(self) -> BoundingBox:
         """Return the bounding box of the text.
@@ -717,8 +797,9 @@ def get_padded_text_info(
     :param y_bounds_reference: optional character or string to use as a reference
         for the ascent and descent. If provided, the ascent and descent will be the y
         extents of the capline reference. This argument is provided to mimic the
-        behavior of the query module's `pad_text` function. `pad_text` does no
-        inspect font files and relies on Inkscape to measure reference characters.
+        behavior of the query module's `pad_text_inkscape` function.
+        `pad_text_inkscape` does not inspect font files and relies on Inkscape to
+        measure reference characters.
     :return: A FTTextInfo object with the information necessary to create a
         PaddedText instance: bbox, tpad, rpad, bpad, lpad.
     """

svg_ultralight/layout.py

@@ -6,13 +6,36 @@
 
 from __future__ import annotations
 
-from collections.abc import Sequence
-from typing import TypeAlias
+from typing import TypeAlias, cast
 
 from svg_ultralight.string_conversion import format_number
-from svg_ultralight.unit_conversion import Measurement, MeasurementArg
+from svg_ultralight.unit_conversion import (
+    Measurement,
+    MeasurementArg,
+    is_measurement_arg,
+)
 
-PadArg: TypeAlias = float | str | Measurement | Sequence[float | str | Measurement]
+_MeasurementArgs: TypeAlias = (
+    tuple[MeasurementArg]
+    | tuple[MeasurementArg, MeasurementArg]
+    | tuple[MeasurementArg, MeasurementArg, MeasurementArg]
+    | tuple[MeasurementArg, MeasurementArg, MeasurementArg, MeasurementArg]
+)
+
+PadArg: TypeAlias = MeasurementArg | _MeasurementArgs
+
+
+def _expand_pad_args(pad: _MeasurementArgs) -> tuple[float, float, float, float]:
+    """Transform a tuple of MeasurementArgs to a 4-tuple of user units."""
+    as_ms = (m if isinstance(m, Measurement) else Measurement(m) for m in pad)
+    as_units = [m.value for m in as_ms]
+    if len(as_units) == 1:
+        as_units = as_units * 4
+    elif len(as_units) == 2:
+        as_units = as_units * 2
+    elif len(as_units) == 3:
+        as_units = [*as_units, as_units[1]]
+    return as_units[0], as_units[1], as_units[2], as_units[3]
 
 
 def expand_pad_arg(pad: PadArg) -> tuple[float, float, float, float]:
@@ -39,15 +62,11 @@ def expand_pad_arg(pad: PadArg) -> tuple[float, float, float, float]:
     >>> expand_pad_arg((Measurement("1in"), Measurement("2in")))
     (96.0, 192.0, 96.0, 192.0)
     """
-    if isinstance(pad, str) or not isinstance(pad, Sequence):
-        return expand_pad_arg([pad])
-    as_ms = [m if isinstance(m, Measurement) else Measurement(m) for m in pad]
-    as_units = [m.value for m in as_ms]
-    if len(as_units) == 3:
-        as_units = [*as_units, as_units[1]]
-    else:
-        as_units = [as_units[i % len(as_units)] for i in range(4)]
-    return as_units[0], as_units[1], as_units[2], as_units[3]
+    if is_measurement_arg(pad):
+        pads = cast("_MeasurementArgs", (pad,))
+        return _expand_pad_args(pads)
+    pads = cast("_MeasurementArgs", pad)
+    return _expand_pad_args(pads)
 
 
 def pad_viewbox(
@@ -136,7 +155,7 @@ def _infer_scale(
 
 def pad_and_scale(
     viewbox: tuple[float, float, float, float],
-    pad: PadArg,
+    pad: PadArg = 0,
     print_width: MeasurementArg | None = None,
     print_height: MeasurementArg | None = None,
     dpu: float = 1,
@@ -222,10 +241,10 @@ def pad_and_scale(
       so there is no additional information supplied by giving both, but I've
       had unexpected behavior from pandoc when one was missing.
 
-    * If only a unit is given, (e.g., "pt"), the user units (viewbox width and
-      height) will be interpreted as that unit. This is important for InDesign,
-      which may not display in image at all if the width and height are not
-      explicitly "pt".
+    * If only a unit is given, (e.g., Unit.PT), the user units (viewbox width and
+      height) will be interpreted as that unit. This is important for InDesign, which
+      may not display an image at all if the width and height are not explicitly
+      "pt".
 
     * Print ratios are discarded. The viwebox ratio is preserved. For instance,
       if the viewbox is (0, 0, 16, 9), giving a 16:9 aspect ratio and the

svg_ultralight/main.py

@@ -19,9 +19,10 @@ from typing import IO, TYPE_CHECKING, TypeGuard
 from lxml import etree
 
 from svg_ultralight.constructors import update_element
-from svg_ultralight.layout import pad_and_scale
+from svg_ultralight.layout import PadArg, pad_and_scale
 from svg_ultralight.nsmap import NSMAP
 from svg_ultralight.string_conversion import get_view_box_str, svg_tostring
+from svg_ultralight.unit_conversion import MeasurementArg, to_svg_str, to_user_units
 
 if TYPE_CHECKING:
     import os
@@ -31,7 +32,6 @@ if TYPE_CHECKING:
     )
 
     from svg_ultralight.attrib_hints import ElemAttrib, OptionalElemAttribMapping
-    from svg_ultralight.layout import PadArg
 
 
 def _is_io_bytes(obj: object) -> TypeGuard[IO[bytes]]:
@@ -44,15 +44,15 @@ def _is_io_bytes(obj: object) -> TypeGuard[IO[bytes]]:
 
 
 def new_svg_root(
-    x_: float | None = None,
-    y_: float | None = None,
-    width_: float | None = None,
-    height_: float | None = None,
+    x_: MeasurementArg | None = None,
+    y_: MeasurementArg | None = None,
+    width_: MeasurementArg | None = None,
+    height_: MeasurementArg | None = None,
     *,
     pad_: PadArg = 0,
-    print_width_: float | str | None = None,
-    print_height_: float | str | None = None,
-    dpu_: float = 1,
+    print_width_: MeasurementArg | None = None,
+    print_height_: MeasurementArg | None = None,
+    dpu_: float | None = None,
     nsmap: dict[str | None, str] | None = None,
     attrib: OptionalElemAttribMapping | None = None,
     **attributes: ElemAttrib,
@@ -92,17 +92,27 @@ def new_svg_root(
         nsmap = NSMAP
 
     inferred_attribs: dict[str, ElemAttrib] = {}
-    if (
-        isinstance(x_, (float, int))
-        and isinstance(y_, (float, int))
-        and isinstance(width_, (float, int))
-        and isinstance(height_, (float, int))
-    ):
+    if x_ is not None and y_ is not None and width_ is not None and height_ is not None:
+        dpu = dpu_ or 1
+        x_, y_, width_, height_ = map(to_user_units, (x_, y_, width_, height_))
         padded_viewbox, scale_attribs = pad_and_scale(
-            (x_, y_, width_, height_), pad_, print_width_, print_height_, dpu_
+            (x_, y_, width_, height_), pad_, print_width_, print_height_, dpu
         )
         inferred_attribs["viewBox"] = get_view_box_str(*padded_viewbox)
         inferred_attribs.update(scale_attribs)
+    elif (
+        x_ is None
+        and y_ is None
+        and (width_ or print_width_) is not None
+        and (height_ or print_height_) is not None
+        and pad_ == 0
+        and dpu_ is None
+    ):
+        width = print_width_ if width_ is None else width_
+        height = print_height_ if height_ is None else height_
+        inferred_attribs["width"] = to_svg_str(width or 0)
+        inferred_attribs["height"] = to_svg_str(height or 0)
+
     inferred_attribs.update(attributes)
     # can only pass nsmap on instance creation
     svg_root = etree.Element(f"{{{nsmap[None]}}}svg", nsmap=nsmap)

svg_ultralight/root_elements.py

@@ -11,6 +11,7 @@ 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.constructors.new_element import new_element_union
 from svg_ultralight.main import new_svg_root
 
 if TYPE_CHECKING:
@@ -21,6 +22,7 @@ if TYPE_CHECKING:
     from svg_ultralight.attrib_hints import ElemAttrib, OptionalElemAttribMapping
     from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
     from svg_ultralight.layout import PadArg
+    from svg_ultralight.unit_conversion import MeasurementArg
 
 
 def _viewbox_args_from_bboxes(*bboxes: BoundingBox) -> dict[str, float]:
@@ -41,9 +43,9 @@ def _viewbox_args_from_bboxes(*bboxes: BoundingBox) -> dict[str, float]:
 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,
+    print_width_: MeasurementArg | None = None,
+    print_height_: MeasurementArg | None = None,
+    dpu_: float | None = None,
     nsmap: dict[str | None, str] | None = None,
     attrib: OptionalElemAttribMapping = None,
     **attributes: ElemAttrib,
@@ -75,7 +77,7 @@ def new_svg_root_around_bounds(
     bbox = bound.new_bbox_union(*bounded)
     elem: EtreeElement | None = None
     with suppress(ValueError):
-        elem = bound.new_element_union(*bounded)
+        elem = new_element_union(*bounded)
     viewbox = _viewbox_args_from_bboxes(bbox)
     root = new_svg_root(
         x_=viewbox["x_"],

svg_ultralight/string_conversion.py

@@ -10,9 +10,10 @@ Rounding some numbers to ensure quality svg rendering:
 from __future__ import annotations
 
 import binascii
+import itertools as it
 import re
 from enum import Enum
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Literal, cast
 
 import svg_path_data
 from lxml import etree
@@ -20,7 +21,7 @@ from lxml import etree
 from svg_ultralight.nsmap import NSMAP
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Iterator
 
     from lxml.etree import (
         _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
@@ -29,6 +30,10 @@ if TYPE_CHECKING:
     from svg_ultralight.attrib_hints import ElemAttrib
 
 
+# match a hex color string with 8 digits: #RRGGBBAA
+_HEX_COLOR_8DIGIT = re.compile(r"^#([0-9a-fA-F]{8})$")
+
+
 def format_number(num: float | str, resolution: int | None = 6) -> str:
     """Format a number into an svg-readable float string with resolution = 6.
 
@@ -52,7 +57,24 @@ def format_numbers(
     return [format_number(num) for num in nums]
 
 
-def _fix_key_and_format_val(key: str, val: ElemAttrib) -> tuple[str, str]:
+def _split_opacity(
+    prefix: Literal["fill", "stroke"], hex_color: str
+) -> Iterator[tuple[str, str]]:
+    """Get a fill and fill-opacity or stroke and stroke-opacity for an svg element.
+
+    :param prefix: either "fill" or "stroke"
+    :param color: an 8-digit hex color with leading # ("#RRGGBBAA")
+    :yield: tuples of (attribute name, attribute value)
+    """
+    rgb, opacity = hex_color[:7], hex_color[7:]
+    if opacity == "00":
+        yield (prefix, "none")
+    else:
+        yield (prefix, rgb)
+        yield f"{prefix}-opacity", format_number(int(opacity, 16) / 255)
+
+
+def _fix_key_and_format_val(key: str, val: ElemAttrib) -> Iterator[tuple[str, str]]:
     """Format one key, value pair for an svg element.
 
     :param key: element attribute name
@@ -64,17 +86,18 @@ def _fix_key_and_format_val(key: str, val: ElemAttrib) -> tuple[str, str]:
     values. This saves having to convert input to strings.
 
     * convert float values to formatted strings
-    * format datastring values when keyword is 'd'
     * replace '_' with '-' in keywords
     * remove trailing '_' from keywords
     * will convert `namespace:tag` to a qualified name
+    * will convert 8-digit hex colors to color + opacity. SVG supports 8-digit hex
+      colors, but Inkscape (and likely other Linux-based SVG rasterizers) do not.
 
     SVG attribute names like `font-size` and `stroke-width` are not valid python
-    keywords, but can be passed as `font-size` and `stroke-width`.
+    keywords, but can be passed as `font_size` and `stroke_width`.
 
     Reserved Python keywords that are also valid and useful SVG attribute names (a
     popular one will be 'class') can be passed with a trailing underscore (e.g.,
-    class_='body_text').
+    class_='body_text') to keep your code highlighter from getting confused.
     """
     if "http:" in key or "https:" in key:
         key_ = key
@@ -88,10 +111,18 @@ def _fix_key_and_format_val(key: str, val: ElemAttrib) -> tuple[str, str]:
         val_ = "none"
     elif isinstance(val, (int, float)):
         val_ = format_number(val)
+    elif _HEX_COLOR_8DIGIT.match(val):
+        if key_ == "fill":
+            yield from _split_opacity("fill", val)
+            return
+        if key_ == "stroke":
+            yield from _split_opacity("stroke", val)
+            return
+        val_ = val
     else:
         val_ = val
 
-    return key_, val_
+    yield key_, val_
 
 
 def format_attr_dict(**attributes: ElemAttrib) -> dict[str, str]:
@@ -100,7 +131,8 @@ def format_attr_dict(**attributes: ElemAttrib) -> dict[str, str]:
     :param attributes: element attribute names and values.
     :return: dict of attributes, each key a valid svg attribute name, each value a str
     """
-    return dict(_fix_key_and_format_val(key, val) for key, val in attributes.items())
+    items = attributes.items()
+    return dict(it.chain(*(_fix_key_and_format_val(k, v) for k, v in items)))
 
 
 def set_attributes(elem: EtreeElement, **attributes: ElemAttrib) -> None: