fonttools 4.58.3__cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

fontTools/misc/filenames.py

@@ -0,0 +1,245 @@
+"""
+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
+"""
+
+illegalCharacters = r"\" * + / : < > ? [ \ ] | \0".split(" ")
+illegalCharacters += [chr(i) for i in range(1, 32)]
+illegalCharacters += [chr(0x7F)]
+reservedFileNames = "CON PRN AUX CLOCK$ NUL A:-Z: COM1".lower().split(" ")
+reservedFileNames += "LPT1 LPT2 LPT3 COM2 COM3 COM4".lower().split(" ")
+maxFileNameLength = 255
+
+
+class NameTranslationError(Exception):
+    pass
+
+
+def userNameToFileName(userName, existing=[], prefix="", suffix=""):
+    """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 str
+    if not isinstance(userName, str):
+        raise ValueError("The value for userName must be a string.")
+    # establish the prefix and suffix lengths
+    prefixLength = len(prefix)
+    suffixLength = len(suffix)
+    # replace an initial period with an _
+    # if no prefix is to be added
+    if not prefix and userName[0] == ".":
+        userName = "_" + userName[1:]
+    # filter the user name
+    filteredUserName = []
+    for character in userName:
+        # replace illegal characters with _
+        if character in illegalCharacters:
+            character = "_"
+        # add _ to all non-lower characters
+        elif character != character.lower():
+            character += "_"
+        filteredUserName.append(character)
+    userName = "".join(filteredUserName)
+    # clip to 255
+    sliceLength = maxFileNameLength - prefixLength - suffixLength
+    userName = userName[:sliceLength]
+    # test for illegal files names
+    parts = []
+    for part in userName.split("."):
+        if part.lower() in reservedFileNames:
+            part = "_" + part
+        parts.append(part)
+    userName = ".".join(parts)
+    # test for clash
+    fullName = prefix + userName + suffix
+    if fullName.lower() in existing:
+        fullName = handleClash1(userName, existing, prefix, suffix)
+    # finished
+    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
+    """
+    # 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
+    prefixLength = len(prefix)
+    suffixLength = len(suffix)
+    if prefixLength + len(userName) + suffixLength + 15 > maxFileNameLength:
+        l = prefixLength + len(userName) + suffixLength + 15
+        sliceLength = maxFileNameLength - l
+        userName = userName[:sliceLength]
+    finalName = None
+    # try to add numbers to create a unique name
+    counter = 1
+    while finalName is None:
+        name = userName + str(counter).zfill(15)
+        fullName = prefix + name + suffix
+        if fullName.lower() not in existing:
+            finalName = fullName
+            break
+        else:
+            counter += 1
+        if counter >= 999999999999999:
+            break
+    # if there is a clash, go to the next fallback
+    if finalName is None:
+        finalName = handleClash2(existing, prefix, suffix)
+    # finished
+    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
+    """
+    # calculate the longest possible string
+    maxLength = maxFileNameLength - len(prefix) - len(suffix)
+    maxValue = int("9" * maxLength)
+    # try to find a number
+    finalName = None
+    counter = 1
+    while finalName is None:
+        fullName = prefix + str(counter) + suffix
+        if fullName.lower() not in existing:
+            finalName = fullName
+            break
+        else:
+            counter += 1
+        if counter >= maxValue:
+            break
+    # raise an error if nothing has been found
+    if finalName is None:
+        raise NameTranslationError("No unique name could be found.")
+    # finished
+    return finalName
+
+
+if __name__ == "__main__":
+    import doctest
+    import sys
+
+    sys.exit(doctest.testmod().failed)

fontTools/misc/fixedTools.py

@@ -0,0 +1,253 @@
+"""
+The `OpenType specification <https://docs.microsoft.com/en-us/typography/opentype/spec/otff#data-types>`_
+defines two fixed-point data types:
+
+``Fixed``
+	A 32-bit signed fixed-point number with a 16 bit twos-complement
+	magnitude component and 16 fractional bits.
+``F2DOT14``
+	A 16-bit signed fixed-point number with a 2 bit twos-complement
+	magnitude component and 14 fractional bits.
+
+To support reading and writing data with these data types, this module provides
+functions for converting between fixed-point, float and string representations.
+
+.. data:: MAX_F2DOT14
+
+	The maximum value that can still fit in an F2Dot14. (1.99993896484375)
+"""
+
+from .roundTools import otRound, nearestMultipleShortestRepr
+import logging
+
+log = logging.getLogger(__name__)
+
+__all__ = [
+    "MAX_F2DOT14",
+    "fixedToFloat",
+    "floatToFixed",
+    "floatToFixedToFloat",
+    "floatToFixedToStr",
+    "fixedToStr",
+    "strToFixed",
+    "strToFixedToFloat",
+    "ensureVersionIsLong",
+    "versionToFixed",
+]
+
+
+MAX_F2DOT14 = 0x7FFF / (1 << 14)
+
+
+def fixedToFloat(value, precisionBits):
+    """Converts a fixed-point number to a float given the number of
+    precision bits.
+
+    Args:
+            value (int): Number in fixed-point format.
+            precisionBits (int): Number of precision bits.
+
+    Returns:
+            Floating point value.
+
+    Examples::
+
+            >>> import math
+            >>> f = fixedToFloat(-10139, precisionBits=14)
+            >>> math.isclose(f, -0.61883544921875)
+            True
+    """
+    return value / (1 << precisionBits)
+
+
+def floatToFixed(value, precisionBits):
+    """Converts a float to a fixed-point number given the number of
+    precision bits.
+
+    Args:
+            value (float): Floating point value.
+            precisionBits (int): Number of precision bits.
+
+    Returns:
+            int: Fixed-point representation.
+
+    Examples::
+
+            >>> floatToFixed(-0.61883544921875, precisionBits=14)
+            -10139
+            >>> floatToFixed(-0.61884, precisionBits=14)
+            -10139
+    """
+    return otRound(value * (1 << precisionBits))
+
+
+def floatToFixedToFloat(value, precisionBits):
+    """Converts a float to a fixed-point number and back again.
+
+    By converting the float to fixed, rounding it, and converting it back
+    to float again, this returns a floating point values which is exactly
+    representable in fixed-point format.
+
+    Note: this **is** equivalent to ``fixedToFloat(floatToFixed(value))``.
+
+    Args:
+            value (float): The input floating point value.
+            precisionBits (int): Number of precision bits.
+
+    Returns:
+            float: The transformed and rounded value.
+
+    Examples::
+            >>> import math
+            >>> f1 = -0.61884
+            >>> f2 = floatToFixedToFloat(-0.61884, precisionBits=14)
+            >>> f1 != f2
+            True
+            >>> math.isclose(f2, -0.61883544921875)
+            True
+    """
+    scale = 1 << precisionBits
+    return otRound(value * scale) / scale
+
+
+def fixedToStr(value, precisionBits):
+    """Converts a fixed-point number to a string representing a decimal float.
+
+    This chooses the float that has the shortest decimal representation (the least
+    number of fractional decimal digits).
+
+    For example, to convert a fixed-point number in a 2.14 format, use
+    ``precisionBits=14``::
+
+            >>> fixedToStr(-10139, precisionBits=14)
+            '-0.61884'
+
+    This is pretty slow compared to the simple division used in ``fixedToFloat``.
+    Use sporadically when you need to serialize or print the fixed-point number in
+    a human-readable form.
+    It uses nearestMultipleShortestRepr under the hood.
+
+    Args:
+            value (int): The fixed-point value to convert.
+            precisionBits (int): Number of precision bits, *up to a maximum of 16*.
+
+    Returns:
+            str: A string representation of the value.
+    """
+    scale = 1 << precisionBits
+    return nearestMultipleShortestRepr(value / scale, factor=1.0 / scale)
+
+
+def strToFixed(string, precisionBits):
+    """Converts a string representing a decimal float to a fixed-point number.
+
+    Args:
+            string (str): A string representing a decimal float.
+            precisionBits (int): Number of precision bits, *up to a maximum of 16*.
+
+    Returns:
+            int: Fixed-point representation.
+
+    Examples::
+
+            >>> ## to convert a float string to a 2.14 fixed-point number:
+            >>> strToFixed('-0.61884', precisionBits=14)
+            -10139
+    """
+    value = float(string)
+    return otRound(value * (1 << precisionBits))
+
+
+def strToFixedToFloat(string, precisionBits):
+    """Convert a string to a decimal float with fixed-point rounding.
+
+    This first converts string to a float, then turns it into a fixed-point
+    number with ``precisionBits`` fractional binary digits, then back to a
+    float again.
+
+    This is simply a shorthand for fixedToFloat(floatToFixed(float(s))).
+
+    Args:
+            string (str): A string representing a decimal float.
+            precisionBits (int): Number of precision bits.
+
+    Returns:
+            float: The transformed and rounded value.
+
+    Examples::
+
+            >>> import math
+            >>> s = '-0.61884'
+            >>> bits = 14
+            >>> f = strToFixedToFloat(s, precisionBits=bits)
+            >>> math.isclose(f, -0.61883544921875)
+            True
+            >>> f == fixedToFloat(floatToFixed(float(s), precisionBits=bits), precisionBits=bits)
+            True
+    """
+    value = float(string)
+    scale = 1 << precisionBits
+    return otRound(value * scale) / scale
+
+
+def floatToFixedToStr(value, precisionBits):
+    """Convert float to string with fixed-point rounding.
+
+    This uses the shortest decimal representation (ie. the least
+    number of fractional decimal digits) to represent the equivalent
+    fixed-point number with ``precisionBits`` fractional binary digits.
+    It uses nearestMultipleShortestRepr under the hood.
+
+    >>> floatToFixedToStr(-0.61883544921875, precisionBits=14)
+    '-0.61884'
+
+    Args:
+            value (float): The float value to convert.
+            precisionBits (int): Number of precision bits, *up to a maximum of 16*.
+
+    Returns:
+            str: A string representation of the value.
+
+    """
+    scale = 1 << precisionBits
+    return nearestMultipleShortestRepr(value, factor=1.0 / scale)
+
+
+def ensureVersionIsLong(value):
+    """Ensure a table version is an unsigned long.
+
+    OpenType table version numbers are expressed as a single unsigned long
+    comprising of an unsigned short major version and unsigned short minor
+    version. This function detects if the value to be used as a version number
+    looks too small (i.e. is less than ``0x10000``), and converts it to
+    fixed-point using :func:`floatToFixed` if so.
+
+    Args:
+            value (Number): a candidate table version number.
+
+    Returns:
+            int: A table version number, possibly corrected to fixed-point.
+    """
+    if value < 0x10000:
+        newValue = floatToFixed(value, 16)
+        log.warning(
+            "Table version value is a float: %.4f; " "fix to use hex instead: 0x%08x",
+            value,
+            newValue,
+        )
+        value = newValue
+    return value
+
+
+def versionToFixed(value):
+    """Ensure a table version number is fixed-point.
+
+    Args:
+            value (str): a candidate table version number.
+
+    Returns:
+            int: A table version number, possibly corrected to fixed-point.
+    """
+    value = int(value, 0) if value.startswith("0") else float(value)
+    value = ensureVersionIsLong(value)
+    return value

fontTools/misc/intTools.py

@@ -0,0 +1,25 @@
+__all__ = ["popCount", "bit_count", "bit_indices"]
+
+
+try:
+    bit_count = int.bit_count
+except AttributeError:
+
+    def bit_count(v):
+        return bin(v).count("1")
+
+
+"""Return number of 1 bits (population count) of the absolute value of an integer.
+
+See https://docs.python.org/3.10/library/stdtypes.html#int.bit_count
+"""
+popCount = bit_count  # alias
+
+
+def bit_indices(v):
+    """Return list of indices where bits are set, 0 being the index of the least significant bit.
+
+    >>> bit_indices(0b101)
+    [0, 2]
+    """
+    return [i for i, b in enumerate(bin(v)[::-1]) if b == "1"]

fontTools/misc/iterTools.py

@@ -0,0 +1,12 @@
+from itertools import *
+
+# Python 3.12:
+if "batched" not in globals():
+    # https://docs.python.org/3/library/itertools.html#itertools.batched
+    def batched(iterable, n):
+        # batched('ABCDEFG', 3) --> ABC DEF G
+        if n < 1:
+            raise ValueError("n must be at least one")
+        it = iter(iterable)
+        while batch := tuple(islice(it, n)):
+            yield batch

fontTools/misc/lazyTools.py

@@ -0,0 +1,42 @@
+from collections import UserDict, UserList
+
+__all__ = ["LazyDict", "LazyList"]
+
+
+class LazyDict(UserDict):
+    def __init__(self, data):
+        super().__init__()
+        self.data = data
+
+    def __getitem__(self, k):
+        v = self.data[k]
+        if callable(v):
+            v = v(k)
+            self.data[k] = v
+        return v
+
+
+class LazyList(UserList):
+    def __getitem__(self, k):
+        if isinstance(k, slice):
+            indices = range(*k.indices(len(self)))
+            return [self[i] for i in indices]
+        v = self.data[k]
+        if callable(v):
+            v = v(k)
+            self.data[k] = v
+        return v
+
+    def __add__(self, other):
+        if isinstance(other, LazyList):
+            other = list(other)
+        elif isinstance(other, list):
+            pass
+        else:
+            return NotImplemented
+        return list(self) + other
+
+    def __radd__(self, other):
+        if not isinstance(other, list):
+            return NotImplemented
+        return other + list(self)