svg-ultralight 0.64.0__py3-none-any.whl

svg_ultralight/layout.py

@@ -0,0 +1,291 @@
+"""Manage inferences for pad_ and dpu_ arguments.
+
+:author: Shay Hill
+:created: 2023-02-12
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeAlias
+
+from svg_ultralight.string_conversion import format_number
+from svg_ultralight.unit_conversion import Measurement, MeasurementArg
+
+PadArg: TypeAlias = float | str | Measurement | Sequence[float | str | Measurement]
+
+
+def expand_pad_arg(pad: PadArg) -> tuple[float, float, float, float]:
+    """Transform a single value or tuple of values to a 4-tuple of user units.
+
+    :param pad: padding value(s)
+    :return: 4-tuple of padding values in (scaled) user units
+
+    >>> expand_pad_arg(1)
+    (1.0, 1.0, 1.0, 1.0)
+
+    >>> expand_pad_arg((1, 2))
+    (1.0, 2.0, 1.0, 2.0)
+
+    >>> expand_pad_arg("1in")
+    (96.0, 96.0, 96.0, 96.0)
+
+    >>> expand_pad_arg(("1in", "2in"))
+    (96.0, 192.0, 96.0, 192.0)
+
+    >>> expand_pad_arg(Measurement("1in"))
+    (96.0, 96.0, 96.0, 96.0)
+
+    >>> 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]
+
+
+def pad_viewbox(
+    viewbox: tuple[float, float, float, float], pads: tuple[float, float, float, float]
+) -> tuple[float, float, float, float]:
+    """Expand viewbox by padding.
+
+    :param viewbox: viewbox to pad (x, y, width height)
+    :param pads: padding (top, right, bottom, left)
+    :return: padded viewbox
+    """
+    x, y, width, height = viewbox
+    top, right, bottom, left = pads
+    return x - left, y - top, width + left + right, height + top + bottom
+
+
+def _scale_pads(
+    pads: tuple[float, float, float, float], scale: float
+) -> tuple[float, float, float, float]:
+    """Scale padding by a factor.
+
+    :param pads: padding to scale (top, right, bottom, left)
+    :param scale: factor to scale by
+    :return: scaled padding
+    """
+    top, right, bottom, left = pads
+    return top * scale, right * scale, bottom * scale, left * scale
+
+
+def _infer_scale(
+    print_h: Measurement, print_w: Measurement, viewbox_h: float, viewbox_w: float
+) -> float:
+    """Determine size of viewbox units.
+
+    :param print_h: height of print area
+    :param print_w: width of print area
+    :param viewbox_h: height of viewbox
+    :param viewbox_w: width of viewbox
+    :return: scale factor to apply to viewbox to match print area
+    :raises ValueError: if no valid scale can be determined
+
+    If one of width or height cannot be used, will defer to the other.
+
+    Will ignore ONE, but not both of these conditions:
+    * print_w > 0 / viewbox_w == 0
+    * print_h > 0 / viewbox_h == 0
+
+    Any potential scale would be infinite, so this raises a ValueError
+
+    Will ignore ONE, but not both of these conditions:
+    * print_w == 0 / viewbox_w > 0
+    * print_h == 0 / viewbox_h > 0
+
+    The print area is invalid, but there is special handling for this. Interpret
+    viewbox units as print_w.native_unit and determe print area from viewbox area 1
+    to 1.
+
+        >>> _infer_scale(Measurement("in"), Measurement("in"), 1, 2)
+        96
+
+    Will additionally raise a ValueError for any negative measurement.
+
+    Scaling is safe for zero values. If both are zero, the scaling will be 1.
+    Padding might add a non-zero value to width or height later, producing a valid
+    viewbox, but that isn't guaranteed here.
+    """
+    if any(x < 0 for x in (print_h.value, print_w.value, viewbox_h, viewbox_w)):
+        msg = "Negative values are not allowed"
+        raise ValueError(msg)
+
+    candidate_scales: set[float] = set()
+    if print_w.value and viewbox_w:
+        candidate_scales.add(print_w.value / viewbox_w)
+    if print_h.value and viewbox_h:
+        candidate_scales.add(print_h.value / viewbox_h)
+    if candidate_scales:
+        # size of picture is determined by print area
+        return min(candidate_scales)
+    if any([print_w.value, print_h.value]):
+        msg = "All potential scales would be infinite."
+        raise ValueError(msg)
+    # a print unit was given, but not a print size. Size of picture is determined
+    # by interpreting viewbox dimensions as print_width or print_height units
+    return print_w.native_unit.value[1]
+
+
+def pad_and_scale(
+    viewbox: tuple[float, float, float, float],
+    pad: PadArg,
+    print_width: MeasurementArg | None = None,
+    print_height: MeasurementArg | None = None,
+    dpu: float = 1,
+) -> tuple[tuple[float, float, float, float], dict[str, float | str]]:
+    """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
+        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.
+    :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")
+    :param print_height: height of print area, in user units (float), a string
+        with a unit specifier (e.g., "452mm"), or just a unit specifier (e.g.,
+        "pt")
+    :param dpu: scale the print units. This is useful when you want to print the
+        same image at different sizes.
+    :return: padded viewbox 4-tuple and scaling attributes
+
+    SVGs are built in "user units". An optional width and height (not the
+    viewbox with and height, these are separate arguments) define the size of
+    those user units.
+
+    * If the width and height are not specified, the user units are 1 pixel
+      (1/96th of an inch).
+
+    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 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.
+
+    To pad around the viewbox, we need to first figure out what the user units
+    are then scale the padding so it will print (or display) correctly. For
+    instance, if
+
+    * the viewbox width is 3;
+    * the width argument is "1yd"; and
+    * the pad argument is "1in"
+
+    the printed result will be 38" wide. That's 1yd for the width plus 1 inch of
+    padding on each side. The viewbox will have 1/12 of a unit (3 user units
+    over 1 yard = 1 foot per user unit) added on each side.
+
+    Ideally, we know the size of the print or display area from the beginning
+    and build the geometry out at whatever size we want, so no scaling is
+    necessarily required. Even that won't always work, because some software
+    doesn't like "user units" and insists on 'pt' or 'in'. If everything is
+    already in 'pt' or 'in' and you want to keep it that way, just call the
+    function with print_width="pt" or print_height="in". The function will add
+    the unit designators without changing the scale.
+
+    Print aspect ratio is ignored. Viewbox aspect ratio is preserved. For
+    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 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
+      one argument is None). These will always match the viewbox aspect ratio,
+      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".
+
+    * 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
+      print_width and print_height are both 100, giving a 1:1 aspect ratio, the
+      output scaling attributes will be {"width": "100", "height", "56.25"},
+      preserving viewbox aspect ratio with a "best fit" scaling (i.e, the image
+      is as large as it can be without exceeding the specified print area).
+
+    You can pass something impossible like a viewbox width of 1 and a print box
+    of 0. The function will give up, set scaling to 1, and pad the viewbox. This
+    does not try to guard against bad values sent to lxml.
+
+    All of the above is important when you want your padding in real-world units
+    (e.g., when you need to guarantee a certain amount of padding above and
+    below an image in a book layout). However, it does add some complexity,
+    because aspect ratio is not maintained when print_width increases. Worse, if
+    there is some geomtry like a background pattern in your padding, then more
+    or less of that pattern will be visible depending on the print_width.
+
+    That's not hard to work around, just change the padding every time you
+    change the width. Or, to make it even simpler, use the dpu argument. The dpu
+    argument will scale the width and the padding together. So, you can produce
+    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 wide and twice as high) as the 16" x 9" image.
+    """
+    pads = expand_pad_arg(pad)
+
+    # no print information given, pad and return viewbox
+    if print_width is None and print_height is None:
+        padded = pad_viewbox(viewbox, pads)
+        dims: dict[str, float | str] = {}
+        if dpu != 1:
+            dims["width"] = format_number(padded[2] * dpu)
+            dims["height"] = format_number(padded[3] * dpu)
+        return padded, dims
+
+    _, _, viewbox_w, viewbox_h = viewbox
+    print_w = Measurement(print_width or 0)
+    print_h = Measurement(print_height or 0)
+
+    # match unspecified (None) width or height units.
+    if print_width is None:
+        print_w.native_unit = print_h.native_unit
+    elif print_height is None:
+        print_h.native_unit = print_w.native_unit
+
+    scale = _infer_scale(print_h, print_w, viewbox_h, viewbox_w)
+
+    print_w.value = viewbox_w * scale
+    print_h.value = viewbox_h * scale
+
+    # add padding and increase print area
+    print_w.value += pads[1] + pads[3]
+    print_h.value += pads[0] + pads[2]
+
+    # scale pads to viewbox to match input size when later scaled to print area
+    padded_viewbox = pad_viewbox(viewbox, _scale_pads(pads, 1 / scale))
+    return padded_viewbox, {
+        "width": (print_w * dpu).get_svg(print_w.native_unit),
+        "height": (print_h * dpu).get_svg(print_h.native_unit),
+    }

svg_ultralight/main.py

@@ -0,0 +1,183 @@
+r"""Simple functions to LIGHTLY assist in creating Scalable Vector Graphics.
+
+:author: Shay Hill
+created: 10/7/2019
+
+Some functions here require a path to an Inkscape executable on your filesystem.
+IMPORTANT: path cannot end with ``.exe``.
+Use something like ``"C:\\Program Files\\Inkscape\\inkscape"``
+
+Inkscape changed their command-line interface with version 1.0. These functions
+should work with all Inkscape versions. Please report any issues.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+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.nsmap import NSMAP
+from svg_ultralight.string_conversion import get_view_box_str, svg_tostring
+
+if TYPE_CHECKING:
+    import os
+
+    from lxml.etree import (
+        _Element as EtreeElement,  # pyright: ignore[reportPrivateUsage]
+    )
+
+    from svg_ultralight.attrib_hints import ElemAttrib, OptionalElemAttribMapping
+    from svg_ultralight.layout import PadArg
+
+
+def _is_io_bytes(obj: object) -> TypeGuard[IO[bytes]]:
+    """Determine if an object is file-like.
+
+    :param obj: object
+    :return: True if object is file-like
+    """
+    return hasattr(obj, "read") and hasattr(obj, "write")
+
+
+def new_svg_root(
+    x_: float | None = None,
+    y_: float | None = None,
+    width_: float | None = None,
+    height_: float | None = None,
+    *,
+    pad_: PadArg = 0,
+    print_width_: float | str | None = None,
+    print_height_: float | str | None = None,
+    dpu_: float = 1,
+    nsmap: dict[str | None, str] | None = None,
+    attrib: OptionalElemAttribMapping | None = None,
+    **attributes: ElemAttrib,
+) -> EtreeElement:
+    """Create an svg root element from viewBox style parameters.
+
+    :param x_: x value in upper-left corner
+    :param y_: y value in upper-left corner
+    :param width_: width of viewBox
+    :param height_: height of viewBox
+    :param pad_: optionally increase viewBox by pad in all directions. Acceps a
+        single value or a tuple of values applied to (cycled over) top, right,
+        bottom, left. pad can be floats or dimension strings*
+    :param print_width_: optionally explicitly set unpadded width in units
+        (float) or a dimension string*
+    :param print_height_: optionally explicitly set unpadded height in units
+        (float) or a dimension string*
+    :param dpu_: dots per unit. Scale the output by this factor. This is
+        different from print_width_ and print_height_ in that dpu_ scales the
+        *padded* output.
+    :param nsmap: optionally pass a namespace map of your choosing
+    :param attrib: optionally pass additional attributes as a mapping instead of as
+        anonymous kwargs. This is useful for pleasing the linter when unpacking a
+        dictionary into a function call.
+    :param attributes: element attribute names and values
+    :return: root svg element
+
+    * dimension strings are strings with a float value and a unit. Valid units
+      are formatted as "1in", "2cm", or "3mm".
+
+    All viewBox-style (trailing underscore) parameters are optional. Any kwargs
+    will be passed to ``etree.Element`` as element parameters. These will
+    supercede any parameters inferred from the trailing underscore parameters.
+    """
+    attributes.update(attrib or {})
+    if nsmap is None:
+        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))
+    ):
+        padded_viewbox, scale_attribs = pad_and_scale(
+            (x_, y_, width_, height_), pad_, print_width_, print_height_, dpu_
+        )
+        inferred_attribs["viewBox"] = get_view_box_str(*padded_viewbox)
+        inferred_attribs.update(scale_attribs)
+    inferred_attribs.update(attributes)
+    # can only pass nsmap on instance creation
+    svg_root = etree.Element(f"{{{nsmap[None]}}}svg", nsmap=nsmap)
+    return update_element(svg_root, **inferred_attribs)
+
+
+def write_svg(
+    svg: str | Path | IO[bytes],
+    root: EtreeElement,
+    stylesheet: str | os.PathLike[str] | None = None,
+    *,
+    do_link_css: bool = False,
+    **tostring_kwargs: str | bool,
+) -> str:
+    r"""Write an xml element as an svg file.
+
+    :param svg: open binary file object or path to output file (include extension .svg)
+    :param root: root node of your svg geometry
+    :param stylesheet: optional path to css stylesheet
+    :param do_link_css: link to stylesheet, else (default) write contents of stylesheet
+        into svg (ignored if stylesheet is None)
+    :param tostring_kwargs: keyword arguments to etree.tostring. xml_header=True for
+        sensible default values. See below.
+    :return: svg filename
+    :effects: creates svg file at ``svg``
+    :raises TypeError: if ``svg`` is not a Path, str, or binary file object
+
+    It's often useful to write a temporary svg file, so a tempfile.NamedTemporaryFile
+    object (or any open binary file object can be passed instead of an svg filename).
+
+    You may never need an xml_header. Inkscape doesn't need it, your browser doesn't
+    need it, and it's forbidden if you'd like to "inline" your svg in an html file.
+    The most pressing need might be to set an encoding. If you pass
+    ``xml_declaration=True`` as a tostring_kwarg, this function will attempt to pass
+    the following defaults to ``lxml.etree.tostring``:
+
+    * doctype: str = (
+        '<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"\n'
+        '"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">'
+    )
+    * encoding = "UTF-8"
+
+    Always, this function will default to ``pretty_print=True``
+
+    These can be overridden by tostring_kwargs.
+
+    e.g., ``write_svg(..., xml_declaration=True, doctype=None``)
+    e.g., ``write_svg(..., xml_declaration=True, encoding='ascii')``
+
+    ``lxml.etree.tostring`` is documented here: https://lxml.de/api/index.html,
+    but I know that to be incomplete as of 2020 Feb 01, as it does not document the
+    (perhaps important to you) 'encoding' kwarg.
+    """
+    if stylesheet is not None:
+        if do_link_css is True:
+            parent = Path(str(svg)).parent
+            relative_css_path = Path(stylesheet).relative_to(parent)
+            link = etree.PI(
+                "xml-stylesheet", f'href="{relative_css_path}" type="text/css"'
+            )
+            root.addprevious(link)
+        else:
+            style = etree.Element("style", type="text/css")
+            with Path(stylesheet).open(encoding="utf-8") as css_file:
+                style.text = etree.CDATA("\n" + "".join(css_file.readlines()) + "\n")
+            root.insert(0, style)
+
+    svg_contents = svg_tostring(root, **tostring_kwargs)
+
+    if _is_io_bytes(svg):
+        _ = svg.write(svg_contents)
+        return svg.name
+    if isinstance(svg, (str, Path)):
+        with Path(svg).open("wb") as svg_file:
+            _ = svg_file.write(svg_contents)
+        return str(svg)
+    msg = f"svg must be a path-like object or a file-like object, not {type(svg)}"
+    raise TypeError(msg)

svg_ultralight/metadata.py

@@ -0,0 +1,122 @@
+"""Add metadata exactly as Inkscape formats it.
+
+See https://paladini.github.io/dublin-core-basics/ for a description of the metadata
+fields.
+
+:author: Shay Hill
+:created: 2024-01-29
+"""
+
+import warnings
+
+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
+
+_KNOWN_METADATA_FIELDS = {
+    # tags in both Dublin Core and the Inkscape interface
+    "title",
+    "date",
+    "creator",
+    "rights",
+    "publisher",
+    "identifier",
+    "source",
+    "relation",
+    "language",
+    "coverage",
+    "description",
+    "contributor",
+    # *almost* in both. This is "contributors" in the Inkscape interface. Output as
+    # "contributor".
+    "contributors",
+    # tags in Dublin Core but not the Inkscape interface.
+    "subject",
+    "type",
+    "format",
+    # tags in the Inkscape interface but not Dublin Core
+    "keywords",  # Inkscape alias for "subject". Will be subject in the output.
+}
+
+
+def _wrap_agent(title: str) -> EtreeElement:
+    """Create nested elements for creator, rights, publisher, and contributors.
+
+    :param title: The text to put in the nested element.
+    :return: an agent element to be places in a dc:creator, dc:rights, dc:publisher,
+        or dc:contributors element.
+
+    This is the way Inkscape formats these fields.
+    """
+    agent = new_element(new_qname("cc", "Agent"))
+    _ = new_sub_element(agent, new_qname("dc", "title"), text=title)
+    return agent
+
+
+def _wrap_bag(title: str) -> EtreeElement:
+    """Create nested elements for keywords.
+
+    :param title: The text to put in the nested element.
+    :return: an agent element to be places in a dc:subject element.
+
+    This is the way Inkscape formats these fields. Keywords are put in a subject
+    element.
+    """
+    items = title.split(",")
+    agent = new_element(new_qname("rdf", "Bag"))
+    for title_item in items:
+        _ = new_sub_element(agent, new_qname("rdf", "li"), text=title_item)
+    return agent
+
+
+def new_metadata(**kwargs: str) -> EtreeElement:
+    """Return a new metadata string.
+
+    :param kwargs: The metadata fields to include.
+
+    This is the way Inkscape formats metadata. If you create a metadata element,
+    svg_ultralight will create an empty `dc:title` element even if no title keyword
+    is passed.
+
+    The following keywords can be used without a warning:
+    title, date, creator, rights, publisher, identifier, source, relation, language,
+    coverage, description, contributor, contributors, subject, type, format, keywords.
+
+    Only the keywords `keywords` and `subject` accept treat comma-delimited strings
+    as multiple values. Every other value will be treated as a single string. You can
+    pass other fields. They will be included as
+    `<dc:other_field>value</dc:other_field>`.
+
+    Will hardcode the id to "metadata1" because that's what Inkscape does. If that
+    doesn't satisfy, replace id after description.
+    """
+    for tag in kwargs:
+        if tag not in _KNOWN_METADATA_FIELDS:
+            msg = f"Unknown metadata field: {tag}"
+            warnings.warn(msg, stacklevel=2)
+
+    metadata = new_element("metadata", id_="metadata1")
+    rdf = new_sub_element(metadata, new_qname("rdf", "RDF"))
+    work = new_sub_element(rdf, new_qname("cc", "Work"), **{"rdf:about": ""})
+
+    _ = new_sub_element(work, new_qname("dc", "title"), text=kwargs.pop("title", ""))
+    for k, v in kwargs.items():
+        tag = k
+        # aliases
+        if tag == "contributors":
+            tag = "contributor"
+        elif tag == "subject":
+            tag = "keywords"
+
+        if tag in {"creator", "rights", "publisher", "contributor"}:
+            elem = new_sub_element(work, new_qname("dc", tag))
+            elem.append(_wrap_agent(v))
+            continue
+        if tag == "keywords":
+            elem = new_sub_element(work, new_qname("dc", "subject"))
+            elem.append(_wrap_bag(v))
+            continue
+        _ = new_sub_element(work, new_qname("dc", tag), text=v)
+
+    return metadata

svg_ultralight/nsmap.py

@@ -0,0 +1,36 @@
+"""xml namespace entries for svg files.
+
+:author: Shay Hill
+:created: 1/14/2021
+
+I started by copying out entries from Inkscape output. Added more as I found them
+necessary. This is a pretty robust list. Can be pared down as documented at
+https://shayallenhill.com/svg-with-css-in-python/
+"""
+
+from __future__ import annotations
+
+from lxml.etree import QName
+
+_SVG_NAMESPACE = "http://www.w3.org/2000/svg"
+NSMAP = {
+    None: _SVG_NAMESPACE,
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "cc": "http://creativecommons.org/ns#",
+    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    "svg": _SVG_NAMESPACE,
+    "xlink": "http://www.w3.org/1999/xlink",
+    "sodipodi": "http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd",
+    "inkscape": "http://www.inkscape.org/namespaces/inkscape",
+}
+
+
+def new_qname(namespace_abbreviation: str | None, tag: str) -> QName:
+    """Create a qualified name for an svg element.
+
+    :param namespace_abbreviation: The namespace abbreviation. This
+        will have to be a key in NSMAP (e.g., "dc", "cc", "rdf").
+    :param tag: The tag name of the element.
+    :return: A qualified name for the element.
+    """
+    return QName(NSMAP[namespace_abbreviation], tag)

svg_ultralight/py.typed

@@ -0,0 +1,5 @@
+""" This file is used to indicate to mypy that the package is typed.
+
+Do not delete this comment, because empty files choke
+some cloud drives on sync.
+"""