svg-ultralight 0.39.0__tar.gz → 0.40.0__tar.gz

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/.pre-commit-config.yaml

@@ -92,6 +92,8 @@ repos:
   # S301 don't use pickle
   # B028 wants explicit stacklevel on warn
   # BLE001 Use of `except Exception:` detected
+  # ANN401 Any type disallowed
+  # FLY002 Consider f-string instead of string join
   rev: 'v0.11.11'
   hooks:
     - id: ruff
@@ -100,7 +102,7 @@ repos:
       args:
       - --target-version=py39
       - --select=ALL
-      - --ignore=ANN201,ANN202,B905,COM812,D203,D213,I001,ISC003,N802,N806,PGH003,PLR0913,PTH108,S101,S603,PLR2004,S320,S301,B028,BLE001
+      - --ignore=ANN201,ANN202,B905,COM812,D203,D213,I001,ISC003,N802,N806,PGH003,PLR0913,PTH108,S101,S603,PLR2004,S320,S301,B028,BLE001,ANN401,FLY002
       - --fix
       - --fixable=RUF022
     - id: ruff

{svg_ultralight-0.39.0/src/svg_ultralight.egg-info → svg_ultralight-0.40.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: svg-ultralight
-Version: 0.39.0
+Version: 0.40.0
 Summary: a sensible way to create svg files with Python
 Author-email: Shay Hill <shay_public@hotmail.com>
 License: MIT
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
+Requires-Dist: cssutils
+Requires-Dist: fonttools
 Requires-Dist: lxml
-Requires-Dist: pillow
 Requires-Dist: paragraphs
+Requires-Dist: pillow
 Requires-Dist: types-lxml
 Requires-Dist: typing-extensions
 Provides-Extra: dev

svg_ultralight-0.40.0/dev-requirements.txt

@@ -0,0 +1,110 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile --extra=dev --output-file=dev-requirements.txt --strip-extras pyproject.toml
+#
+argcomplete==3.6.2
+    # via commitizen
+beautifulsoup4==4.13.4
+    # via types-lxml
+cachetools==6.0.0
+    # via tox
+cfgv==3.4.0
+    # via pre-commit
+chardet==5.2.0
+    # via tox
+charset-normalizer==3.4.2
+    # via commitizen
+colorama==0.4.6
+    # via
+    #   commitizen
+    #   pytest
+    #   tox
+commitizen==4.8.2
+    # via svg-ultralight (pyproject.toml)
+cssselect==1.3.0
+    # via types-lxml
+cssutils==2.11.1
+    # via svg-ultralight (pyproject.toml)
+decli==0.6.3
+    # via commitizen
+distlib==0.3.9
+    # via virtualenv
+filelock==3.18.0
+    # via
+    #   tox
+    #   virtualenv
+fonttools==4.58.1
+    # via svg-ultralight (pyproject.toml)
+identify==2.6.12
+    # via pre-commit
+iniconfig==2.1.0
+    # via pytest
+jinja2==3.1.6
+    # via commitizen
+lxml==5.4.0
+    # via svg-ultralight (pyproject.toml)
+markupsafe==3.0.2
+    # via jinja2
+more-itertools==10.7.0
+    # via cssutils
+nodeenv==1.9.1
+    # via pre-commit
+packaging==25.0
+    # via
+    #   commitizen
+    #   pyproject-api
+    #   pytest
+    #   tox
+paragraphs==1.0.1
+    # via svg-ultralight (pyproject.toml)
+pillow==11.2.1
+    # via svg-ultralight (pyproject.toml)
+platformdirs==4.3.8
+    # via
+    #   tox
+    #   virtualenv
+pluggy==1.6.0
+    # via
+    #   pytest
+    #   tox
+pre-commit==4.2.0
+    # via svg-ultralight (pyproject.toml)
+prompt-toolkit==3.0.51
+    # via questionary
+pygments==2.19.1
+    # via pytest
+pyproject-api==1.9.1
+    # via tox
+pytest==8.4.0
+    # via svg-ultralight (pyproject.toml)
+pyyaml==6.0.2
+    # via
+    #   commitizen
+    #   pre-commit
+questionary==2.1.0
+    # via commitizen
+soupsieve==2.7
+    # via beautifulsoup4
+termcolor==2.5.0
+    # via commitizen
+tomlkit==0.13.2
+    # via commitizen
+tox==4.26.0
+    # via svg-ultralight (pyproject.toml)
+types-html5lib==1.1.11.20250516
+    # via types-lxml
+types-lxml==2025.3.30
+    # via svg-ultralight (pyproject.toml)
+typing-extensions==4.14.0
+    # via
+    #   beautifulsoup4
+    #   svg-ultralight (pyproject.toml)
+    #   types-lxml
+virtualenv==20.31.2
+    # via
+    #   pre-commit
+    #   tox
+wcwidth==0.2.13
+    # via prompt-toolkit

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/pyproject.toml

@@ -1,13 +1,20 @@
 [project]
 name = "svg-ultralight"
-version = "0.39.0"
+version = "0.40.0"
 description = "a sensible way to create svg files with Python"
 authors = [{ name = "Shay Hill", email = "shay_public@hotmail.com" }]
 license = { text = "MIT" }
 readme = "README.md"
 requires-python = ">=3.9"
-dependencies = ["lxml", "pillow", "paragraphs", "types-lxml", "typing-extensions"]
-
+dependencies = [
+    "cssutils",
+    "fonttools",
+    "lxml",
+    "paragraphs",
+    "pillow",
+    "types-lxml",
+    "typing-extensions",
+]
 [project.optional-dependencies]
 dev = ["pytest", "commitizen", "pre-commit", "tox"]
 images = ["pillow"]
@@ -42,7 +49,7 @@ convention = "pep257"
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "0.39.0"
+version = "0.40.0"
 tag_format = "$version"
 version_files = ["pyproject.toml:^version"]
 annotated_tag = true

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/__init__.py

@@ -14,6 +14,11 @@ from svg_ultralight.bounding_boxes.bound_helpers import (
     pad_bbox,
     parse_bound_element,
 )
+from svg_ultralight.bounding_boxes.padded_text_initializers import (
+    pad_text,
+    pad_text_ft,
+    pad_text_mix,
+)
 from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
 from svg_ultralight.bounding_boxes.type_bound_collection import BoundCollection
 from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
@@ -39,7 +44,6 @@ from svg_ultralight.query import (
     clear_svg_ultralight_cache,
     get_bounding_box,
     get_bounding_boxes,
-    pad_text,
 )
 from svg_ultralight.root_elements import new_svg_root_around_bounds
 from svg_ultralight.string_conversion import (
@@ -87,6 +91,8 @@ __all__ = [
     "new_svg_root_around_bounds",
     "pad_bbox",
     "pad_text",
+    "pad_text_ft",
+    "pad_text_mix",
     "parse_bound_element",
     "transform_element",
     "update_element",

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/animate.py

@@ -16,13 +16,13 @@ except ModuleNotFoundError as exc:
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    import os
     from collections.abc import Iterable
-    from pathlib import Path
 
 
 def write_gif(
-    gif: str | Path,
-    pngs: Iterable[str] | Iterable[Path] | Iterable[str | Path],
+    gif: str | os.PathLike[str],
+    pngs: Iterable[str] | Iterable[os.PathLike[str]] | Iterable[str | os.PathLike[str]],
     duration: float = 100,
     loop: int = 0,
 ) -> None:

svg_ultralight-0.40.0/src/svg_ultralight/bounding_boxes/padded_text_initializers.py

@@ -0,0 +1,186 @@
+"""Functions that create PaddedText instances.
+
+Three variants:
+
+- `pad_text`: uses Inkscape to measure text bounds
+
+- `pad_text_ft`: uses fontTools to measure text bounds (faster, and you get line_gap)
+
+- `pad_text_mix`: uses Inkscape and fontTools to give true ascent, descent, and
+  line_gap while correcting some of the layout differences between fontTools and
+  Inkscape.
+
+:author: Shay Hill
+:created: 2025-06-09
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from svg_ultralight.bounding_boxes.type_padded_text import PaddedText
+from svg_ultralight.constructors import new_element, update_element
+from svg_ultralight.font_tools.font_info import (
+    get_padded_text_info,
+    get_svg_font_attributes,
+)
+from svg_ultralight.font_tools.globs import DEFAULT_FONT_SIZE
+from svg_ultralight.query import get_bounding_boxes
+from svg_ultralight.string_conversion import (
+    encode_to_css_class_name,
+    format_attr_dict,
+    format_number,
+)
+
+if TYPE_CHECKING:
+    import os
+
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
+
+DEFAULT_Y_BOUNDS_REFERENCE = "{[|gjpqyf"
+
+
+def pad_text(
+    inkscape: str | os.PathLike[str],
+    text_elem: EtreeElement,
+    y_bounds_reference: str | None = None,
+    *,
+    font: str | os.PathLike[str] | None = None,
+) -> PaddedText:
+    r"""Create a PaddedText instance from a text element.
+
+    :param inkscape: path to an inkscape executable on your local file system
+        IMPORTANT: path cannot end with ``.exe``.
+        Use something like ``"C:\\Program Files\\Inkscape\\inkscape"``
+    :param text_elem: an etree element with a text tag
+    :param y_bounds_reference: an optional string to use to determine the ascent and
+        capline of the font. The default is a good choice, which approaches or even
+        meets the ascent of descent of most fonts without using utf-8 characters. You
+        might want to use a letter like "M" or even "x" if you are using an all-caps
+        string and want to center between the capline and baseline or if you'd like
+        to center between the baseline and x-line.
+    :param font: optionally add a path to a font file to use for the text element.
+        This is going to conflict with any font-family, font-style, or other
+        font-related attributes *except* font-size. You likely want to use
+        `font_tools.new_padded_text` if you're going to pass a font path, but you can
+        use it here to compare results between `pad_text` and `new_padded_text`.
+    :return: a PaddedText instance
+    """
+    if y_bounds_reference is None:
+        y_bounds_reference = DEFAULT_Y_BOUNDS_REFERENCE
+    if font is not None:
+        _ = update_element(text_elem, **get_svg_font_attributes(font))
+    if "font-size" not in text_elem.attrib:
+        text_elem.attrib["font-size"] = format_number(DEFAULT_FONT_SIZE)
+    rmargin_ref = deepcopy(text_elem)
+    capline_ref = deepcopy(text_elem)
+    _ = rmargin_ref.attrib.pop("id", None)
+    _ = capline_ref.attrib.pop("id", None)
+    rmargin_ref.attrib["text-anchor"] = "end"
+    capline_ref.text = y_bounds_reference
+
+    bboxes = get_bounding_boxes(inkscape, text_elem, rmargin_ref, capline_ref)
+    bbox, rmargin_bbox, capline_bbox = bboxes
+
+    tpad = bbox.y - capline_bbox.y
+    rpad = -rmargin_bbox.x2
+    bpad = capline_bbox.y2 - bbox.y2
+    lpad = bbox.x
+    return PaddedText(text_elem, bbox, tpad, rpad, bpad, lpad)
+
+
+def pad_text_ft(
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float = DEFAULT_FONT_SIZE,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    **attributes: str | float,
+) -> PaddedText:
+    """Create a new PaddedText instance using fontTools.
+
+    :param font: path to a font file.
+    :param text: the text of the text element.
+    :param font_size: the font size to use.
+    :param ascent: the ascent of the font. If not provided, it will be calculated
+        from the font file.
+    :param descent: the descent of the font. If not provided, it will be calculated
+        from the font file.
+    :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.
+    :param attributes: additional attributes to set on the text element. There is a
+        chance these will cause the font element to exceed the BoundingBox of the
+        PaddedText instance.
+    :return: a PaddedText instance with a line_gap defined.
+    """
+    attributes_ = format_attr_dict(**attributes)
+    attributes_["font-size"] = attributes_.get("font-size", format_number(font_size))
+    attributes_["class"] = encode_to_css_class_name(Path(font).name)
+
+    elem = new_element("text", text=text, **attributes_)
+    info = get_padded_text_info(
+        font, text, font_size, ascent, descent, y_bounds_reference=y_bounds_reference
+    )
+    return PaddedText(elem, info.bbox, *info.padding, info.line_gap)
+
+
+def pad_text_mix(
+    inkscape: str | os.PathLike[str],
+    font: str | os.PathLike[str],
+    text: str,
+    font_size: float = DEFAULT_FONT_SIZE,
+    ascent: float | None = None,
+    descent: float | None = None,
+    *,
+    y_bounds_reference: str | None = None,
+    **attributes: str | float,
+) -> PaddedText:
+    """Use Inkscape text bounds and fill missing with fontTools.
+
+    :param font: path to a font file.
+    :param text: the text of the text element.
+    :param font_size: the font size to use.
+    :param ascent: the ascent of the font. If not provided, it will be calculated
+        from the font file.
+    :param descent: the descent of the font. If not provided, it will be calculated
+        from the font file.
+    :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.
+    :param attributes: additional attributes to set on the text element. There is a
+        chance these will cause the font element to exceed the BoundingBox of the
+        PaddedText instance.
+    :return: a PaddedText instance with a line_gap defined.
+    """
+    elem = new_element("text", text=text, **attributes)
+    padded_inkscape = pad_text(inkscape, elem, y_bounds_reference, font=font)
+    padded_fonttools = pad_text_ft(
+        font,
+        text,
+        font_size,
+        ascent,
+        descent,
+        y_bounds_reference=y_bounds_reference,
+        **attributes,
+    )
+    bbox = padded_inkscape.unpadded_bbox
+    rpad = padded_inkscape.rpad
+    lpad = padded_inkscape.lpad
+    if y_bounds_reference is None:
+        tpad = padded_fonttools.tpad
+        bpad = padded_fonttools.bpad
+    else:
+        tpad = padded_inkscape.tpad
+        bpad = padded_inkscape.bpad
+    return PaddedText(elem, bbox, tpad, rpad, bpad, lpad, padded_fonttools.line_gap)

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/bounding_boxes/supports_bounds.py

@@ -49,7 +49,7 @@ class SupportsBounds(Protocol):
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: tuple[float, float] | None = None,
+        scale: tuple[float, float] | float | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/bounding_boxes/type_bound_collection.py

@@ -44,7 +44,7 @@ class BoundCollection(HasBoundingBox):
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: tuple[float, float] | None = None,
+        scale: tuple[float, float] | float | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/bounding_boxes/type_bound_element.py

@@ -49,7 +49,7 @@ class BoundElement(HasBoundingBox):
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: tuple[float, float] | None = None,
+        scale: tuple[float, float] | float | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/bounding_boxes/type_bounding_box.py

@@ -41,6 +41,18 @@ class HasBoundingBox(SupportsBounds):
         y2 = y + self.bbox.base_height
         return (x, y), (x2, y), (x2, y2), (x, y2)
 
+    def values(self) -> tuple[float, float, float, float]:
+        """Get the values of the bounding box.
+
+        :return: x, y, width, height of the bounding box
+        """
+        return (
+            self.bbox.x,
+            self.bbox.y,
+            self.bbox.width,
+            self.bbox.height,
+        )
+
     def _get_transformed_corners(
         self,
     ) -> tuple[
@@ -59,21 +71,11 @@ class HasBoundingBox(SupportsBounds):
         )
         return c0, c1, c2, c3
 
-    def _scale_scale_by_uniform_scalar(self, scalar: float) -> None:
-        """Scale the bounding box uniformly by a factor.
-
-        :param scale: scale factor
-        Unlike self.scale, this does not set the scale, but scales the scale. So if
-        the current scale is (2, 6), and you call this with a scalar of 2, the new
-        scale will be (4, 12).
-        """
-        self.transform(scale=(scalar, scalar))
-
     def transform(
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: tuple[float, float] | None = None,
+        scale: tuple[float, float] | float | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):
@@ -241,7 +243,7 @@ class HasBoundingBox(SupportsBounds):
         """
         current_x = self.x
         current_y = self.y
-        self._scale_scale_by_uniform_scalar(value / self.width)
+        self.transform(scale=value / self.width)
         self.x = current_x
         self.y = current_y
 

{svg_ultralight-0.39.0 → svg_ultralight-0.40.0}/src/svg_ultralight/bounding_boxes/type_padded_text.py

@@ -66,6 +66,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from paragraphs import par
+
 from svg_ultralight.bounding_boxes.type_bound_element import BoundElement
 from svg_ultralight.bounding_boxes.type_bounding_box import BoundingBox
 from svg_ultralight.transformations import new_transformation_matrix, transform_element
@@ -77,6 +79,14 @@ if TYPE_CHECKING:
 
 _Matrix = tuple[float, float, float, float, float, float]
 
+_no_line_gap_msg = par(
+    """No line_gap defined. Line gap is an inherent font attribute defined within a
+    font file. If this PaddedText instance was created with `pad_text` from reference
+    elements, a line_gap was not defined. Reading line_gap from the font file
+    requires creating a PaddedText instance with `pad_text_ft` or `pad_text_mixed`.
+    You can set an arbitrary line_gap after init with `instance.line_gap = value`."""
+)
+
 
 class PaddedText(BoundElement):
     """A line of text with a bounding box and padding."""
@@ -89,6 +99,7 @@ class PaddedText(BoundElement):
         rpad: float,
         bpad: float,
         lpad: float,
+        line_gap: float | None = None,
     ) -> None:
         """Initialize a PaddedText instance.
 
@@ -105,6 +116,7 @@ class PaddedText(BoundElement):
         self.rpad = rpad
         self.base_bpad = bpad
         self.lpad = lpad
+        self._line_gap = line_gap
 
     @property
     def bbox(self) -> BoundingBox:
@@ -122,7 +134,6 @@ class PaddedText(BoundElement):
             self.y,
             self.width,
             self.height,
-            self.unpadded_bbox.transformation,
         )
 
     @bbox.setter
@@ -139,7 +150,7 @@ class PaddedText(BoundElement):
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: tuple[float, float] | None = None,
+        scale: tuple[float, float] | float | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):
@@ -154,6 +165,32 @@ class PaddedText(BoundElement):
         self.unpadded_bbox.transform(tmat)
         _ = transform_element(self.elem, tmat)
 
+    @property
+    def line_gap(self) -> float:
+        """The line gap between this line of text and the next.
+
+        :return: The line gap between this line of text and the next.
+        """
+        if self._line_gap is None:
+            raise AttributeError(_no_line_gap_msg)
+        return self._line_gap
+
+    @line_gap.setter
+    def line_gap(self, value: float) -> None:
+        """Set the line gap between this line of text and the next.
+
+        :param value: The new line gap.
+        """
+        self._line_gap = value
+
+    @property
+    def leading(self) -> float:
+        """The leading of this line of text.
+
+        :return: The line gap plus the height of this line of text.
+        """
+        return self.height + self.line_gap
+
     @property
     def tpad(self) -> float:
         """The top padding of this line of text.
@@ -208,7 +245,12 @@ class PaddedText(BoundElement):
         *and* y2) when scaling.
         """
         y2 = self.y2
-        self.unpadded_bbox.width = value - self.lpad - self.rpad
+
+        no_margins_old = self.unpadded_bbox.width
+        no_margins_new = value - self.lpad - self.rpad
+        scale = no_margins_new / no_margins_old
+        self.transform(scale=(scale, scale))
+
         self.y2 = y2
 
     @property
@@ -226,7 +268,10 @@ class PaddedText(BoundElement):
         :param height: The new height of this line of text.
         :effects: the text_element bounding box is scaled to height - tpad - bpad.
         """
-        self.width *= value / self.height
+        y2 = self.y2
+        scale = value / self.height
+        self.transform(scale=(scale, scale))
+        self.y2 = y2
 
     @property
     def x(self) -> float:
@@ -244,6 +289,22 @@ class PaddedText(BoundElement):
         """
         self.transform(dx=value + self.lpad - self.unpadded_bbox.x)
 
+    @property
+    def cx(self) -> float:
+        """The horizontal center of this line of text.
+
+        :return: The horizontal center of this line of text.
+        """
+        return self.x + self.width / 2
+
+    @cx.setter
+    def cx(self, value: float) -> None:
+        """Set the horizontal center of this line of text.
+
+        :param value: The horizontal center of this line of text.
+        """
+        self.x += value - self.cx
+
     @property
     def x2(self) -> float:
         """The right margin of this line of text.
@@ -276,6 +337,22 @@ class PaddedText(BoundElement):
         """
         self.transform(dy=value + self.tpad - self.unpadded_bbox.y)
 
+    @property
+    def cy(self) -> float:
+        """The horizontal center of this line of text.
+
+        :return: The horizontal center of this line of text.
+        """
+        return self.y + self.height / 2
+
+    @cy.setter
+    def cy(self, value: float) -> None:
+        """Set the horizontal center of this line of text.
+
+        :param value: The horizontal center of this line of text.
+        """
+        self.y += value - self.cy
+
     @property
     def y2(self) -> float:
         """The bottom of this line of text.

svg_ultralight-0.40.0/src/svg_ultralight/font_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Mark font_tools as a package.
+
+:author: Shay Hill
+:created: 2025-06-04
+"""