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

fontTools/ufoLib/kerning.py

@@ -1,52 +1,97 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from fontTools.annotations import KerningPair, KerningDict, KerningGroups, IntFloat
+
+StrDict = dict[str, str]
+
+
 def lookupKerningValue(
-    pair, kerning, groups, fallback=0, glyphToFirstGroup=None, glyphToSecondGroup=None
-):
-    """
-    Note: This expects kerning to be a flat dictionary
-    of kerning pairs, not the nested structure used
-    in kerning.plist.
+    pair: KerningPair,
+    kerning: KerningDict,
+    groups: KerningGroups,
+    fallback: IntFloat = 0,
+    glyphToFirstGroup: Optional[StrDict] = None,
+    glyphToSecondGroup: Optional[StrDict] = None,
+) -> IntFloat:
+    """Retrieve the kerning value (if any) between a pair of elements.
+
+    The elments can be either individual glyphs (by name) or kerning
+    groups (by name), or any combination of the two.
+
+    Args:
+      pair:
+          A tuple, in logical order (first, second) with respect
+          to the reading direction, to query the font for kerning
+          information on. Each element in the tuple can be either
+          a glyph name or a kerning group name.
+      kerning:
+          A dictionary of kerning pairs.
+      groups:
+          A set of kerning groups.
+      fallback:
+          The fallback value to return if no kern is found between
+          the elements in ``pair``. Defaults to 0.
+      glyphToFirstGroup:
+          A dictionary mapping glyph names to the first-glyph kerning
+          groups to which they belong. Defaults to ``None``.
+      glyphToSecondGroup:
+          A dictionary mapping glyph names to the second-glyph kerning
+          groups to which they belong. Defaults to ``None``.
+
+    Returns:
+      The kerning value between the element pair. If no kerning for
+      the pair is found, the fallback value is returned.
+
+    Note: This function expects the ``kerning`` argument to be a flat
+    dictionary of kerning pairs, not the nested structure used in a
+    kerning.plist file.
+
+    Examples::
 
-    >>> groups = {
-    ...     "public.kern1.O" : ["O", "D", "Q"],
-    ...     "public.kern2.E" : ["E", "F"]
-    ... }
-    >>> kerning = {
-    ...     ("public.kern1.O", "public.kern2.E") : -100,
-    ...     ("public.kern1.O", "F") : -200,
-    ...     ("D", "F") : -300
-    ... }
-    >>> lookupKerningValue(("D", "F"), kerning, groups)
-    -300
-    >>> lookupKerningValue(("O", "F"), kerning, groups)
-    -200
-    >>> lookupKerningValue(("O", "E"), kerning, groups)
-    -100
-    >>> lookupKerningValue(("O", "O"), kerning, groups)
-    0
-    >>> lookupKerningValue(("E", "E"), kerning, groups)
-    0
-    >>> lookupKerningValue(("E", "O"), kerning, groups)
-    0
-    >>> lookupKerningValue(("X", "X"), kerning, groups)
-    0
-    >>> lookupKerningValue(("public.kern1.O", "public.kern2.E"),
-    ...     kerning, groups)
-    -100
-    >>> lookupKerningValue(("public.kern1.O", "F"), kerning, groups)
-    -200
-    >>> lookupKerningValue(("O", "public.kern2.E"), kerning, groups)
-    -100
-    >>> lookupKerningValue(("public.kern1.X", "public.kern2.X"), kerning, groups)
-    0
+      >>> groups = {
+      ...     "public.kern1.O" : ["O", "D", "Q"],
+      ...     "public.kern2.E" : ["E", "F"]
+      ... }
+      >>> kerning = {
+      ...     ("public.kern1.O", "public.kern2.E") : -100,
+      ...     ("public.kern1.O", "F") : -200,
+      ...     ("D", "F") : -300
+      ... }
+      >>> lookupKerningValue(("D", "F"), kerning, groups)
+      -300
+      >>> lookupKerningValue(("O", "F"), kerning, groups)
+      -200
+      >>> lookupKerningValue(("O", "E"), kerning, groups)
+      -100
+      >>> lookupKerningValue(("O", "O"), kerning, groups)
+      0
+      >>> lookupKerningValue(("E", "E"), kerning, groups)
+      0
+      >>> lookupKerningValue(("E", "O"), kerning, groups)
+      0
+      >>> lookupKerningValue(("X", "X"), kerning, groups)
+      0
+      >>> lookupKerningValue(("public.kern1.O", "public.kern2.E"),
+      ...     kerning, groups)
+      -100
+      >>> lookupKerningValue(("public.kern1.O", "F"), kerning, groups)
+      -200
+      >>> lookupKerningValue(("O", "public.kern2.E"), kerning, groups)
+      -100
+      >>> lookupKerningValue(("public.kern1.X", "public.kern2.X"), kerning, groups)
+      0
     """
     # quickly check to see if the pair is in the kerning dictionary
     if pair in kerning:
         return kerning[pair]
+    # ensure both or no glyph-to-group mappings are provided
+    if (glyphToFirstGroup is None) != (glyphToSecondGroup is None):
+        raise ValueError(
+            "Must provide both 'glyphToFirstGroup' and 'glyphToSecondGroup', or neither."
+        )
     # create glyph to group mapping
-    if glyphToFirstGroup is not None:
-        assert glyphToSecondGroup is not None
-    if glyphToSecondGroup is not None:
-        assert glyphToFirstGroup is not None
     if glyphToFirstGroup is None:
         glyphToFirstGroup = {}
         glyphToSecondGroup = {}
@@ -57,25 +102,30 @@ def lookupKerningValue(
             elif group.startswith("public.kern2."):
                 for glyph in groupMembers:
                     glyphToSecondGroup[glyph] = group
+    # ensure type safety for mappings
+    assert glyphToFirstGroup is not None
+    assert glyphToSecondGroup is not None
     # get group names and make sure first and second are glyph names
     first, second = pair
     firstGroup = secondGroup = None
     if first.startswith("public.kern1."):
         firstGroup = first
-        first = None
+        firstGlyph = None
     else:
         firstGroup = glyphToFirstGroup.get(first)
+        firstGlyph = first
     if second.startswith("public.kern2."):
         secondGroup = second
-        second = None
+        secondGlyph = None
     else:
         secondGroup = glyphToSecondGroup.get(second)
+        secondGlyph = second
     # make an ordered list of pairs to look up
     pairs = [
-        (first, second),
-        (first, secondGroup),
-        (firstGroup, second),
-        (firstGroup, secondGroup),
+        (a, b)
+        for a in (firstGlyph, firstGroup)
+        for b in (secondGlyph, secondGroup)
+        if a is not None and b is not None
     ]
     # look up the pairs and return any matches
     for pair in pairs:

fontTools/ufoLib/utils.py

@@ -1,15 +1,26 @@
-"""The module contains miscellaneous helpers.
-It's not considered part of the public ufoLib API.
+"""This module contains miscellaneous helpers.
+
+It is not considered part of the public ufoLib API. It does, however,
+define the :py:obj:`.deprecated` decorator that is used elsewhere in
+the module.
 """
 
-import warnings
+from __future__ import annotations
+
+from typing import Optional, Type, TypeVar, Union, cast
+from collections.abc import Callable
+import enum
 import functools
+import warnings
 
+F = TypeVar("F", bound=Callable[..., object])
+FormatVersion = TypeVar("FormatVersion", bound="BaseFormatVersion")
+FormatVersionInput = Optional[Union[int, tuple[int, int], FormatVersion]]
 
 numberTypes = (int, float)
 
 
-def deprecated(msg=""):
+def deprecated(msg: str = "") -> Callable[[F], F]:
     """Decorator factory to mark functions as deprecated with given message.
 
     >>> @deprecated("Enough!")
@@ -22,7 +33,7 @@ def deprecated(msg=""):
     True
     """
 
-    def deprecated_decorator(func):
+    def deprecated_decorator(func: F) -> F:
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
             warnings.warn(
@@ -32,41 +43,61 @@ def deprecated(msg=""):
             )
             return func(*args, **kwargs)
 
-        return wrapper
+        return cast(F, wrapper)
 
     return deprecated_decorator
 
 
-# To be mixed with enum.Enum in UFOFormatVersion and GLIFFormatVersion
-class _VersionTupleEnumMixin:
+def normalizeFormatVersion(
+    value: FormatVersionInput, cls: Type[FormatVersion]
+) -> FormatVersion:
+    # Needed for type safety of UFOFormatVersion and GLIFFormatVersion input
+    if value is None:
+        return cls.default()
+    if isinstance(value, cls):
+        return value
+    if isinstance(value, int):
+        return cls((value, 0))
+    if isinstance(value, tuple) and len(value) == 2:
+        return cls(value)
+    raise ValueError(f"Unsupported format version: {value!r}")
+
+
+# Base class for UFOFormatVersion and GLIFFormatVersion
+class BaseFormatVersion(tuple[int, int], enum.Enum):
+    value: tuple[int, int]
+
+    def __new__(cls: Type[FormatVersion], value: tuple[int, int]) -> BaseFormatVersion:
+        return super().__new__(cls, value)
+
     @property
-    def major(self):
+    def major(self) -> int:
         return self.value[0]
 
     @property
-    def minor(self):
+    def minor(self) -> int:
         return self.value[1]
 
     @classmethod
-    def _missing_(cls, value):
+    def _missing_(cls, value: object) -> BaseFormatVersion:
         # allow to initialize a version enum from a single (major) integer
         if isinstance(value, int):
             return cls((value, 0))
         # or from None to obtain the current default version
         if value is None:
             return cls.default()
-        return super()._missing_(value)
+        raise ValueError(f"{value!r} is not a valid {cls.__name__}")
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"{self.major}.{self.minor}"
 
     @classmethod
-    def default(cls):
+    def default(cls: Type[FormatVersion]) -> FormatVersion:
         # get the latest defined version (i.e. the max of all versions)
         return max(cls.__members__.values())
 
     @classmethod
-    def supported_versions(cls):
+    def supported_versions(cls: Type[FormatVersion]) -> frozenset[FormatVersion]:
         return frozenset(cls.__members__.values())