svg-ultralight 0.37.0__py3-none-any.whl → 0.39.0__py3-none-any.whl

svg_ultralight/bounding_boxes/type_padded_text.py

@@ -12,7 +12,7 @@ There is a getter and setter for each of the four padding values. These *do not*
 the text element. For instance, if you decrease the left padding, the left margin
 will move, *not* the text element.
 
-There is a getter and setter for each of lmargin, rmargin, baseline, and capline.
+_There is a getter and setter for each of lmargin, rmargin, baseline, and capline.
 These *do* move the element, but do not scale it. For instance, if you move the
 leftmargin to the left, the right margin (and the text element with it) will move to
 the left.
@@ -66,16 +66,19 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from svg_ultralight.bounding_boxes.supports_bounds import SupportsBounds
+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
 
 if TYPE_CHECKING:
-    from lxml.etree import _Element as EtreeElement  # type: ignore
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
 
 _Matrix = tuple[float, float, float, float, float, float]
 
 
-class PaddedText(SupportsBounds):
+class PaddedText(BoundElement):
     """A line of text with a bounding box and padding."""
 
     def __init__(
@@ -97,14 +100,14 @@ class PaddedText(SupportsBounds):
         :param lpad: Left padding.
         """
         self.elem = elem
-        self.bbox = bbox
+        self.unpadded_bbox = bbox
         self.base_tpad = tpad
         self.rpad = rpad
         self.base_bpad = bpad
         self.lpad = lpad
 
     @property
-    def padded_bbox(self) -> BoundingBox:
+    def bbox(self) -> BoundingBox:
         """Return a BoundingBox around the margins and cap/baseline.
 
         :return: A BoundingBox around the margins and cap/baseline.
@@ -115,22 +118,28 @@ class PaddedText(SupportsBounds):
         instance around multiple text elements (a <g> elem).
         """
         return BoundingBox(
-            self.lmargin, self.capline, self.padded_width, self.padded_height
+            self.x,
+            self.y,
+            self.width,
+            self.height,
+            self.unpadded_bbox.transformation,
         )
 
-    @property
-    def transformation(self) -> _Matrix:
-        """The transformation matrix of the bounding box."""
-        return self.bbox.transformation
+    @bbox.setter
+    def bbox(self, value: BoundingBox) -> None:
+        """Set the bounding box of this PaddedText.
 
-    def _update_elem(self):
-        self.elem.attrib["transform"] = self.bbox.transform_string
+        :param value: The new bounding box.
+        :effects: The text element is transformed to fit the new bounding box.
+        """
+        msg = "Cannot set bbox of PaddedText, use transform() instead."
+        raise NotImplementedError(msg)
 
     def transform(
         self,
         transformation: _Matrix | None = None,
         *,
-        scale: float | None = None,
+        scale: tuple[float, float] | None = None,
         dx: float | None = None,
         dy: float | None = None,
     ):
@@ -141,8 +150,9 @@ class PaddedText(SupportsBounds):
         :param dx: the x translation
         :param dy: the y translation
         """
-        self.bbox.transform(transformation, scale=scale, dx=dx, dy=dy)
-        self._update_elem()
+        tmat = new_transformation_matrix(transformation, scale=scale, dx=dx, dy=dy)
+        self.unpadded_bbox.transform(tmat)
+        _ = transform_element(self.elem, tmat)
 
     @property
     def tpad(self) -> float:
@@ -150,7 +160,7 @@ class PaddedText(SupportsBounds):
 
         :return: The scaled top padding of this line of text.
         """
-        return self.base_tpad * self.bbox.scale
+        return self.base_tpad * self.unpadded_bbox.scale[1]
 
     @tpad.setter
     def tpad(self, value: float) -> None:
@@ -158,7 +168,7 @@ class PaddedText(SupportsBounds):
 
         :param value: The new top padding.
         """
-        self.base_tpad = value / self.bbox.scale
+        self.base_tpad = value / self.unpadded_bbox.scale[1]
 
     @property
     def bpad(self) -> float:
@@ -166,7 +176,7 @@ class PaddedText(SupportsBounds):
 
         :return: The scaled bottom padding of this line of text.
         """
-        return self.base_bpad * self.bbox.scale
+        return self.base_bpad * self.unpadded_bbox.scale[1]
 
     @bpad.setter
     def bpad(self, value: float) -> None:
@@ -174,82 +184,18 @@ class PaddedText(SupportsBounds):
 
         :param value: The new bottom padding.
         """
-        self.base_bpad = value / self.bbox.scale
-
-    @property
-    def lmargin(self) -> float:
-        """The left margin of this line of text.
-
-        :return: The left margin of this line of text.
-        """
-        return self.bbox.x - self.lpad
-
-    @lmargin.setter
-    def lmargin(self, value: float) -> None:
-        """Set the left margin of this line of text.
-
-        :param value: The left margin of this line of text.
-        """
-        self.transform(dx=value + self.lpad - self.bbox.x)
-
-    @property
-    def rmargin(self) -> float:
-        """The right margin of this line of text.
-
-        :return: The right margin of this line of text.
-        """
-        return self.bbox.x2 + self.rpad
-
-    @rmargin.setter
-    def rmargin(self, value: float) -> None:
-        """Set the right margin of this line of text.
-
-        :param value: The right margin of this line of text.
-        """
-        self.transform(dx=value - self.rpad - self.bbox.x2)
-
-    @property
-    def capline(self) -> float:
-        """The top of this line of text.
-
-        :return: The top of this line of text.
-        """
-        return self.bbox.y - self.tpad
-
-    @capline.setter
-    def capline(self, value: float) -> None:
-        """Set the top of this line of text.
-
-        :param value: The top of this line of text.
-        """
-        self.transform(dy=value + self.tpad - self.bbox.y)
+        self.base_bpad = value / self.unpadded_bbox.scale[1]
 
     @property
-    def baseline(self) -> float:
-        """The bottom of this line of text.
-
-        :return: The bottom of this line of text.
-        """
-        return self.bbox.y2 + self.bpad
-
-    @baseline.setter
-    def baseline(self, value: float) -> None:
-        """Set the bottom of this line of text.
-
-        :param value: The bottom of this line of text.
-        """
-        self.transform(dy=value - self.bpad - self.bbox.y2)
-
-    @property
-    def padded_width(self) -> float:
+    def width(self) -> float:
         """The width of this line of text with padding.
 
         :return: The scaled width of this line of text with padding.
         """
-        return self.bbox.width + self.lpad + self.rpad
+        return self.unpadded_bbox.width + self.lpad + self.rpad
 
-    @padded_width.setter
-    def padded_width(self, width: float) -> None:
+    @width.setter
+    def width(self, value: float) -> None:
         """Scale to padded_width = width without scaling padding.
 
         :param width: The new width of this line of text.
@@ -261,27 +207,26 @@ class PaddedText(SupportsBounds):
         baseline is near y2 (y + height) not y. So, we preserve baseline (alter y
         *and* y2) when scaling.
         """
-        baseline = self.baseline
-        self.bbox.width = width - self.lpad - self.rpad
-        self.baseline = baseline
-        self._update_elem()
+        y2 = self.y2
+        self.unpadded_bbox.width = value - self.lpad - self.rpad
+        self.y2 = y2
 
     @property
-    def padded_height(self) -> float:
+    def height(self) -> float:
         """The height of this line of text with padding.
 
         :return: The scaled height of this line of text with padding.
         """
-        return self.bbox.height + self.tpad + self.bpad
+        return self.unpadded_bbox.height + self.tpad + self.bpad
 
-    @padded_height.setter
-    def padded_height(self, height: float) -> None:
-        """Scale to padded_height = height without scaling padding.
+    @height.setter
+    def height(self, value: float) -> None:
+        """Scale to height without scaling padding.
 
         :param height: The new height of this line of text.
         :effects: the text_element bounding box is scaled to height - tpad - bpad.
         """
-        self.padded_width *= height / self.padded_height
+        self.width *= value / self.height
 
     @property
     def x(self) -> float:
@@ -289,15 +234,15 @@ class PaddedText(SupportsBounds):
 
         :return: The left margin of this line of text.
         """
-        return self.lmargin
+        return self.unpadded_bbox.x - self.lpad
 
     @x.setter
     def x(self, value: float) -> None:
         """Set the left margin of this line of text.
 
-        :param value: The new left margin of this line of text.
+        :param value: The left margin of this line of text.
         """
-        self.lmargin = value
+        self.transform(dx=value + self.lpad - self.unpadded_bbox.x)
 
     @property
     def x2(self) -> float:
@@ -305,134 +250,49 @@ class PaddedText(SupportsBounds):
 
         :return: The right margin of this line of text.
         """
-        return self.rmargin
+        return self.unpadded_bbox.x2 + self.rpad
 
     @x2.setter
     def x2(self, value: float) -> None:
         """Set the right margin of this line of text.
 
-        :param value: The new right margin of this line of this text.
+        :param value: The right margin of this line of text.
         """
-        self.rmargin = value
+        self.transform(dx=value - self.rpad - self.unpadded_bbox.x2)
 
     @property
     def y(self) -> float:
-        """The capline of this line of text.
+        """The top of this line of text.
 
-        :return: The capline of this line of text.
+        :return: The top of this line of text.
         """
-        return self.capline
+        return self.unpadded_bbox.y - self.tpad
 
     @y.setter
     def y(self, value: float) -> None:
-        """Set the capline of this line of text.
+        """Set the top of this line of text.
 
-        :param value: The new capline of this line of text.
+        :param value: The top of this line of text.
         """
-        self.capline = value
+        self.transform(dy=value + self.tpad - self.unpadded_bbox.y)
 
     @property
     def y2(self) -> float:
-        """The baseline of this line of text.
+        """The bottom of this line of text.
 
-        :return: The baseline of this line of text.
+        :return: The bottom of this line of text.
         """
-        return self.baseline
+        return self.unpadded_bbox.y2 + self.bpad
 
     @y2.setter
     def y2(self, value: float) -> None:
-        """Set the baseline of this line of text.
-
-        :param value: The new baseline of this line of text.
-        """
-        self.baseline = value
-
-    @property
-    def width(self) -> float:
-        """The width of this line of text with padding.
-
-        :return: The scaled width of this line of text with padding.
-        """
-        return self.padded_width
-
-    @width.setter
-    def width(self, value: float) -> None:
-        """Scale to width without scaling padding.
-
-        :param value: The new width of this line of text.
-        :effects: the text_element bounding box is scaled to width - lpad - rpad.
-
-        Svg_Ultralight BoundingBoxes preserve x and y when scaling. This is
-        consistent with how rectangles, viewboxes, and anything else defined by x, y,
-        width, height behaves in SVG. This is unintuitive for text, because the
-        baseline is near y2 (y + height) not y. So, we preserve baseline (alter y
-        *and* y2) when scaling.
-        """
-        baseline = self.baseline
-        self.padded_width = value
-        self.baseline = baseline
-
-    @property
-    def height(self) -> float:
-        """The height of this line of text with padding.
-
-        :return: The scaled height of this line of text with padding.
-        """
-        return self.padded_height
-
-    @height.setter
-    def height(self, value: float) -> None:
-        """Scale to height without scaling padding.
-
-        :param value: The new height of this line of text.
-        :effects: the text_element bounding box is scaled to height - tpad - bpad.
-        """
-        self.padded_height = value
-
-    @property
-    def cx(self) -> float:
-        """The x coordinate of the center between margins.
-
-        :return: the x coordinate of the center between margins
-        """
-        return self.lmargin + self.padded_width / 2
-
-    @cx.setter
-    def cx(self, value: float):
-        """Set the x coordinate of the center between margins.
-
-        :param value: the new x coordinate of the center between margins
-        """
-        self.lmargin = value - self.padded_width / 2
-
-    @property
-    def cy(self) -> float:
-        """The y coordinate of the center between baseline and capline.
-
-        :return: the y coordinate of the center between baseline and capline
-        """
-        return self.capline + self.padded_height / 2
-
-    @cy.setter
-    def cy(self, value: float):
-        """Set the y coordinate of the center between baseline and capline.
-
-        :param value: the new y coordinate of the center between baseline and capline
-        """
-        self.capline = value - self.padded_height / 2
-
-    @property
-    def scale(self) -> float:
-        """The scale of the text element.
+        """Set the bottom of this line of text.
 
-        :return: the scale of the text element
+        :param value: The bottom of this line of text.
         """
-        return self.bbox.scale
-
-    @scale.setter
-    def scale(self, value: float):
-        """Set the scale of the text element.
+        self.transform(dy=value - self.bpad - self.unpadded_bbox.y2)
 
-        :param value: the new scale of the text element
-        """
-        self.bbox.scale = value
+    lmargin = x
+    rmargin = x2
+    capline = y
+    baseline = y2

svg_ultralight/constructors/new_element.py

@@ -21,7 +21,9 @@ from svg_ultralight.string_conversion import set_attributes
 
 if TYPE_CHECKING:
     from lxml.etree import QName
-    from lxml.etree import _Element as EtreeElement  # type: ignore
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
 
 
 def new_element(tag: str | QName, **attributes: str | float) -> EtreeElement:

svg_ultralight/inkscape.py

@@ -30,7 +30,9 @@ from lxml import etree
 from svg_ultralight import main
 
 if TYPE_CHECKING:
-    from lxml.etree import _Element as EtreeElement  # type: ignore
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
 
 
 def write_png_from_svg(

svg_ultralight/layout.py

@@ -144,11 +144,11 @@ def pad_and_scale(
     """Expand and scale the pad argument. If necessary, scale image.
 
     :param viewbox: viewbox to pad (x, y, width height)
-    :param pad: padding to add around image, in user units or inches. if a
+    :param pad: padding to add around image, in user units or inches. If a
         sequence, it should be (top, right, bottom, left). if a single float or
-        string, it will be applied to all sides. if two floats, top and bottom
-        then left and right. if three floats, top, left and right, then bottom.
-        if four floats, top, right, bottom, left.
+        string, it will be applied to all sides. If two floats, top and bottom
+        then left and right. If three floats, top, left and right, then bottom.
+        If four floats, top, right, bottom, left.
     :param print_width: width of print area, in user units (float), a string
         with a unit specifier (e.g., "452mm"), or just a unit specifier (e.g.,
         "pt")
@@ -169,7 +169,7 @@ def pad_and_scale(
     If the width and height *are* specified, the user units become whatever they
     need to be to fit that requirement. For instance, if the viewbox width is 96
     and the width argument is "1in", then the user units are *still* pixels,
-    because there are 96 pixels in an inch. If the viewbox with is 2 and the
+    because there are 96 pixels in an inch. If the viewbox width is 2 and the
     width argument is "1in", then the user units are 1/2 of an inch (i.e., 48
     pixels) each, because there are 2 user units in an inch. If the viewbox
     width is 3 and the width argument is "1yd", the each user unit is 1 foot.
@@ -195,17 +195,26 @@ def pad_and_scale(
     the unit designators without changing the scale.
 
     Print aspect ratio is ignored. Viewbox aspect ratio is preserved. For
-    instance, If you take a 100x100 unit image then pass pad="0.25in" and
-    print_width="12in", the output image will be 12.5 inches across. Whatever
-    geometry was visible in the original viewbox will be much larger, but the
-    padding will still be 0.25 inches. If you want to use padding and need a
-    specific output image size, remember to subtract the padding width from your
-    print_width or print_height.
+    instance, if you created two images
+
+    * x_=0, y_=0, width_=1, height_=2, pad_="0.25in", print_width_="6in"
+
+    * x_=0, y_=0, width_=1, height_=2, pad_="0.25in", print_width_="12in"
+
+    ... (note that the images only vary in print_width_), the first image would be
+    rendered at 6.5x12.5 inches and the second at 12.5x24.5 inches. The visible
+    content in the viewbox would be exactly twice as wide in the larger image, but
+    the padding would remain 0.25 in both images. Despite setting `print_width_` to
+    exactly 6 or 12 inches, you would not get an image exactly 6 or 12 inches wide.
+    Despite a viewbox aspect ratio of 1:2, you would not get an output image of
+    exactly 1:2. If you want to use padding and need a specific output image size or
+    aspect ratio, remember to subtract the padding width from your print_width or
+    print_height.
 
     Scaling attributes are returned as a dictonary that can be "exploded" into
     the element constructor, e.g., {"width": "12.5in", "height": "12.5in"}.
 
-    * If neighther a print_width nor print_height is specified, no scaling
+    * If neither a print_width nor print_height is specified, no scaling
       attributes will be returned.
 
     * If either is specified, both a width and height will be returned (even if
@@ -242,7 +251,7 @@ def pad_and_scale(
     a 16" x 9" image with viwebox(0, 0, 14, 7), pad_="1in", print_width_="14in"
     ... then scale the printout with dpu_=2 to get a 32" x 18" image with the
     same viewbox. This means the padding will be 2" on all sides, but the image
-    will be identical (just twice as large) as the 16" x 9" image.
+    will be identical (just twice as wide and twice as high) as the 16" x 9" image.
     """
     pads = expand_pad_arg(pad)
 

svg_ultralight/main.py

@@ -13,6 +13,7 @@ should work with all Inkscape versions. Please report any issues.
 
 from __future__ import annotations
 
+import sys
 from pathlib import Path
 from typing import IO, TYPE_CHECKING
 
@@ -23,8 +24,15 @@ from svg_ultralight.layout import pad_and_scale
 from svg_ultralight.nsmap import NSMAP
 from svg_ultralight.string_conversion import get_viewBox_str, svg_tostring
 
+if sys.version_info >= (3, 10):
+    from typing import TypeGuard
+else:
+    from typing_extensions import TypeGuard
+
 if TYPE_CHECKING:
-    from lxml.etree import _Element as EtreeElement  # type: ignore
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
 
     from svg_ultralight.layout import PadArg
 
@@ -38,7 +46,7 @@ def _is_four_floats(objs: tuple[object, ...]) -> bool:
     return len(objs) == 4 and all(isinstance(x, (float, int)) for x in objs)
 
 
-def _is_io_bytes(obj: object) -> bool:
+def _is_io_bytes(obj: object) -> TypeGuard[IO[bytes]]:
     """Determine if an object is file-like.
 
     :param obj: object
@@ -172,8 +180,8 @@ def write_svg(
     svg_contents = svg_tostring(root, **tostring_kwargs)
 
     if _is_io_bytes(svg):
-        _ = svg.write(svg_contents)  # type: ignore
-        return svg.name  # type: ignore
+        _ = svg.write(svg_contents)
+        return svg.name
     if isinstance(svg, (Path, str)):
         with Path(svg).open("wb") as svg_file:
             _ = svg_file.write(svg_contents)

svg_ultralight/metadata.py

@@ -9,7 +9,7 @@ fields.
 
 import warnings
 
-from lxml.etree import _Element as EtreeElement  # type: ignore
+from lxml.etree import _Element as EtreeElement  # pyright: ignore[reportPrivateUsage]
 
 from svg_ultralight.constructors.new_element import new_element, new_sub_element
 from svg_ultralight.nsmap import new_qname