fonttools 4.57.0__cp313-cp313-macosx_10_13_universal2.whl → 4.58.1__cp313-cp313-macosx_10_13_universal2.whl

fontTools/ufoLib/filenames.py

@@ -1,6 +1,22 @@
 """
-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
@@ -93,53 +109,69 @@ class NameTranslationError(Exception):
 
 
 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
+    """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):
@@ -181,33 +213,42 @@ def userNameToFileName(userName: str, existing=(), prefix="", suffix=""):
 
 
 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
+    """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
@@ -238,30 +279,44 @@ def handleClash1(userName, existing=[], prefix="", suffix=""):
 
 
 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
+    """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)

fontTools/ufoLib/glifLib.py

@@ -1,11 +1,11 @@
 """
-glifLib.py -- Generic module for reading and writing the .glif format.
+Generic module for reading and writing the .glif format.
 
 More info about the .glif format (GLyphInterchangeFormat) can be found here:
 
 	http://unifiedfontobject.org
 
-The main class in this module is GlyphSet. It manages a set of .glif files
+The main class in this module is :class:`GlyphSet`. It manages a set of .glif files
 in a folder. It offers two ways to read glyph data, and one way to write
 glyph data. See the class doc string for details.
 """
@@ -60,6 +60,13 @@ LAYERINFO_FILENAME = "layerinfo.plist"
 
 
 class GLIFFormatVersion(tuple, _VersionTupleEnumMixin, enum.Enum):
+    """Class representing the versions of the .glif format supported by the UFO version in use.
+
+    For a given :mod:`fontTools.ufoLib.UFOFormatVersion`, the :func:`supported_versions` method will
+    return the supported versions of the GLIF file format. If the UFO version is unspecified, the
+    :func:`supported_versions` method will return all available GLIF format versions.
+    """
+
     FORMAT_1_0 = (1, 0)
     FORMAT_2_0 = (2, 0)
 

fontTools/ufoLib/kerning.py

@@ -1,43 +1,73 @@
 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.
+    """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:

fontTools/ufoLib/utils.py

@@ -1,5 +1,8 @@
-"""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