You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
357 lines
10 KiB
Python
357 lines
10 KiB
Python
from __future__ import annotations
|
|
|
|
from collections.abc import Iterable
|
|
|
|
"""
|
|
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
|
|
# https://docs.microsoft.com/en-gb/windows/win32/fileio/naming-a-file#naming-conventions.
|
|
#
|
|
# 1. Integer value zero, sometimes referred to as the ASCII NUL character.
|
|
# 2. Characters whose integer representations are in the range 1 to 31,
|
|
# inclusive.
|
|
# 3. Various characters that (mostly) Windows and POSIX-y filesystems don't
|
|
# allow, plus "(" and ")", as per the specification.
|
|
illegalCharacters: set[str] = {
|
|
"\x00",
|
|
"\x01",
|
|
"\x02",
|
|
"\x03",
|
|
"\x04",
|
|
"\x05",
|
|
"\x06",
|
|
"\x07",
|
|
"\x08",
|
|
"\t",
|
|
"\n",
|
|
"\x0b",
|
|
"\x0c",
|
|
"\r",
|
|
"\x0e",
|
|
"\x0f",
|
|
"\x10",
|
|
"\x11",
|
|
"\x12",
|
|
"\x13",
|
|
"\x14",
|
|
"\x15",
|
|
"\x16",
|
|
"\x17",
|
|
"\x18",
|
|
"\x19",
|
|
"\x1a",
|
|
"\x1b",
|
|
"\x1c",
|
|
"\x1d",
|
|
"\x1e",
|
|
"\x1f",
|
|
'"',
|
|
"*",
|
|
"+",
|
|
"/",
|
|
":",
|
|
"<",
|
|
">",
|
|
"?",
|
|
"[",
|
|
"\\",
|
|
"]",
|
|
"(",
|
|
")",
|
|
"|",
|
|
"\x7f",
|
|
}
|
|
reservedFileNames: set[str] = {
|
|
"aux",
|
|
"clock$",
|
|
"com1",
|
|
"com2",
|
|
"com3",
|
|
"com4",
|
|
"com5",
|
|
"com6",
|
|
"com7",
|
|
"com8",
|
|
"com9",
|
|
"con",
|
|
"lpt1",
|
|
"lpt2",
|
|
"lpt3",
|
|
"lpt4",
|
|
"lpt5",
|
|
"lpt6",
|
|
"lpt7",
|
|
"lpt8",
|
|
"lpt9",
|
|
"nul",
|
|
"prn",
|
|
}
|
|
maxFileNameLength: int = 255
|
|
|
|
|
|
class NameTranslationError(Exception):
|
|
pass
|
|
|
|
|
|
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):
|
|
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: 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
|
|
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: 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)
|
|
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
|
|
|
|
doctest.testmod()
|