fonttools 4.55.4__cp313-cp313-musllinux_1_2_aarch64.whl → 4.61.1__cp313-cp313-musllinux_1_2_aarch64.whl

fontTools/ufoLib/converters.py

@@ -1,11 +1,42 @@
+from __future__ import annotations
+
+from typing import Mapping, Any
+from collections.abc import Container
+
+from fontTools.annotations import KerningNested
+
 """
-Conversion functions.
+Functions for converting UFO1 or UFO2 files into UFO3 format.
+
+Currently provides functionality for converting kerning rules
+and kerning groups. Conversion is only supported _from_ UFO1
+or UFO2, and _to_ UFO3.
 """
 
 # adapted from the UFO spec
 
 
-def convertUFO1OrUFO2KerningToUFO3Kerning(kerning, groups, glyphSet=()):
+def convertUFO1OrUFO2KerningToUFO3Kerning(
+    kerning: KerningNested, groups: dict[str, list[str]], glyphSet: Container[str] = ()
+) -> tuple[KerningNested, dict[str, list[str]], dict[str, dict[str, str]]]:
+    """Convert kerning data in UFO1 or UFO2 syntax into UFO3 syntax.
+
+    Args:
+      kerning:
+          A dictionary containing the kerning rules defined in
+          the UFO font, as used in :class:`.UFOReader` objects.
+      groups:
+          A dictionary containing the groups defined in the UFO
+          font, as used in :class:`.UFOReader` objects.
+      glyphSet:
+        Optional; a set of glyph objects to skip (default: None).
+
+    Returns:
+      1. A dictionary representing the converted kerning data.
+      2. A copy of the groups dictionary, with all groups renamed to UFO3 syntax.
+      3. A dictionary containing the mapping of old group names to new group names.
+
+    """
     # gather known kerning groups based on the prefixes
     firstReferencedGroups, secondReferencedGroups = findKnownKerningGroups(groups)
     # Make lists of groups referenced in kerning pairs.
@@ -18,7 +49,7 @@ def convertUFO1OrUFO2KerningToUFO3Kerning(kerning, groups, glyphSet=()):
                 if not second.startswith("public.kern2."):
                     secondReferencedGroups.add(second)
     # Create new names for these groups.
-    firstRenamedGroups = {}
+    firstRenamedGroups: dict[str, str] = {}
     for first in firstReferencedGroups:
         # Make a list of existing group names.
         existingGroupNames = list(groups.keys()) + list(firstRenamedGroups.keys())
@@ -30,7 +61,7 @@ def convertUFO1OrUFO2KerningToUFO3Kerning(kerning, groups, glyphSet=()):
         newName = makeUniqueGroupName(newName, existingGroupNames)
         # Store for use later.
         firstRenamedGroups[first] = newName
-    secondRenamedGroups = {}
+    secondRenamedGroups: dict[str, str] = {}
     for second in secondReferencedGroups:
         # Make a list of existing group names.
         existingGroupNames = list(groups.keys()) + list(secondRenamedGroups.keys())
@@ -62,36 +93,55 @@ def convertUFO1OrUFO2KerningToUFO3Kerning(kerning, groups, glyphSet=()):
     return newKerning, groups, dict(side1=firstRenamedGroups, side2=secondRenamedGroups)
 
 
-def findKnownKerningGroups(groups):
-    """
-    This will find kerning groups with known prefixes.
-    In some cases not all kerning groups will be referenced
-    by the kerning pairs. The algorithm for locating groups
-    in convertUFO1OrUFO2KerningToUFO3Kerning will miss these
-    unreferenced groups. By scanning for known prefixes
+def findKnownKerningGroups(groups: Mapping[str, Any]) -> tuple[set[str], set[str]]:
+    """Find all kerning groups in a UFO1 or UFO2 font that use known prefixes.
+
+    In some cases, not all kerning groups will be referenced
+    by the kerning pairs in a UFO. The algorithm for locating
+    groups in :func:`convertUFO1OrUFO2KerningToUFO3Kerning` will
+    miss these unreferenced groups. By scanning for known prefixes,
     this function will catch all of the prefixed groups.
 
-    These are the prefixes and sides that are handled:
+    The prefixes and sides by this function are:
+
     @MMK_L_ - side 1
     @MMK_R_ - side 2
 
-    >>> testGroups = {
-    ...     "@MMK_L_1" : None,
-    ...     "@MMK_L_2" : None,
-    ...     "@MMK_L_3" : None,
-    ...     "@MMK_R_1" : None,
-    ...     "@MMK_R_2" : None,
-    ...     "@MMK_R_3" : None,
-    ...     "@MMK_l_1" : None,
-    ...     "@MMK_r_1" : None,
-    ...     "@MMK_X_1" : None,
-    ...     "foo" : None,
-    ... }
-    >>> first, second = findKnownKerningGroups(testGroups)
-    >>> sorted(first) == ['@MMK_L_1', '@MMK_L_2', '@MMK_L_3']
-    True
-    >>> sorted(second) == ['@MMK_R_1', '@MMK_R_2', '@MMK_R_3']
-    True
+    as defined in the UFO1 specification.
+
+    Args:
+        groups:
+          A dictionary containing the groups defined in the UFO
+          font, as read by :class:`.UFOReader`.
+
+    Returns:
+        Two sets; the first containing the names of all
+        first-side kerning groups identified in the ``groups``
+        dictionary, and the second containing the names of all
+        second-side kerning groups identified.
+
+        "First-side" and "second-side" are with respect to the
+        writing direction of the script.
+
+        Example::
+
+          >>> testGroups = {
+          ...     "@MMK_L_1" : None,
+          ...     "@MMK_L_2" : None,
+          ...     "@MMK_L_3" : None,
+          ...     "@MMK_R_1" : None,
+          ...     "@MMK_R_2" : None,
+          ...     "@MMK_R_3" : None,
+          ...     "@MMK_l_1" : None,
+          ...     "@MMK_r_1" : None,
+          ...     "@MMK_X_1" : None,
+          ...     "foo" : None,
+          ... }
+          >>> first, second = findKnownKerningGroups(testGroups)
+          >>> sorted(first) == ['@MMK_L_1', '@MMK_L_2', '@MMK_L_3']
+          True
+          >>> sorted(second) == ['@MMK_R_1', '@MMK_R_2', '@MMK_R_3']
+          True
     """
     knownFirstGroupPrefixes = ["@MMK_L_"]
     knownSecondGroupPrefixes = ["@MMK_R_"]
@@ -109,7 +159,28 @@ def findKnownKerningGroups(groups):
     return firstGroups, secondGroups
 
 
-def makeUniqueGroupName(name, groupNames, counter=0):
+def makeUniqueGroupName(name: str, groupNames: list[str], counter: int = 0) -> str:
+    """Make a kerning group name that will be unique within the set of group names.
+
+    If the requested kerning group name already exists within the set, this
+    will return a new name by adding an incremented counter to the end
+    of the requested name.
+
+    Args:
+        name:
+          The requested kerning group name.
+        groupNames:
+          A list of the existing kerning group names.
+        counter:
+          Optional; a counter of group names already seen (default: 0). If
+          :attr:`.counter` is not provided, the function will recurse,
+          incrementing the value of :attr:`.counter` until it finds the
+          first unused ``name+counter`` combination, and return that result.
+
+    Returns:
+        A unique kerning group name composed of the requested name suffixed
+        by the smallest available integer counter.
+    """
     # Add a number to the name if the counter is higher than zero.
     newName = name
     if counter > 0:
@@ -123,6 +194,8 @@ def makeUniqueGroupName(name, groupNames, counter=0):
 
 def test():
     """
+    Tests for :func:`.convertUFO1OrUFO2KerningToUFO3Kerning`.
+
     No known prefixes.
 
     >>> testKerning = {

fontTools/ufoLib/errors.py

@@ -10,6 +10,14 @@ class UnsupportedUFOFormat(UFOLibError):
 
 
 class GlifLibError(UFOLibError):
+    """An error raised by glifLib.
+
+    This class is a loose backport of PEP 678, adding a :attr:`.note`
+    attribute that can hold additional context for errors encountered.
+
+    It will be maintained until only Python 3.11-and-later are supported.
+    """
+
     def _add_note(self, note: str) -> None:
         # Loose backport of PEP 678 until we only support Python 3.11+, used for
         # adding additional context to errors.

fontTools/ufoLib/etree.py

@@ -1,5 +1,5 @@
 """DEPRECATED - This module is kept here only as a backward compatibility shim
-for the old ufoLib.etree module, which was moved to fontTools.misc.etree.
+for the old ufoLib.etree module, which was moved to :mod:`fontTools.misc.etree`.
 Please use the latter instead.
 """
 

fontTools/ufoLib/filenames.py

@@ -1,6 +1,26 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
 """
-User name to file name conversion.
-This was taken from the UFO 3 spec.
+Convert user-provided internal UFO names to spec-compliant filenames.
+
+This module implements the algorithm for converting between a "user name" -
+something that a user can choose arbitrarily inside a font editor - and a file
+name suitable for use in a wide range of operating systems and filesystems.
+
+The `UFO 3 specification <http://unifiedfontobject.org/versions/ufo3/conventions/>`_
+provides an example of an algorithm for such conversion, which avoids illegal
+characters, reserved file names, ambiguity between upper- and lower-case
+characters, and clashes with existing files.
+
+This code was originally copied from
+`ufoLib <https://github.com/unified-font-object/ufoLib/blob/8747da7/Lib/ufoLib/filenames.py>`_
+by Tal Leming and is copyright (c) 2005-2016, The RoboFab Developers:
+
+-	Erik van Blokland
+-	Tal Leming
+-	Just van Rossum
 """
 
 # Restrictions are taken mostly from
@@ -11,7 +31,7 @@ This was taken from the UFO 3 spec.
 #    inclusive.
 # 3. Various characters that (mostly) Windows and POSIX-y filesystems don't
 #    allow, plus "(" and ")", as per the specification.
-illegalCharacters = {
+illegalCharacters: set[str] = {
     "\x00",
     "\x01",
     "\x02",
@@ -60,7 +80,7 @@ illegalCharacters = {
     "|",
     "\x7f",
 }
-reservedFileNames = {
+reservedFileNames: set[str] = {
     "aux",
     "clock$",
     "com1",
@@ -85,61 +105,79 @@ reservedFileNames = {
     "nul",
     "prn",
 }
-maxFileNameLength = 255
+maxFileNameLength: int = 255
 
 
 class NameTranslationError(Exception):
     pass
 
 
-def userNameToFileName(userName: str, existing=(), prefix="", suffix=""):
-    """
-    `existing` should be a set-like object.
-
-    >>> userNameToFileName("a") == "a"
-    True
-    >>> userNameToFileName("A") == "A_"
-    True
-    >>> userNameToFileName("AE") == "A_E_"
-    True
-    >>> userNameToFileName("Ae") == "A_e"
-    True
-    >>> userNameToFileName("ae") == "ae"
-    True
-    >>> userNameToFileName("aE") == "aE_"
-    True
-    >>> userNameToFileName("a.alt") == "a.alt"
-    True
-    >>> userNameToFileName("A.alt") == "A_.alt"
-    True
-    >>> userNameToFileName("A.Alt") == "A_.A_lt"
-    True
-    >>> userNameToFileName("A.aLt") == "A_.aL_t"
-    True
-    >>> userNameToFileName(u"A.alT") == "A_.alT_"
-    True
-    >>> userNameToFileName("T_H") == "T__H_"
-    True
-    >>> userNameToFileName("T_h") == "T__h"
-    True
-    >>> userNameToFileName("t_h") == "t_h"
-    True
-    >>> userNameToFileName("F_F_I") == "F__F__I_"
-    True
-    >>> userNameToFileName("f_f_i") == "f_f_i"
-    True
-    >>> userNameToFileName("Aacute_V.swash") == "A_acute_V_.swash"
-    True
-    >>> userNameToFileName(".notdef") == "_notdef"
-    True
-    >>> userNameToFileName("con") == "_con"
-    True
-    >>> userNameToFileName("CON") == "C_O_N_"
-    True
-    >>> userNameToFileName("con.alt") == "_con.alt"
-    True
-    >>> userNameToFileName("alt.con") == "alt._con"
-    True
+def userNameToFileName(
+    userName: str, existing: Iterable[str] = (), prefix: str = "", suffix: str = ""
+) -> str:
+    """Converts from a user name to a file name.
+
+    Takes care to avoid illegal characters, reserved file names, ambiguity between
+    upper- and lower-case characters, and clashes with existing files.
+
+    Args:
+            userName (str): The input file name.
+            existing: A case-insensitive list of all existing file names.
+            prefix: Prefix to be prepended to the file name.
+            suffix: Suffix to be appended to the file name.
+
+    Returns:
+            A suitable filename.
+
+    Raises:
+            NameTranslationError: If no suitable name could be generated.
+
+    Examples::
+
+            >>> userNameToFileName("a") == "a"
+            True
+            >>> userNameToFileName("A") == "A_"
+            True
+            >>> userNameToFileName("AE") == "A_E_"
+            True
+            >>> userNameToFileName("Ae") == "A_e"
+            True
+            >>> userNameToFileName("ae") == "ae"
+            True
+            >>> userNameToFileName("aE") == "aE_"
+            True
+            >>> userNameToFileName("a.alt") == "a.alt"
+            True
+            >>> userNameToFileName("A.alt") == "A_.alt"
+            True
+            >>> userNameToFileName("A.Alt") == "A_.A_lt"
+            True
+            >>> userNameToFileName("A.aLt") == "A_.aL_t"
+            True
+            >>> userNameToFileName(u"A.alT") == "A_.alT_"
+            True
+            >>> userNameToFileName("T_H") == "T__H_"
+            True
+            >>> userNameToFileName("T_h") == "T__h"
+            True
+            >>> userNameToFileName("t_h") == "t_h"
+            True
+            >>> userNameToFileName("F_F_I") == "F__F__I_"
+            True
+            >>> userNameToFileName("f_f_i") == "f_f_i"
+            True
+            >>> userNameToFileName("Aacute_V.swash") == "A_acute_V_.swash"
+            True
+            >>> userNameToFileName(".notdef") == "_notdef"
+            True
+            >>> userNameToFileName("con") == "_con"
+            True
+            >>> userNameToFileName("CON") == "C_O_N_"
+            True
+            >>> userNameToFileName("con.alt") == "_con.alt"
+            True
+            >>> userNameToFileName("alt.con") == "alt._con"
+            True
     """
     # the incoming name must be a string
     if not isinstance(userName, str):
@@ -180,34 +218,45 @@ def userNameToFileName(userName: str, existing=(), prefix="", suffix=""):
     return fullName
 
 
-def handleClash1(userName, existing=[], prefix="", suffix=""):
-    """
-    existing should be a case-insensitive list
-    of all existing file names.
-
-    >>> prefix = ("0" * 5) + "."
-    >>> suffix = "." + ("0" * 10)
-    >>> existing = ["a" * 5]
-
-    >>> e = list(existing)
-    >>> handleClash1(userName="A" * 5, existing=e,
-    ...		prefix=prefix, suffix=suffix) == (
-    ... 	'00000.AAAAA000000000000001.0000000000')
-    True
-
-    >>> e = list(existing)
-    >>> e.append(prefix + "aaaaa" + "1".zfill(15) + suffix)
-    >>> handleClash1(userName="A" * 5, existing=e,
-    ...		prefix=prefix, suffix=suffix) == (
-    ... 	'00000.AAAAA000000000000002.0000000000')
-    True
-
-    >>> e = list(existing)
-    >>> e.append(prefix + "AAAAA" + "2".zfill(15) + suffix)
-    >>> handleClash1(userName="A" * 5, existing=e,
-    ...		prefix=prefix, suffix=suffix) == (
-    ... 	'00000.AAAAA000000000000001.0000000000')
-    True
+def handleClash1(
+    userName: str, existing: Iterable[str] = [], prefix: str = "", suffix: str = ""
+) -> str:
+    """A helper function that resolves collisions with existing names when choosing a filename.
+
+    This function attempts to append an unused integer counter to the filename.
+
+        Args:
+                userName (str): The input file name.
+                existing: A case-insensitive list of all existing file names.
+                prefix: Prefix to be prepended to the file name.
+                suffix: Suffix to be appended to the file name.
+
+        Returns:
+                A suitable filename.
+
+        >>> prefix = ("0" * 5) + "."
+        >>> suffix = "." + ("0" * 10)
+        >>> existing = ["a" * 5]
+
+        >>> e = list(existing)
+        >>> handleClash1(userName="A" * 5, existing=e,
+        ...		prefix=prefix, suffix=suffix) == (
+        ... 	'00000.AAAAA000000000000001.0000000000')
+        True
+
+        >>> e = list(existing)
+        >>> e.append(prefix + "aaaaa" + "1".zfill(15) + suffix)
+        >>> handleClash1(userName="A" * 5, existing=e,
+        ...		prefix=prefix, suffix=suffix) == (
+        ... 	'00000.AAAAA000000000000002.0000000000')
+        True
+
+        >>> e = list(existing)
+        >>> e.append(prefix + "AAAAA" + "2".zfill(15) + suffix)
+        >>> handleClash1(userName="A" * 5, existing=e,
+        ...		prefix=prefix, suffix=suffix) == (
+        ... 	'00000.AAAAA000000000000001.0000000000')
+        True
     """
     # if the prefix length + user name length + suffix length + 15 is at
     # or past the maximum length, silce 15 characters off of the user name
@@ -237,31 +286,47 @@ def handleClash1(userName, existing=[], prefix="", suffix=""):
     return finalName
 
 
-def handleClash2(existing=[], prefix="", suffix=""):
-    """
-    existing should be a case-insensitive list
-    of all existing file names.
-
-    >>> prefix = ("0" * 5) + "."
-    >>> suffix = "." + ("0" * 10)
-    >>> existing = [prefix + str(i) + suffix for i in range(100)]
-
-    >>> e = list(existing)
-    >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
-    ... 	'00000.100.0000000000')
-    True
-
-    >>> e = list(existing)
-    >>> e.remove(prefix + "1" + suffix)
-    >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
-    ... 	'00000.1.0000000000')
-    True
-
-    >>> e = list(existing)
-    >>> e.remove(prefix + "2" + suffix)
-    >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
-    ... 	'00000.2.0000000000')
-    True
+def handleClash2(
+    existing: Iterable[str] = [], prefix: str = "", suffix: str = ""
+) -> str:
+    """A helper function that resolves collisions with existing names when choosing a filename.
+
+    This function is a fallback to :func:`handleClash1`. It attempts to append an unused integer counter to the filename.
+
+        Args:
+                userName (str): The input file name.
+                existing: A case-insensitive list of all existing file names.
+                prefix: Prefix to be prepended to the file name.
+                suffix: Suffix to be appended to the file name.
+
+        Returns:
+                A suitable filename.
+
+        Raises:
+                NameTranslationError: If no suitable name could be generated.
+
+        Examples::
+
+          >>> prefix = ("0" * 5) + "."
+          >>> suffix = "." + ("0" * 10)
+          >>> existing = [prefix + str(i) + suffix for i in range(100)]
+
+          >>> e = list(existing)
+          >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
+          ... 	'00000.100.0000000000')
+          True
+
+          >>> e = list(existing)
+          >>> e.remove(prefix + "1" + suffix)
+          >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
+          ... 	'00000.1.0000000000')
+          True
+
+          >>> e = list(existing)
+          >>> e.remove(prefix + "2" + suffix)
+          >>> handleClash2(existing=e, prefix=prefix, suffix=suffix) == (
+          ... 	'00000.2.0000000000')
+          True
     """
     # calculate the longest possible string
     maxLength = maxFileNameLength - len(prefix) - len(suffix)