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

svg_ultralight/unit_conversion.py

@@ -14,6 +14,8 @@ from __future__ import annotations
 import dataclasses
 import enum
 import re
+from contextlib import suppress
+from typing import Any, Literal, TypeAlias, cast
 
 from svg_ultralight.string_conversion import format_number
 
@@ -47,26 +49,33 @@ class Unit(enum.Enum):
     USER = "", 1  # "user units" without a unit specifier
 
 
-# the arguments this module will attempt to interpret as a string with a unit specifier
-MeasurementArg = (
-    float
-    | str
-    | tuple[str, str]
-    | tuple[float, str]
-    | tuple[str, Unit]
-    | tuple[float, Unit]
-    | Unit
-)
+_UnitSpecifier: TypeAlias = Literal[
+    "in", "pt", "px", "mm", "cm", "m", "km", "Q", "pc", "yd", "ft", ""
+]
+
 
 _UNIT_SPECIFIER2UNIT = {x.value[0]: x for x in Unit}
 
 _UNIT_SPECIFIERS = [x.value[0] for x in Unit]
 _NUMBER = r"([-+]?[0-9]+(\.[0-9]*)?|[-+]?\.[0-9]+)([eE][-+]?[0-9]+)?"
-_UNIT_RE = re.compile(rf"(?P<unit>{'|'.join(_UNIT_SPECIFIERS)})")
+_UNIT_RE = re.compile(rf"(?P<unit>{'|'.join(_UNIT_SPECIFIERS)})$")
 _NUMBER_RE = re.compile(rf"(?P<number>{_NUMBER})")
 _NUMBER_AND_UNIT = re.compile(rf"^{_NUMBER_RE.pattern}{_UNIT_RE.pattern}$")
 
 
+def is_measurement_arg(obj: object) -> bool:
+    """Determine if an object is a valid measurement argument.
+
+    :param obj: object to check
+    :return: True if the object is a valid measurement argument
+    """
+    maybe_measurement_arg = cast("Any", obj)
+    with suppress(ValueError):
+        _ = Measurement(maybe_measurement_arg)
+        return True
+    return False
+
+
 def _parse_unit(measurement_arg: MeasurementArg) -> tuple[float, Unit]:
     """Split the value and unit from a string.
 
@@ -95,8 +104,10 @@ def _parse_unit(measurement_arg: MeasurementArg) -> tuple[float, Unit]:
     | Measurement   | Measurement("3in") | (3.0, Unit.IN)     |
 
     """
+    if isinstance(measurement_arg, Measurement):
+        return measurement_arg.get_tuple()
     failure_msg = f"Cannot parse value and unit from {measurement_arg}"
-    unit: str | Unit
+    unit: _UnitSpecifier | Unit
     try:
         if isinstance(measurement_arg, tuple):
             number, unit = float(measurement_arg[0]), measurement_arg[1]
@@ -110,13 +121,15 @@ def _parse_unit(measurement_arg: MeasurementArg) -> tuple[float, Unit]:
         if isinstance(measurement_arg, Unit):
             return _parse_unit((0, measurement_arg))
 
-        if number_unit := _NUMBER_AND_UNIT.match(str(measurement_arg)):
-            return _parse_unit((number_unit["number"], number_unit["unit"]))
+        if number_unit := _NUMBER_AND_UNIT.match(measurement_arg):
+            unit = _UNIT_SPECIFIER2UNIT[number_unit["unit"]]
+            return _parse_unit((number_unit["number"], unit))
 
-        if unit_only := _UNIT_RE.match(str(measurement_arg)):
-            return _parse_unit((0, unit_only["unit"]))
+        if unit_only := _UNIT_RE.match(measurement_arg):
+            unit = _UNIT_SPECIFIER2UNIT[unit_only["unit"]]
+            return _parse_unit((0, unit))
 
-    except (ValueError, KeyError) as e:
+    except (ValueError, KeyError, IndexError, TypeError) as e:
         raise ValueError(failure_msg) from e
 
     raise ValueError(failure_msg)
@@ -142,6 +155,16 @@ class Measurement:
         value, self.native_unit = _parse_unit(measurement_arg)
         self.value = value * self.native_unit.value[1]
 
+    def __float__(self) -> float:
+        """Get the measurement in user units.
+
+        :return: value in user units
+
+        It's best to do all math with self.value, but this is here for conversion
+        with less precision loss.
+        """
+        return self.value
+
     def get_value(self, unit: Unit | None = None) -> float:
         """Get the measurement in the specified unit.
 
@@ -175,7 +198,7 @@ class Measurement:
         single measurements. Single measurements can be defined by something like
         `(1, "in")`, but groups can be passed as single or tuples, so there is no way
         to differentiate between (1, "in") and "1in" or (1, "in") as ("1", "0in").
-        That is a limitation, but doint it that way preserved the flexibility (and
+        That is a limitation, but doing it that way preserved the flexibility (and
         backwards compatibility) of being able to define padding as "1in" everywhere
         or (1, 2, 3, 4) for top, right, bottom, left.
 
@@ -190,35 +213,49 @@ class Measurement:
     def get_svg(self, unit: Unit | None = None) -> str:
         """Get the measurement in the specified unit as it would be written in svg.
 
-        :param optional unit: the unit to convert to
+        :param optional unit: the unit to convert to (defaults to native unit)
         :return: the measurement in the specified unit, always as a string
 
         Rounds values to 6 decimal places as recommended by svg guidance online.
-        Higher precision just changes file size without imroving quality.
+        Higher resolution just changes file size without imroving quality.
         """
-        _, unit = self.get_tuple(unit)
+        _, unit = self.get_tuple(unit or self.native_unit)
         value_as_str = format_number(self.get_value(unit))
         return f"{value_as_str}{unit.value[0]}"
 
-    def __add__(self, other: Measurement) -> Measurement:
+    def __add__(self, other: Measurement | float) -> Measurement:
         """Add two measurements.
 
         :param other: the other measurement
         :return: the sum of the two measurements in self native unit
         """
         result = Measurement(self.native_unit)
-        result.value = self.value + other.value
+        result.value = self.value + float(other)
         return result
 
-    def __sub__(self, other: Measurement) -> Measurement:
+    def __radd__(self, other: float) -> Measurement:
+        """Add a measurement to a float.
+
+        :param other: the other measurement
+        :return: the sum of the two measurements in self native unit
+        """
+        return self.__add__(other)
+
+    def __sub__(self, other: Measurement | float) -> Measurement:
         """Subtract two measurements.
 
         :param other: the other measurement
         :return: the difference of the two measurements in self native unit
         """
-        result = Measurement(self.native_unit)
-        result.value = self.value - other.value
-        return result
+        return self.__add__(-other)
+
+    def __rsub__(self, other: float) -> Measurement:
+        """Subtract a measurement from a float.
+
+        :param other: the other measurement
+        :return: the difference of the two measurements in self native unit
+        """
+        return self.__mul__(-1).__add__(other)
 
     def __mul__(self, scalar: float) -> Measurement:
         """Multiply a measurement by a scalar.
@@ -245,3 +282,43 @@ class Measurement:
         :return: the measurement divided by the scalar in self native unit
         """
         return self.__mul__(1.0 / scalar)
+
+    def __neg__(self) -> Measurement:
+        """Negate a measurement.
+
+        :return: the negated measurement in self native unit
+        """
+        return self.__mul__(-1)
+
+
+def to_user_units(measurement_arg: MeasurementArg) -> float:
+    """Convert a measurement argument to user units.
+
+    :param measurement_arg: The measurement argument to convert
+    :return: The measurement in user units
+    """
+    if isinstance(measurement_arg, (int, float)):
+        return float(measurement_arg)
+    return Measurement(measurement_arg).value
+
+
+def to_svg_str(measurement_arg: MeasurementArg) -> str:
+    """Convert a measurement argument to an svg string.
+
+    :param measurement_arg: The measurement argument to convert
+    :return: The measurement as an svg string
+    """
+    return Measurement(measurement_arg).get_svg()
+
+
+# the arguments this module will attempt to interpret as a string with a unit specifier
+MeasurementArg: TypeAlias = (
+    float
+    | str
+    | tuple[str, _UnitSpecifier]
+    | tuple[float, _UnitSpecifier]
+    | tuple[str, Unit]
+    | tuple[float, Unit]
+    | Unit
+    | Measurement
+)

{svg_ultralight-0.64.0.dist-info → svg_ultralight-0.73.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: svg-ultralight
-Version: 0.64.0
+Version: 0.73.1
 Summary: a sensible way to create svg files with Python
 Author: Shay Hill
 Author-email: Shay Hill <shay_public@hotmail.com>

{svg_ultralight-0.64.0.dist-info → svg_ultralight-0.73.1.dist-info}/RECORD

@@ -1,35 +1,34 @@
-svg_ultralight/__init__.py,sha256=DhQPgcNsTz8ZIeKPZGMXlOpZZS28BsMPVi0ELg00E_M,2858
+svg_ultralight/__init__.py,sha256=6rH78uWngTeTQkS636swQBM3B_7F57k3B2Mz3tkTU4o,2895
 svg_ultralight/animate.py,sha256=pwboos8Z1GFNEGxHxIeeIyxyfRUew5pus2lG3P4MERU,1093
 svg_ultralight/attrib_hints.py,sha256=_p85b77mcmj15IUnsDtgbYJ3FFd-Q1qM2OERv2UEZ20,419
 svg_ultralight/bounding_boxes/__init__.py,sha256=YNCwgN-Ja2MFoCxIYxC3KZTCx_gFvPfRQ-8zBR5Q9mk,73
-svg_ultralight/bounding_boxes/bound_helpers.py,sha256=660DLfjnOOdLE-GmsDIZhF4JckdiK9O7DcFGWQ-g4Ww,7010
-svg_ultralight/bounding_boxes/padded_text_initializers.py,sha256=xv34iEmy8gvCgBZmYnLf26Y5MCjnCt1VF3jyLZvkfws,15085
+svg_ultralight/bounding_boxes/bound_helpers.py,sha256=zTzsLagCESWsFZweS-ErFNSKi7z7OrCGcgjQgt8LCiY,6594
+svg_ultralight/bounding_boxes/padded_text_initializers.py,sha256=EBI6uyO2PerVt4CSp-p9gycmB53SS6_iQF8gqnkW1b0,13494
 svg_ultralight/bounding_boxes/supports_bounds.py,sha256=8rIklGICIx-DXELN7FjDwrzOi8iUrlstGrCIuN9ew3o,4458
 svg_ultralight/bounding_boxes/type_bound_collection.py,sha256=ct8BLjqyHSCNhOGG0eYuubdOajI2KVo1nbTP3JxXZ00,2756
 svg_ultralight/bounding_boxes/type_bound_element.py,sha256=gXsHCSJ6lxIGODm1oJ5yYAPzuIi7NkBIIzD_GX-cgo8,2322
-svg_ultralight/bounding_boxes/type_bounding_box.py,sha256=gnbZjj32eaaRA0cSJwUsnfbhFqOlH35GTfYcVhRjAog,14644
-svg_ultralight/bounding_boxes/type_padded_list.py,sha256=8Osu-sfyzuvBrNlrkAtJnMLgS7HP1DT5ojjecI_KNPo,8125
-svg_ultralight/bounding_boxes/type_padded_text.py,sha256=OvMMJ2NWAXavjvs2l8MPwCVdRyy6PBI3wmmkcSugejY,17272
+svg_ultralight/bounding_boxes/type_bounding_box.py,sha256=V9i-EhJRIz6g1moPIuvFeh_zoASQVj0SdoD2FSknGKo,15314
+svg_ultralight/bounding_boxes/type_padded_list.py,sha256=NAEIdSmm-D4Zjmtogj4K_n1ioqP3w1am97x3byz0N3Y,7918
+svg_ultralight/bounding_boxes/type_padded_text.py,sha256=TPi2UO-sCsJOEau41uUc_QFsdbXMTZU10cbmkMpw65A,22208
 svg_ultralight/constructors/__init__.py,sha256=fb-A50G3YTZNMQXpxcCl_QAcfssS0Us065_kdJRybDQ,313
-svg_ultralight/constructors/new_element.py,sha256=7n4LQROxi-Lzi1t-85704H5heADeyoctfJEvEBLlT50,3431
+svg_ultralight/constructors/new_element.py,sha256=AppAt4t9VNDjnWChhGe-R-T696oNVne-rWOdOuHpGRY,4752
 svg_ultralight/font_tools/__init__.py,sha256=b_VSvk5aODzS2wv48EMU2sey_mxq1o1SL8ecWTdy4kc,78
-svg_ultralight/font_tools/comp_results.py,sha256=-GZ3wvnWER7IWurL2IzZym-_0wcLT3y3jGukV4V4pTI,10341
-svg_ultralight/font_tools/font_info.py,sha256=mLI4dRS_zb6FeTSfpP0Zw_GxsXIDsu3vkQ0X-gOdZbU,31968
+svg_ultralight/font_tools/comp_results.py,sha256=O0id9w8ORTxGWLVdhRxuh-MdzxixcrF-1pQCp2yQPRs,10311
+svg_ultralight/font_tools/font_info.py,sha256=CweGwPo8C68FAOkiev_1AHO88jfs6Q59-BvyiR_5pCQ,34229
 svg_ultralight/image_ops.py,sha256=cwR038ECUuiceIrk-9Peh5Ijp4tzjuaV5Y1cvYOt4TI,5454
 svg_ultralight/inkscape.py,sha256=_aQ42ZQ1JP9TFdHmtxgCRsXvxfZPpdZWTGKEea9BgIU,9336
-svg_ultralight/layout.py,sha256=yiTAYtSsYywdCObIdjkK3A4fiEYLNPqD3BOQKxfj6gQ,12514
-svg_ultralight/main.py,sha256=T5S2vtLU99JTVH1RucsWmQPlyltruWmQBMXAZEKbuok,7178
+svg_ultralight/layout.py,sha256=xj_QvRnzWpDHPvA1qWX9XQJmwJ0-ghWkd03-HcPLUKE,13036
+svg_ultralight/main.py,sha256=zCBDB5QmkAFsnCCBkgfXzWVoFMNWR7Pp9MQ684x2YrM,7735
 svg_ultralight/metadata.py,sha256=kBaJ2QPpCn1s2f-qBGJxivA3HXoGTVKp4sU3-U0SQMw,4112
 svg_ultralight/nsmap.py,sha256=3N-x2I1iJ4EPWjYxIyHi4z8MVbJzxUyRvaGsiOijqmA,1208
 svg_ultralight/py.typed,sha256=cnjZxaS4F-N8wLWhQK9YvZ-PaN5T1TK94E9VhPT_LGg,155
 svg_ultralight/query.py,sha256=tSW6kvIm6Rq7IBterq6XHU90w8F2cWROSWri0JWl4nM,9680
-svg_ultralight/read_svg.py,sha256=07azKpJciJEiw_VJt_YHd-PnUWxjnw5nE1ruSP0qTLo,2090
-svg_ultralight/root_elements.py,sha256=V9XsIHQBnik6D6inlV0TiO_2RkFPLbn6qFkLR2l_saM,3464
-svg_ultralight/string_conversion.py,sha256=pzqkbGb-wXdhGd8ojEx4Hy-HBCC8fOfcloaLrNMh8TM,8607
+svg_ultralight/root_elements.py,sha256=NHUQEqb7YLoC1FCy5RMD5IkmIGlC3YzHoKnZM5W4MEY,3606
+svg_ultralight/string_conversion.py,sha256=MQQyI7I1DOd43ZHQG-7NYL9PkMLRKbyFfqtm84T0-yQ,9796
 svg_ultralight/strings/__init__.py,sha256=iaRwr9AF9bPDkG3XvgGRSf8JPAS2GQ8ds9yCNpPN4ng,365
 svg_ultralight/strings/svg_strings.py,sha256=XlXQ5RqueGrROXBI4VzR2cK7e1NdNhYx5S84bgyqFUQ,3132
 svg_ultralight/transformations.py,sha256=YyhehH0Hlui2U9t7hjwgHgRyHzUR7UCMSSo-G85J-bo,4784
-svg_ultralight/unit_conversion.py,sha256=Y32GZ5TLkvjDHM2kBw52M8ZxDNlpVSlDkSdRa1S_X-A,8985
-svg_ultralight-0.64.0.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
-svg_ultralight-0.64.0.dist-info/METADATA,sha256=M31DX00UVc1Qolt45PUk7WlcOGXVH52VfU1ehsKIHMI,8691
-svg_ultralight-0.64.0.dist-info/RECORD,,
+svg_ultralight/unit_conversion.py,sha256=72B1_1ubz3Rl498deSZkOih3lI2lpPxT2JlWuCLXZBo,11436
+svg_ultralight-0.73.1.dist-info/WHEEL,sha256=eh7sammvW2TypMMMGKgsM83HyA_3qQ5Lgg3ynoecH3M,79
+svg_ultralight-0.73.1.dist-info/METADATA,sha256=NeBy62XYkcTKV_fcENURDXYcPF1PN2RHIoVZ0s1hNIM,8691
+svg_ultralight-0.73.1.dist-info/RECORD,,

svg_ultralight/read_svg.py

@@ -1,58 +0,0 @@
-"""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)