Merge pull request #838 from snoyer/simplify-import_svg-api

simplify `import_svg` API

src/build123d/importers.py

@@ -31,10 +31,12 @@
 
 import os
 from os import PathLike, fsdecode
+import re
 import unicodedata
 from math import degrees
 from pathlib import Path
-from typing import Optional, TextIO, Union
+from typing import Literal, Optional, TextIO, Union
+import warnings
 
 from OCP.BRep import BRep_Builder
 from OCP.BRepGProp import BRepGProp
@@ -336,31 +338,35 @@ def import_svg(
     *,
     flip_y: bool = True,
     ignore_visibility: bool = False,
-    label_by: str = "id",
-    is_inkscape_label: bool = False,
+    label_by: Literal["id", "class", "inkscape:label"] | str = "id",
+    is_inkscape_label: bool | None = None,  # TODO remove for `1.0` release
 ) -> ShapeList[Wire | Face]:
     """import_svg
 
     Args:
         svg_file (Union[str, Path, TextIO]): svg file
         flip_y (bool, optional): flip objects to compensate for svg orientation. Defaults to True.
         ignore_visibility (bool, optional): Defaults to False.
-        label_by (str, optional): xml attribute. Defaults to "id".
-        is_inkscape_label (bool, optional): flag to indicate that the attribute
-            is an Inkscape label like `inkscape:label` - label_by would be set to
-            `label` in this case. Defaults to False.
+        label_by (str, optional): XML attribute to use for imported shapes' `label` property.
+            Defaults to "id".
+            Use `inkscape:label` to read labels set from Inkscape's "Layers and Objects" panel.
 
     Raises:
         ValueError: unexpected shape type
 
     Returns:
         ShapeList[Union[Wire, Face]]: objects contained in svg
     """
+    if is_inkscape_label is not None:  # TODO remove for `1.0` release
+        msg = "`is_inkscape_label` parameter is deprecated"
+        if is_inkscape_label:
+            label_by = "inkscape:" + label_by
+            msg += f", use `label_by={label_by!r}` instead"
+        warnings.warn(msg, stacklevel=2)
+
     shapes = []
-    label_by = (
-        "{http://www.inkscape.org/namespaces/inkscape}" + label_by
-        if is_inkscape_label
-        else label_by
+    label_by = re.sub(
+        r"^inkscape:(.+)", r"{http://www.inkscape.org/namespaces/inkscape}\1", label_by
     )
     for face_or_wire, color_and_label in import_svg_document(
         svg_file,

tests/test_importers.py

@@ -71,13 +71,9 @@ def test_import_svg_as_buildline_code_invalid_name(self):
 
     def test_import_svg(self):
         svg_file = Path(__file__).parent / "../tests/svg_import_test.svg"
-        for tag in ["id", "label"]:
+        for tag in ["id", "inkscape:label"]:
             # Import the svg object as a ShapeList
-            svg = import_svg(
-                svg_file,
-                label_by=tag,
-                is_inkscape_label=tag == "label",
-            )
+            svg = import_svg(svg_file, label_by=tag)
 
             # Exact the shape of the plate & holes
             base_faces = svg.filter_by(lambda f: "base" in f.label)
@@ -88,6 +84,24 @@ def test_import_svg(self):
             self.assertEqual(len(list(hole_faces)), 2)
             self.assertEqual(len(list(test_wires)), 1)
 
+    def test_import_svg_deprecated_param(self):  # TODO remove for `1.0` release
+        svg_file = Path(__file__).parent / "../tests/svg_import_test.svg"
+
+        with self.assertWarns(UserWarning):
+            svg = import_svg(svg_file, label_by="label", is_inkscape_label=True)
+
+            # Exact the shape of the plate & holes
+            base_faces = svg.filter_by(lambda f: "base" in f.label)
+            hole_faces = svg.filter_by(lambda f: "hole" in f.label)
+            test_wires = svg.filter_by(lambda f: "wire" in f.label)
+
+            self.assertEqual(len(list(base_faces)), 1)
+            self.assertEqual(len(list(hole_faces)), 2)
+            self.assertEqual(len(list(test_wires)), 1)
+
+        with self.assertWarns(UserWarning):
+            svg = import_svg(svg_file, is_inkscape_label=False)
+
     def test_import_svg_colors(self):
         svg_file = StringIO(
             '<svg xmlns="http://www.w3.org/2000/svg">'