fonttools 4.60.2__cp311-cp311-win32.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/filesystem/__init__.py

@@ -0,0 +1,68 @@
+"""Minimal, stdlib-only replacement for [`pyfilesystem2`][1] API for use by `fontTools.ufoLib`.
+
+This package is a partial reimplementation of the `fs` package by Will McGugan, used under the
+MIT license. See LICENSE.external for details.
+
+Note this only exports a **subset** of the `pyfilesystem2` API, in particular the modules,
+classes and functions that are currently used directly by `fontTools.ufoLib`.
+
+It opportunistically tries to import the relevant modules from the upstream `fs` package
+when this is available. Otherwise it falls back to the replacement modules within this package.
+
+As of version 4.59.0, the `fonttools[ufo]` extra no longer requires the `fs` package, thus
+this `fontTools.misc.filesystem` package is used by default.
+
+Client code can either replace `import fs` with `from fontTools.misc import filesystem as fs`
+if that happens to work (no guarantee), or they can continue to use `fs` but they will have
+to specify it as an explicit dependency of their project.
+
+[1]: https://github.com/PyFilesystem/pyfilesystem2
+"""
+
+from __future__ import annotations
+
+try:
+    __import__("fs")
+except ImportError:
+    from . import _base as base
+    from . import _copy as copy
+    from . import _errors as errors
+    from . import _info as info
+    from . import _osfs as osfs
+    from . import _path as path
+    from . import _subfs as subfs
+    from . import _tempfs as tempfs
+    from . import _tools as tools
+    from . import _walk as walk
+    from . import _zipfs as zipfs
+
+    _haveFS = False
+else:
+    import fs.base as base
+    import fs.copy as copy
+    import fs.errors as errors
+    import fs.info as info
+    import fs.osfs as osfs
+    import fs.path as path
+    import fs.subfs as subfs
+    import fs.tempfs as tempfs
+    import fs.tools as tools
+    import fs.walk as walk
+    import fs.zipfs as zipfs
+
+    _haveFS = True
+
+
+__all__ = [
+    "base",
+    "copy",
+    "errors",
+    "info",
+    "osfs",
+    "path",
+    "subfs",
+    "tempfs",
+    "tools",
+    "walk",
+    "zipfs",
+]

fontTools/misc/filesystem/_base.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import typing
+from abc import ABC, abstractmethod
+
+from ._copy import copy_dir, copy_file
+from ._errors import (
+    DestinationExists,
+    DirectoryExpected,
+    FileExpected,
+    FilesystemClosed,
+    NoSysPath,
+    ResourceNotFound,
+)
+from ._path import dirname
+from ._walk import BoundWalker
+
+if typing.TYPE_CHECKING:
+    from typing import IO, Any, Collection, Iterator, Self, Type
+
+    from ._info import Info
+    from ._subfs import SubFS
+
+
+class FS(ABC):
+    """Abstract base class for custom filesystems."""
+
+    _closed: bool = False
+
+    @abstractmethod
+    def open(self, path: str, mode: str = "rb", **kwargs) -> IO[Any]: ...
+
+    @abstractmethod
+    def exists(self, path: str) -> bool: ...
+
+    @abstractmethod
+    def isdir(self, path: str) -> bool: ...
+
+    @abstractmethod
+    def isfile(self, path: str) -> bool: ...
+
+    @abstractmethod
+    def listdir(self, path: str) -> list[str]: ...
+
+    @abstractmethod
+    def makedir(self, path: str, recreate: bool = False) -> SubFS: ...
+
+    @abstractmethod
+    def makedirs(self, path: str, recreate: bool = False) -> SubFS: ...
+
+    @abstractmethod
+    def getinfo(self, path: str, namespaces: Collection[str] | None = None) -> Info: ...
+
+    @abstractmethod
+    def remove(self, path: str) -> None: ...
+
+    @abstractmethod
+    def removedir(self, path: str) -> None: ...
+
+    @abstractmethod
+    def removetree(self, path: str) -> None: ...
+
+    @abstractmethod
+    def movedir(self, src: str, dst: str, create: bool = False) -> None: ...
+
+    def getsyspath(self, path: str) -> str:
+        raise NoSysPath(f"the filesystem {self!r} has no system path")
+
+    def close(self):
+        self._closed = True
+
+    def isclosed(self) -> bool:
+        return self._closed
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False  # never swallow exceptions
+
+    def check(self):
+        if self._closed:
+            raise FilesystemClosed(f"the filesystem {self!r} is closed")
+
+    def opendir(self, path: str, *, factory: Type[SubFS] | None = None) -> SubFS:
+        """Return a sub‑filesystem rooted at `path`."""
+        if factory is None:
+            from ._subfs import SubFS
+
+            factory = SubFS
+        return factory(self, path)
+
+    def scandir(
+        self, path: str, namespaces: Collection[str] | None = None
+    ) -> Iterator[Info]:
+        return (self.getinfo(f"{path}/{p}", namespaces) for p in self.listdir(path))
+
+    @property
+    def walk(self) -> BoundWalker:
+        return BoundWalker(self)
+
+    def readbytes(self, path: str) -> bytes:
+        with self.open(path, "rb") as f:
+            return f.read()
+
+    def writebytes(self, path: str, data: bytes):
+        with self.open(path, "wb") as f:
+            f.write(data)
+
+    def create(self, path: str, wipe: bool = False):
+        if not wipe and self.exists(path):
+            return False
+        with self.open(path, "wb"):
+            pass  # 'touch' empty file
+        return True
+
+    def copy(self, src_path: str, dst_path: str, overwrite=False):
+        if not self.exists(src_path):
+            raise ResourceNotFound(f"{src_path!r} does not exist")
+        elif not self.isfile(src_path):
+            raise FileExpected(f"path {src_path!r} should be a file")
+        if not overwrite and self.exists(dst_path):
+            raise DestinationExists(f"destination {dst_path!r} already exists")
+        if not self.isdir(dirname(dst_path)):
+            raise DirectoryExpected(f"path {dirname(dst_path)!r} should be a directory")
+        copy_file(self, src_path, self, dst_path)
+
+    def copydir(self, src_path: str, dst_path: str, create=False):
+        if not create and not self.exists(dst_path):
+            raise ResourceNotFound(f"{dst_path!r} does not exist")
+        if not self.isdir(src_path):
+            raise DirectoryExpected(f"path {src_path!r} should be a directory")
+        copy_dir(self, src_path, self, dst_path)

fontTools/misc/filesystem/_copy.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import typing
+
+from ._errors import IllegalDestination
+from ._path import combine, frombase, isbase
+from ._tools import copy_file_data
+
+if typing.TYPE_CHECKING:
+    from ._base import FS
+
+
+def copy_file(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str):
+    if src_fs is dst_fs and src_path == dst_path:
+        raise IllegalDestination(f"cannot copy {src_path!r} to itself")
+
+    with src_fs.open(src_path, "rb") as src_file:
+        with dst_fs.open(dst_path, "wb") as dst_file:
+            copy_file_data(src_file, dst_file)
+
+
+def copy_structure(
+    src_fs: FS,
+    dst_fs: FS,
+    src_root: str = "/",
+    dst_root: str = "/",
+):
+    if src_fs is dst_fs and isbase(src_root, dst_root):
+        raise IllegalDestination(f"cannot copy {src_fs!r} to itself")
+
+    dst_fs.makedirs(dst_root, recreate=True)
+    for dir_path in src_fs.walk.dirs(src_root):
+        dst_fs.makedir(combine(dst_root, frombase(src_root, dir_path)), recreate=True)
+
+
+def copy_dir(src_fs: FS, src_path: str, dst_fs: FS, dst_path: str):
+    copy_structure(src_fs, dst_fs, src_path, dst_path)
+
+    for file_path in src_fs.walk.files(src_path):
+        copy_path = combine(dst_path, frombase(src_path, file_path))
+        copy_file(src_fs, file_path, dst_fs, copy_path)
+
+
+def copy_fs(src_fs: FS, dst_fs: FS):
+    copy_dir(src_fs, "/", dst_fs, "/")

fontTools/misc/filesystem/_errors.py

@@ -0,0 +1,54 @@
+class FSError(Exception):
+    pass
+
+
+class CreateFailed(FSError):
+    pass
+
+
+class FilesystemClosed(FSError):
+    pass
+
+
+class MissingInfoNamespace(FSError):
+    pass
+
+
+class NoSysPath(FSError):
+    pass
+
+
+class OperationFailed(FSError):
+    pass
+
+
+class IllegalDestination(OperationFailed):
+    pass
+
+
+class ResourceError(FSError):
+    pass
+
+
+class ResourceNotFound(ResourceError):
+    pass
+
+
+class DirectoryExpected(ResourceError):
+    pass
+
+
+class DirectoryNotEmpty(ResourceError):
+    pass
+
+
+class FileExpected(ResourceError):
+    pass
+
+
+class DestinationExists(ResourceError):
+    pass
+
+
+class ResourceReadOnly(ResourceError):
+    pass

fontTools/misc/filesystem/_info.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import typing
+from datetime import datetime, timezone
+
+from ._errors import MissingInfoNamespace
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Mapping
+    from typing import Any
+
+
+def epoch_to_datetime(t: int | None) -> datetime | None:
+    """Convert epoch time to a UTC datetime."""
+    if t is None:
+        return None
+    return datetime.fromtimestamp(t, tz=timezone.utc)
+
+
+class Info:
+    __slots__ = ["raw", "namespaces"]
+
+    def __init__(self, raw_info: Mapping[str, Any]):
+        self.raw = raw_info
+        self.namespaces = frozenset(raw_info.keys())
+
+    def get(self, namespace: str, key: str, default: Any | None = None) -> Any | None:
+        try:
+            return self.raw[namespace].get(key, default)
+        except KeyError:
+            raise MissingInfoNamespace(f"Namespace {namespace!r} does not exist")
+
+    @property
+    def name(self) -> str:
+        return self.get("basic", "name")
+
+    @property
+    def is_dir(self) -> bool:
+        return self.get("basic", "is_dir")
+
+    @property
+    def is_file(self) -> bool:
+        return not self.is_dir
+
+    @property
+    def accessed(self) -> datetime | None:
+        return epoch_to_datetime(self.get("details", "accessed"))
+
+    @property
+    def modified(self) -> datetime | None:
+        return epoch_to_datetime(self.get("details", "modified"))
+
+    @property
+    def size(self) -> int | None:
+        return self.get("details", "size")
+
+    @property
+    def type(self) -> int | None:
+        return self.get("details", "type")
+
+    @property
+    def created(self) -> datetime | None:
+        return epoch_to_datetime(self.get("details", "created"))
+
+    @property
+    def metadata_changed(self) -> datetime | None:
+        return epoch_to_datetime(self.get("details", "metadata_changed"))
+
+    def __str__(self) -> str:
+        if self.is_dir:
+            return "<dir '{}'>".format(self.name)
+        else:
+            return "<file '{}'>".format(self.name)
+
+    __repr__ = __str__