# Source code for fontTools.ufoLib.glifLib

    """
    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 :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.
    """

    from __future__ import annotations

    import logging
    from collections import OrderedDict
    from typing import TYPE_CHECKING, Any, Optional, Union, cast
    from warnings import warn

    import fontTools.misc.filesystem as fs
    from fontTools.misc import etree, plistlib
    from fontTools.misc.textTools import tobytes
    from fontTools.pens.pointPen import AbstractPointPen, PointToSegmentPen
    from fontTools.ufoLib import UFOFormatVersion, _UFOBaseIO
    from fontTools.ufoLib.errors import GlifLibError
    from fontTools.ufoLib.filenames import userNameToFileName
    from fontTools.ufoLib.utils import (
        BaseFormatVersion,
        normalizeFormatVersion,
        numberTypes,
    )
    from fontTools.ufoLib.validators import (
        anchorsValidator,
        colorValidator,
        genericTypeValidator,
        glyphLibValidator,
        guidelinesValidator,
        identifierValidator,
        imageValidator,
    )

    if TYPE_CHECKING:
        from collections.abc import Callable, Iterable, Set
        from logging import Logger

        from fontTools.annotations import (
            ElementType,
            FormatVersion,
            FormatVersions,
            GLIFFormatVersionInput,
            GlyphNameToFileNameFunc,
            IntFloat,
            PathOrFS,
            UFOFormatVersionInput,
        )
        from fontTools.misc.filesystem._base import FS

    __all__: list[str] = [
        "GlyphSet",
        "GlifLibError",
        "readGlyphFromString",
        "writeGlyphToString",
        "glyphNameToFileName",
    ]

    logger: Logger = logging.getLogger(__name__)

    # ---------
    # Constants
    # ---------

    CONTENTS_FILENAME = "contents.plist"
    LAYERINFO_FILENAME = "layerinfo.plist"

    class GLIFFormatVersion(BaseFormatVersion):
        """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)

        @classmethod
        def default(
            cls, ufoFormatVersion: Optional[UFOFormatVersion] = None
        ) -> GLIFFormatVersion:
            if ufoFormatVersion is not None:
                return max(cls.supported_versions(ufoFormatVersion))
            return super().default()

        @classmethod
        def supported_versions(
            cls, ufoFormatVersion: Optional[UFOFormatVersion] = None
        ) -> frozenset[GLIFFormatVersion]:
            if ufoFormatVersion is None:
                # if ufo format unspecified, return all the supported GLIF formats
                return super().supported_versions()
            # else only return the GLIF formats supported by the given UFO format
            versions = {cls.FORMAT_1_0}
            if ufoFormatVersion >= UFOFormatVersion.FORMAT_3_0:
                versions.add(cls.FORMAT_2_0)
            return frozenset(versions)

    # ------------
    # Simple Glyph
    # ------------

    class Glyph:
        """
        Minimal glyph object. It has no glyph attributes until either
        the draw() or the drawPoints() method has been called.
        """

        def __init__(self, glyphName: str, glyphSet: GlyphSet) -> None:
            self.glyphName: str = glyphName
            self.glyphSet: GlyphSet = glyphSet

        def draw(self, pen: Any, outputImpliedClosingLine: bool = False) -> None:
            """
            Draw this glyph onto a *FontTools* Pen.
            """
            pointPen = PointToSegmentPen(
                pen, outputImpliedClosingLine=outputImpliedClosingLine
            )
            self.drawPoints(pointPen)

        def drawPoints(self, pointPen: AbstractPointPen) -> None:
            """
            Draw this glyph onto a PointPen.
            """
            self.glyphSet.readGlyph(self.glyphName, self, pointPen)

    # ---------
    # Glyph Set
    # ---------

    class GlyphSet(_UFOBaseIO):
        """
        GlyphSet manages a set of .glif files inside one directory.

        GlyphSet's constructor takes a path to an existing directory as it's
        first argument. Reading glyph data can either be done through the
        readGlyph() method, or by using GlyphSet's dictionary interface, where
        the keys are glyph names and the values are (very) simple glyph objects.

        To write a glyph to the glyph set, you use the writeGlyph() method.
        The simple glyph objects returned through the dict interface do not
        support writing, they are just a convenient way to get at the glyph data.
        """

        glyphClass = Glyph

        def __init__(
            self,
            path: PathOrFS,
            glyphNameToFileNameFunc: GlyphNameToFileNameFunc = None,
            ufoFormatVersion: UFOFormatVersionInput = None,
            validateRead: bool = True,
            validateWrite: bool = True,
            expectContentsFile: bool = False,
        ) -> None:
            """
            'path' should be a path (string) to an existing local directory, or
            an instance of fs.base.FS class.

            The optional 'glyphNameToFileNameFunc' argument must be a callback
            function that takes two arguments: a glyph name and a list of all
            existing filenames (if any exist). It should return a file name
            (including the .glif extension). The glyphNameToFileName function
            is called whenever a file name is created for a given glyph name.

            ``validateRead`` will validate read operations. Its default is ``True``.
            ``validateWrite`` will validate write operations. Its default is ``True``.
            ``expectContentsFile`` will raise a GlifLibError if a contents.plist file is
            not found on the glyph set file system. This should be set to ``True`` if you
            are reading an existing UFO and ``False`` if you create a fresh	glyph set.
            """
            try:
                ufoFormatVersion = normalizeFormatVersion(
                    ufoFormatVersion, UFOFormatVersion
                )
            except ValueError as e:
                from fontTools.ufoLib.errors import UnsupportedUFOFormat

                raise UnsupportedUFOFormat(
                    f"Unsupported UFO format: {ufoFormatVersion!r}"
                ) from e

            if hasattr(path, "__fspath__"):  # support os.PathLike objects
                path = path.__fspath__()

            if isinstance(path, str):
                try:
                    filesystem: FS = fs.osfs.OSFS(path)
                except fs.errors.CreateFailed:
                    raise GlifLibError("No glyphs directory '%s'" % path)
                self._shouldClose: bool = True
            elif isinstance(path, fs.base.FS):
                filesystem = path
                try:
                    filesystem.check()
                except fs.errors.FilesystemClosed:
                    raise GlifLibError("the filesystem '%s' is closed" % filesystem)
                self._shouldClose = False
            else:
                raise TypeError(
                    "Expected a path string or fs object, found %s" % type(path).__name__
                )
            try:
                path = filesystem.getsyspath("/")
            except fs.errors.NoSysPath:
                # network or in-memory FS may not map to the local one
                path = str(filesystem)
            # 'dirName' is kept for backward compatibility only, but it's DEPRECATED
            # as it's not guaranteed that it maps to an existing OSFS directory.
            # Client could use the FS api via the `self.fs` attribute instead.
            self.dirName: str = fs.path.basename(path)
            self.fs: FS = filesystem
            # if glyphSet contains no 'contents.plist', we consider it empty
            self._havePreviousFile: bool = filesystem.exists(CONTENTS_FILENAME)
            if expectContentsFile and not self._havePreviousFile:
                raise GlifLibError(f"{CONTENTS_FILENAME} is missing.")
            # attribute kept for backward compatibility
            self.ufoFormatVersion: int = ufoFormatVersion.major
            self.ufoFormatVersionTuple: UFOFormatVersion = ufoFormatVersion
            if glyphNameToFileNameFunc is None:
                glyphNameToFileNameFunc = glyphNameToFileName
            self.glyphNameToFileName: Callable[[str, set[str]], str] = (
                glyphNameToFileNameFunc
            )
            self._validateRead: bool = validateRead
            self._validateWrite: bool = validateWrite
            self._existingFileNames: set[str] | None = None
            self._reverseContents: Optional[dict[str, str]] = None

            self.rebuildContents()

        def rebuildContents(self, validateRead: bool = False) -> None:
            """
            Rebuild the contents dict by loading contents.plist.

            ``validateRead`` will validate the data, by default it is set to the
            class's ``validateRead`` value, can be overridden.
            """
            if validateRead is None:
                validateRead = self._validateRead
            contents = self._getPlist(CONTENTS_FILENAME, {})
            # validate the contents
            if validateRead:
                invalidFormat = False
                if not isinstance(contents, dict):
                    invalidFormat = True
                else:
                    for name, fileName in contents.items():
                        if not isinstance(name, str):
                            invalidFormat = True
                        if not isinstance(fileName, str):
                            invalidFormat = True
                        elif not self.fs.exists(fileName):
                            raise GlifLibError(
                                "%s references a file that does not exist: %s"
                                % (CONTENTS_FILENAME, fileName)
                            )
                if invalidFormat:
                    raise GlifLibError("%s is not properly formatted" % CONTENTS_FILENAME)
            self.contents: dict[str, str] = contents
            self._existingFileNames = None
            self._reverseContents = None

        def getReverseContents(self) -> dict[str, str]:
            """
            Return a reversed dict of self.contents, mapping file names to
            glyph names. This is primarily an aid for custom glyph name to file
            name schemes that want to make sure they don't generate duplicate
            file names. The file names are converted to lowercase so we can
            reliably check for duplicates that only differ in case, which is
            important for case-insensitive file systems.
            """
            if self._reverseContents is None:
                d = {}
                for k, v in self.contents.items():
                    d[v.lower()] = k
                self._reverseContents = d
            return self._reverseContents

        def writeContents(self) -> None:
            """
            Write the contents.plist file out to disk. Call this method when
            you're done writing glyphs.
            """
            self._writePlist(CONTENTS_FILENAME, self.contents)

        # layer info

        def readLayerInfo(self, info: Any, validateRead: Optional[bool] = None) -> None:
            """
            ``validateRead`` will validate the data, by default it is set to the
            class's ``validateRead`` value, can be overridden.
            """
            if validateRead is None:
                validateRead = self._validateRead
            infoDict = self._getPlist(LAYERINFO_FILENAME, {})
            if validateRead:
                if not isinstance(infoDict, dict):
                    raise GlifLibError("layerinfo.plist is not properly formatted.")
                infoDict = validateLayerInfoVersion3Data(infoDict)
            # populate the object
            for attr, value in infoDict.items():
                try:
                    setattr(info, attr, value)
                except AttributeError:
                    raise GlifLibError(
                        "The supplied layer info object does not support setting a necessary attribute (%s)."
                        % attr
                    )

        def writeLayerInfo(self, info: Any, validateWrite: Optional[bool] = None) -> None:
            """
            ``validateWrite`` will validate the data, by default it is set to the
            class's ``validateWrite`` value, can be overridden.
            """
            if validateWrite is None:
                validateWrite = self._validateWrite
            if self.ufoFormatVersionTuple.major < 3:
                raise GlifLibError(
                    "layerinfo.plist is not allowed in UFO %d."
                    % self.ufoFormatVersionTuple.major
                )
            # gather data
            infoData = {}
            for attr in layerInfoVersion3ValueData.keys():
                if hasattr(info, attr):
                    try:
                        value = getattr(info, attr)
                    except AttributeError:
                        raise GlifLibError(
                            "The supplied info object does not support getting a necessary attribute (%s)."
                            % attr
                        )
                    if value is None or (attr == "lib" and not value):
                        continue
                    infoData[attr] = value
            if infoData:
                # validate
                if validateWrite:
                    infoData = validateLayerInfoVersion3Data(infoData)
                # write file
                self._writePlist(LAYERINFO_FILENAME, infoData)
            elif self._havePreviousFile and self.fs.exists(LAYERINFO_FILENAME):
                # data empty, remove existing file
                self.fs.remove(LAYERINFO_FILENAME)

        def getGLIF(self, glyphName: str) -> bytes:
            """
            Get the raw GLIF text for a given glyph name. This only works
            for GLIF files that are already on disk.

            This method is useful in situations when the raw XML needs to be
            read from a glyph set for a particular glyph before fully parsing
            it into an object structure via the readGlyph method.

            Raises KeyError if 'glyphName' is not in contents.plist, or
            GlifLibError if the file associated with can't be found.
            """
            fileName = self.contents[glyphName]
            try:
                return self.fs.readbytes(fileName)
            except fs.errors.ResourceNotFound:
                raise GlifLibError(
                    "The file '%s' associated with glyph '%s' in contents.plist "
                    "does not exist on %s" % (fileName, glyphName, self.fs)
                )

        def getGLIFModificationTime(self, glyphName: str) -> Optional[float]:
            """
            Returns the modification time for the GLIF file with 'glyphName', as
            a floating point number giving the number of seconds since the epoch.
            Return None if the associated file does not exist or the underlying
            filesystem does not support getting modified times.
            Raises KeyError if the glyphName is not in contents.plist.
            """
            fileName = self.contents[glyphName]
            return self.getFileModificationTime(fileName)

        # reading/writing API

        def readGlyph(
            self,
            glyphName: str,
            glyphObject: Optional[Any] = None,
            pointPen: Optional[AbstractPointPen] = None,
            validate: Optional[bool] = None,
        ) -> None:
            """
            Read a .glif file for 'glyphName' from the glyph set. The
            'glyphObject' argument can be any kind of object (even None);
            the readGlyph() method will attempt to set the following
            attributes on it:

            width
                    the advance width of the glyph
            height
                    the advance height of the glyph
            unicodes
                    a list of unicode values for this glyph
            note
                    a string
            lib
                    a dictionary containing custom data
            image
                    a dictionary containing image data
            guidelines
                    a list of guideline data dictionaries
            anchors
                    a list of anchor data dictionaries

            All attributes are optional, in two ways:

            1) An attribute *won't* be set if the .glif file doesn't
               contain data for it. 'glyphObject' will have to deal
               with default values itself.
            2) If setting the attribute fails with an AttributeError
               (for example if the 'glyphObject' attribute is read-
               only), readGlyph() will not propagate that exception,
               but ignore that attribute.

            To retrieve outline information, you need to pass an object
            conforming to the PointPen protocol as the 'pointPen' argument.
            This argument may be None if you don't need the outline data.

            readGlyph() will raise KeyError if the glyph is not present in
            the glyph set.

            ``validate`` will validate the data, by default it is set to the
            class's ``validateRead`` value, can be overridden.
            """
            if validate is None:
                validate = self._validateRead
            text = self.getGLIF(glyphName)
            try:
                tree = _glifTreeFromString(text)
                formatVersions = GLIFFormatVersion.supported_versions(
                    self.ufoFormatVersionTuple
                )
                _readGlyphFromTree(
                    tree,
                    glyphObject,
                    pointPen,
                    formatVersions=formatVersions,
                    validate=validate,
                )
            except GlifLibError as glifLibError:
                # Re-raise with a note that gives extra context, describing where
                # the error occurred.
                fileName = self.contents[glyphName]
                try:
                    glifLocation = f"'{self.fs.getsyspath(fileName)}'"
                except fs.errors.NoSysPath:
                    # Network or in-memory FS may not map to a local path, so use
                    # the best string representation we have.
                    glifLocation = f"'{fileName}' from '{str(self.fs)}'"

                glifLibError._add_note(
                    f"The issue is in glyph '{glyphName}', located in {glifLocation}."
                )
                raise

        def writeGlyph(
            self,
            glyphName: str,
            glyphObject: Optional[Any] = None,
            drawPointsFunc: Optional[Callable[[AbstractPointPen], None]] = None,
            formatVersion: GLIFFormatVersionInput = None,
            validate: Optional[bool] = None,
        ) -> None:
            """
            Write a .glif file for 'glyphName' to the glyph set. The
            'glyphObject' argument can be any kind of object (even None);
            the writeGlyph() method will attempt to get the following
            attributes from it:

            width
                    the advance width of the glyph
            height
                    the advance height of the glyph
            unicodes
                    a list of unicode values for this glyph
            note
                    a string
            lib
                    a dictionary containing custom data
            image
                    a dictionary containing image data
            guidelines
                    a list of guideline data dictionaries
            anchors
                    a list of anchor data dictionaries

            All attributes are optional: if 'glyphObject' doesn't
            have the attribute, it will simply be skipped.

            To write outline data to the .glif file, writeGlyph() needs
            a function (any callable object actually) that will take one
            argument: an object that conforms to the PointPen protocol.
            The function will be called by writeGlyph(); it has to call the
            proper PointPen methods to transfer the outline to the .glif file.

            The GLIF format version will be chosen based on the ufoFormatVersion
            passed during the creation of this object. If a particular format
            version is desired, it can be passed with the formatVersion argument.
            The formatVersion argument accepts either a tuple of integers for
            (major, minor), or a single integer for the major digit only (with
            minor digit implied as 0).

            An UnsupportedGLIFFormat exception is raised if the requested GLIF
            formatVersion is not supported.

            ``validate`` will validate the data, by default it is set to the
            class's ``validateWrite`` value, can be overridden.
            """
            if formatVersion is None:
                formatVersion = GLIFFormatVersion.default(self.ufoFormatVersionTuple)
            else:
                try:
                    formatVersion = normalizeFormatVersion(formatVersion, GLIFFormatVersion)
                except ValueError as e:
                    from fontTools.ufoLib.errors import UnsupportedGLIFFormat

                    raise UnsupportedGLIFFormat(
                        f"Unsupported GLIF format version: {formatVersion!r}"
                    ) from e
            if formatVersion not in GLIFFormatVersion.supported_versions(
                self.ufoFormatVersionTuple
            ):
                from fontTools.ufoLib.errors import UnsupportedGLIFFormat

                raise UnsupportedGLIFFormat(
                    f"Unsupported GLIF format version ({formatVersion!s}) "
                    f"for UFO format version {self.ufoFormatVersionTuple!s}."
                )
            if validate is None:
                validate = self._validateWrite
            fileName = self.contents.get(glyphName)
            if fileName is None:
                if self._existingFileNames is None:
                    self._existingFileNames = {
                        fileName.lower() for fileName in self.contents.values()
                    }
                fileName = self.glyphNameToFileName(glyphName, self._existingFileNames)
                self.contents[glyphName] = fileName
                self._existingFileNames.add(fileName.lower())
                if self._reverseContents is not None:
                    self._reverseContents[fileName.lower()] = glyphName
            data = _writeGlyphToBytes(
                glyphName,
                glyphObject,
                drawPointsFunc,
                formatVersion=formatVersion,
                validate=validate,
            )
            if (
                self._havePreviousFile
                and self.fs.exists(fileName)
                and data == self.fs.readbytes(fileName)
            ):
                return
            self.fs.writebytes(fileName, data)

        def deleteGlyph(self, glyphName: str) -> None:
            """Permanently delete the glyph from the glyph set on disk. Will
            raise KeyError if the glyph is not present in the glyph set.
            """
            fileName = self.contents[glyphName]
            self.fs.remove(fileName)
            if self._existingFileNames is not None:
                self._existingFileNames.remove(fileName.lower())
            if self._reverseContents is not None:
                del self._reverseContents[fileName.lower()]
            del self.contents[glyphName]

        # dict-like support

        def keys(self) -> list[str]:
            return list(self.contents.keys())

        def has_key(self, glyphName: str) -> bool:
            return glyphName in self.contents

        __contains__ = has_key

        def __len__(self) -> int:
            return len(self.contents)

        def __getitem__(self, glyphName: str) -> Any:
            if glyphName not in self.contents:
                raise KeyError(glyphName)
            return self.glyphClass(glyphName, self)

        # quickly fetch unicode values

        def getUnicodes(
            self, glyphNames: Optional[Iterable[str]] = None
        ) -> dict[str, list[int]]:
            """
            Return a dictionary that maps glyph names to lists containing
            the unicode value[s] for that glyph, if any. This parses the .glif
            files partially, so it is a lot faster than parsing all files completely.
            By default this checks all glyphs, but a subset can be passed with glyphNames.
            """
            unicodes = {}
            if glyphNames is None:
                glyphNames = self.contents.keys()
            for glyphName in glyphNames:
                text = self.getGLIF(glyphName)
                unicodes[glyphName] = _fetchUnicodes(text)
            return unicodes

        def getComponentReferences(
            self, glyphNames: Optional[Iterable[str]] = None
        ) -> dict[str, list[str]]:
            """
            Return a dictionary that maps glyph names to lists containing the
            base glyph name of components in the glyph. This parses the .glif
            files partially, so it is a lot faster than parsing all files completely.
            By default this checks all glyphs, but a subset can be passed with glyphNames.
            """
            components = {}
            if glyphNames is None:
                glyphNames = self.contents.keys()
            for glyphName in glyphNames:
                text = self.getGLIF(glyphName)
                components[glyphName] = _fetchComponentBases(text)
            return components

        def getImageReferences(
            self, glyphNames: Optional[Iterable[str]] = None
        ) -> dict[str, Optional[str]]:
            """
            Return a dictionary that maps glyph names to the file name of the image
            referenced by the glyph. This parses the .glif files partially, so it is a
            lot faster than parsing all files completely.
            By default this checks all glyphs, but a subset can be passed with glyphNames.
            """
            images = {}
            if glyphNames is None:
                glyphNames = self.contents.keys()
            for glyphName in glyphNames:
                text = self.getGLIF(glyphName)
                images[glyphName] = _fetchImageFileName(text)
            return images

        def close(self) -> None:
            if self._shouldClose:
                self.fs.close()

        def __enter__(self) -> GlyphSet:
            return self

        def __exit__(self, exc_type: Any, exc_value: Any, exc_tb: Any) -> None:
            self.close()

    # -----------------------
    # Glyph Name to File Name
    # -----------------------

    def glyphNameToFileName(glyphName: str, existingFileNames: Optional[set[str]]) -> str:
        """
        Wrapper around the userNameToFileName function in filenames.py

        Note that existingFileNames should be a set for large glyphsets
        or performance will suffer.
        """
        if existingFileNames is None:
            existingFileNames = set()
        return userNameToFileName(glyphName, existing=existingFileNames, suffix=".glif")

    # -----------------------
    # GLIF To and From String
    # -----------------------

    def readGlyphFromString(
        aString: Union[str, bytes],
        glyphObject: Optional[Any] = None,
        pointPen: Optional[Any] = None,
        formatVersions: FormatVersions = None,
        validate: bool = True,
    ) -> None:
        """
        Read .glif data from a string into a glyph object.

        The 'glyphObject' argument can be any kind of object (even None);
        the readGlyphFromString() method will attempt to set the following
        attributes on it:

        width
                the advance width of the glyph
        height
                the advance height of the glyph
        unicodes
                a list of unicode values for this glyph
        note
                a string
        lib
                a dictionary containing custom data
        image
                a dictionary containing image data
        guidelines
                a list of guideline data dictionaries
        anchors
                a list of anchor data dictionaries

        All attributes are optional, in two ways:

        1) An attribute *won't* be set if the .glif file doesn't
           contain data for it. 'glyphObject' will have to deal
           with default values itself.
        2) If setting the attribute fails with an AttributeError
           (for example if the 'glyphObject' attribute is read-
           only), readGlyphFromString() will not propagate that
           exception, but ignore that attribute.

        To retrieve outline information, you need to pass an object
        conforming to the PointPen protocol as the 'pointPen' argument.
        This argument may be None if you don't need the outline data.

        The formatVersions optional argument define the GLIF format versions
        that are allowed to be read.
        The type is Optional[Iterable[tuple[int, int], int]]. It can contain
        either integers (for the major versions to be allowed, with minor
        digits defaulting to 0), or tuples of integers to specify both
        (major, minor) versions.
        By default when formatVersions is None all the GLIF format versions
        currently defined are allowed to be read.

        ``validate`` will validate the read data. It is set to ``True`` by default.
        """
        tree = _glifTreeFromString(aString)

        if formatVersions is None:
            validFormatVersions: Set[GLIFFormatVersion] = (
                GLIFFormatVersion.supported_versions()
            )
        else:
            validFormatVersions, invalidFormatVersions = set(), set()
            for v in formatVersions:
                try:
                    formatVersion = normalizeFormatVersion(v, GLIFFormatVersion)
                except ValueError:
                    invalidFormatVersions.add(v)
                else:
                    validFormatVersions.add(formatVersion)
            if not validFormatVersions:
                raise ValueError(
                    "None of the requested GLIF formatVersions are supported: "
                    f"{formatVersions!r}"
                )

        _readGlyphFromTree(
            tree,
            glyphObject,
            pointPen,
            formatVersions=validFormatVersions,
            validate=validate,
        )

    def _writeGlyphToBytes(
        glyphName: str,
        glyphObject: Optional[Any] = None,
        drawPointsFunc: Optional[Callable[[Any], None]] = None,
        writer: Optional[Any] = None,
        formatVersion: Optional[FormatVersion] = None,
        validate: bool = True,
    ) -> bytes:
        """Return .glif data for a glyph as a UTF-8 encoded bytes string."""
        try:
            formatVersion = normalizeFormatVersion(formatVersion, GLIFFormatVersion)
        except ValueError:
            from fontTools.ufoLib.errors import UnsupportedGLIFFormat

            raise UnsupportedGLIFFormat(
                "Unsupported GLIF format version: {formatVersion!r}"
            )
        # start
        if validate and not isinstance(glyphName, str):
            raise GlifLibError("The glyph name is not properly formatted.")
        if validate and len(glyphName) == 0:
            raise GlifLibError("The glyph name is empty.")
        glyphAttrs = OrderedDict(
            [("name", glyphName), ("format", repr(formatVersion.major))]
        )
        if formatVersion.minor != 0:
            glyphAttrs["formatMinor"] = repr(formatVersion.minor)
        root = etree.Element("glyph", glyphAttrs)
        identifiers: set[str] = set()
        # advance
        _writeAdvance(glyphObject, root, validate)
        # unicodes
        if getattr(glyphObject, "unicodes", None):
            _writeUnicodes(glyphObject, root, validate)
        # note
        if getattr(glyphObject, "note", None):
            _writeNote(glyphObject, root, validate)
        # image
        if formatVersion.major >= 2 and getattr(glyphObject, "image", None):
            _writeImage(glyphObject, root, validate)
        # guidelines
        if formatVersion.major >= 2 and getattr(glyphObject, "guidelines", None):
            _writeGuidelines(glyphObject, root, identifiers, validate)
        # anchors
        anchors = getattr(glyphObject, "anchors", None)
        if formatVersion.major >= 2 and anchors:
            _writeAnchors(glyphObject, root, identifiers, validate)
        # outline
        if drawPointsFunc is not None:
            outline = etree.SubElement(root, "outline")
            pen = GLIFPointPen(outline, identifiers=identifiers, validate=validate)
            drawPointsFunc(pen)
            if formatVersion.major == 1 and anchors:
                _writeAnchorsFormat1(pen, anchors, validate)
            # prevent lxml from writing self-closing tags
            if not len(outline):
                outline.text = "\n  "
        # lib
        if getattr(glyphObject, "lib", None):
            _writeLib(glyphObject, root, validate)
        # return the text
        data = etree.tostring(
            root, encoding="UTF-8", xml_declaration=True, pretty_print=True
        )
        return data

    def writeGlyphToString(
        glyphName: str,
        glyphObject: Optional[Any] = None,
        drawPointsFunc: Optional[Callable[[Any], None]] = None,
        formatVersion: Optional[FormatVersion] = None,
        validate: bool = True,
    ) -> str:
        """
        Return .glif data for a glyph as a string. The XML declaration's
        encoding is always set to "UTF-8".
        The 'glyphObject' argument can be any kind of object (even None);
        the writeGlyphToString() method will attempt to get the following
        attributes from it:

        width
                the advance width of the glyph
        height
                the advance height of the glyph
        unicodes
                a list of unicode values for this glyph
        note
                a string
        lib
                a dictionary containing custom data
        image
                a dictionary containing image data
        guidelines
                a list of guideline data dictionaries
        anchors
                a list of anchor data dictionaries

        All attributes are optional: if 'glyphObject' doesn't
        have the attribute, it will simply be skipped.

        To write outline data to the .glif file, writeGlyphToString() needs
        a function (any callable object actually) that will take one
        argument: an object that conforms to the PointPen protocol.
        The function will be called by writeGlyphToString(); it has to call the
        proper PointPen methods to transfer the outline to the .glif file.

        The GLIF format version can be specified with the formatVersion argument.
        This accepts either a tuple of integers for (major, minor), or a single
        integer for the major digit only (with minor digit implied as 0).
        By default when formatVesion is None the latest GLIF format version will
        be used; currently it's 2.0, which is equivalent to formatVersion=(2, 0).

        An UnsupportedGLIFFormat exception is raised if the requested UFO
        formatVersion is not supported.

        ``validate`` will validate the written data. It is set to ``True`` by default.
        """
        data = _writeGlyphToBytes(
            glyphName,
            glyphObject=glyphObject,
            drawPointsFunc=drawPointsFunc,
            formatVersion=formatVersion,
            validate=validate,
        )
        return data.decode("utf-8")

    def _writeAdvance(glyphObject: Any, element: ElementType, validate: bool) -> None:
        width = getattr(glyphObject, "width", None)
        if width is not None:
            if validate and not isinstance(width, numberTypes):
                raise GlifLibError("width attribute must be int or float")
            if width == 0:
                width = None
        height = getattr(glyphObject, "height", None)
        if height is not None:
            if validate and not isinstance(height, numberTypes):
                raise GlifLibError("height attribute must be int or float")
            if height == 0:
                height = None
        if width is not None and height is not None:
            etree.SubElement(
                element,
                "advance",
                OrderedDict([("height", repr(height)), ("width", repr(width))]),
            )
        elif width is not None:
            etree.SubElement(element, "advance", dict(width=repr(width)))
        elif height is not None:
            etree.SubElement(element, "advance", dict(height=repr(height)))

    def _writeUnicodes(glyphObject: Any, element: ElementType, validate: bool) -> None:
        unicodes = getattr(glyphObject, "unicodes", [])
        if validate and isinstance(unicodes, int):
            unicodes = [unicodes]
        seen = set()
        for code in unicodes:
            if validate and not isinstance(code, int):
                raise GlifLibError("unicode values must be int")
            if code in seen:
                continue
            seen.add(code)
            hexCode = "%04X" % code
            etree.SubElement(element, "unicode", dict(hex=hexCode))

    def _writeNote(glyphObject: Any, element: ElementType, validate: bool) -> None:
        note = getattr(glyphObject, "note", None)
        if validate and not isinstance(note, str):
            raise GlifLibError("note attribute must be str")
        if isinstance(note, str):
            note = note.strip()
            note = "\n" + note + "\n"
            etree.SubElement(element, "note").text = note

    def _writeImage(glyphObject: Any, element: ElementType, validate: bool) -> None:
        image = getattr(glyphObject, "image", None)
        if image is None:
            return

        if validate and not imageValidator(image):
            raise GlifLibError(
                "image attribute must be a dict or dict-like object with the proper structure."
            )
        attrs = OrderedDict([("fileName", image["fileName"])])
        for attr, default in _transformationInfo:
            value = image.get(attr, default)
            if value != default:
                attrs[attr] = repr(value)
        color = image.get("color")
        if color is not None:
            attrs["color"] = color
        etree.SubElement(element, "image", attrs)

    def _writeGuidelines(
        glyphObject: Any, element: ElementType, identifiers: set[str], validate: bool
    ) -> None:
        guidelines = getattr(glyphObject, "guidelines", [])
        if validate and not guidelinesValidator(guidelines):
            raise GlifLibError("guidelines attribute does not have the proper structure.")
        for guideline in guidelines:
            attrs = OrderedDict()
            x = guideline.get("x")
            if x is not None:
                attrs["x"] = repr(x)
            y = guideline.get("y")
            if y is not None:
                attrs["y"] = repr(y)
            angle = guideline.get("angle")
            if angle is not None:
                attrs["angle"] = repr(angle)
            name = guideline.get("name")
            if name is not None:
                attrs["name"] = name
            color = guideline.get("color")
            if color is not None:
                attrs["color"] = color
            identifier = guideline.get("identifier")
            if identifier is not None:
                if validate and identifier in identifiers:
                    raise GlifLibError("identifier used more than once: %s" % identifier)
                attrs["identifier"] = identifier
                identifiers.add(identifier)
            etree.SubElement(element, "guideline", attrs)

    def _writeAnchorsFormat1(pen: Any, anchors: Any, validate: bool) -> None:
        if validate and not anchorsValidator(anchors):
            raise GlifLibError("anchors attribute does not have the proper structure.")
        for anchor in anchors:
            attrs = {}
            x = anchor["x"]
            attrs["x"] = repr(x)
            y = anchor["y"]
            attrs["y"] = repr(y)
            name = anchor.get("name")
            if name is not None:
                attrs["name"] = name
            pen.beginPath()
            pen.addPoint((x, y), segmentType="move", name=name)
            pen.endPath()

    def _writeAnchors(
        glyphObject: Any,
        element: ElementType,
        identifiers: set[str],
        validate: bool,
    ) -> None:
        anchors = getattr(glyphObject, "anchors", [])
        if validate and not anchorsValidator(anchors):
            raise GlifLibError("anchors attribute does not have the proper structure.")
        for anchor in anchors:
            attrs = OrderedDict()
            x = anchor["x"]
            attrs["x"] = repr(x)
            y = anchor["y"]
            attrs["y"] = repr(y)
            name = anchor.get("name")
            if name is not None:
                attrs["name"] = name
            color = anchor.get("color")
            if color is not None:
                attrs["color"] = color
            identifier = anchor.get("identifier")
            if identifier is not None:
                if validate and identifier in identifiers:
                    raise GlifLibError("identifier used more than once: %s" % identifier)
                attrs["identifier"] = identifier
                identifiers.add(identifier)
            etree.SubElement(element, "anchor", attrs)

    def _writeLib(glyphObject: Any, element: ElementType, validate: bool) -> None:
        lib = getattr(glyphObject, "lib", None)
        if not lib:
            # don't write empty lib
            return
        if validate:
            valid, message = glyphLibValidator(lib)
            if not valid:
                raise GlifLibError(message)
        if not isinstance(lib, dict):
            lib = dict(lib)
        # plist inside GLIF begins with 2 levels of indentation
        e = plistlib.totree(lib, indent_level=2)
        etree.SubElement(element, "lib").append(e)

    # -----------------------
    # layerinfo.plist Support
    # -----------------------

    layerInfoVersion3ValueData = {
        "color": dict(type=str, valueValidator=colorValidator),
        "lib": dict(type=dict, valueValidator=genericTypeValidator),
    }

    def validateLayerInfoVersion3ValueForAttribute(attr: str, value: Any) -> bool:
        """
        This performs very basic validation of the value for attribute
        following the UFO 3 fontinfo.plist specification. The results
        of this should not be interpretted as *correct* for the font
        that they are part of. This merely indicates that the value
        is of the proper type and, where the specification defines
        a set range of possible values for an attribute, that the
        value is in the accepted range.
        """
        if attr not in layerInfoVersion3ValueData:
            return False
        dataValidationDict = layerInfoVersion3ValueData[attr]
        valueType = dataValidationDict.get("type")
        validator = dataValidationDict.get("valueValidator")
        valueOptions = dataValidationDict.get("valueOptions")
        # have specific options for the validator
        assert callable(validator)
        if valueOptions is not None:
            isValidValue = validator(value, valueOptions)
        # no specific options
        else:
            if validator == genericTypeValidator:
                isValidValue = validator(value, valueType)
            else:
                isValidValue = validator(value)
        return isValidValue

    def validateLayerInfoVersion3Data(infoData: dict[str, Any]) -> dict[str, Any]:
        """
        This performs very basic validation of the value for infoData
        following the UFO 3 layerinfo.plist specification. The results
        of this should not be interpretted as *correct* for the font
        that they are part of. This merely indicates that the values
        are of the proper type and, where the specification defines
        a set range of possible values for an attribute, that the
        value is in the accepted range.
        """
        for attr, value in infoData.items():
            if attr not in layerInfoVersion3ValueData:
                raise GlifLibError("Unknown attribute %s." % attr)
            isValidValue = validateLayerInfoVersion3ValueForAttribute(attr, value)
            if not isValidValue:
                raise GlifLibError(f"Invalid value for attribute {attr} ({value!r}).")
        return infoData

    # -----------------
    # GLIF Tree Support
    # -----------------

    def _glifTreeFromFile(aFile: Union[str, bytes, int]) -> ElementType:
        if etree._have_lxml:
            tree = etree.parse(aFile, parser=etree.XMLParser(remove_comments=True))
        else:
            tree = etree.parse(aFile)
        root = tree.getroot()
        if root.tag != "glyph":
            raise GlifLibError("The GLIF is not properly formatted.")
        if root.text and root.text.strip() != "":
            raise GlifLibError("Invalid GLIF structure.")
        return root

    def _glifTreeFromString(aString: Union[str, bytes]) -> ElementType:
        data = tobytes(aString, encoding="utf-8")
        try:
            if etree._have_lxml:
                root = etree.fromstring(data, parser=etree.XMLParser(remove_comments=True))
            else:
                root = etree.fromstring(data)
        except Exception as etree_exception:
            raise GlifLibError("GLIF contains invalid XML.") from etree_exception

        if root.tag != "glyph":
            raise GlifLibError("The GLIF is not properly formatted.")
        if root.text and root.text.strip() != "":
            raise GlifLibError("Invalid GLIF structure.")
        return root

    def _readGlyphFromTree(
        tree: ElementType,
        glyphObject: Optional[Any] = None,
        pointPen: Optional[AbstractPointPen] = None,
        formatVersions: Set[GLIFFormatVersion] = GLIFFormatVersion.supported_versions(),
        validate: bool = True,
    ) -> None:
        # check the format version
        formatVersionMajor = tree.get("format")
        if formatVersionMajor is None:
            if validate:
                raise GlifLibError("Unspecified format version in GLIF.")
            formatVersionMajor = 0
        formatVersionMinor = tree.get("formatMinor", 0)
        try:
            formatVersion = GLIFFormatVersion(
                (int(formatVersionMajor), int(formatVersionMinor))
            )
        except ValueError as e:
            msg = "Unsupported GLIF format: %s.%s" % (
                formatVersionMajor,
                formatVersionMinor,
            )
            if validate:
                from fontTools.ufoLib.errors import UnsupportedGLIFFormat

                raise UnsupportedGLIFFormat(msg) from e
            # warn but continue using the latest supported format
            formatVersion = GLIFFormatVersion.default()
            logger.warning(
                "%s. Assuming the latest supported version (%s). "
                "Some data may be skipped or parsed incorrectly.",
                msg,
                formatVersion,
            )

        if validate and formatVersion not in formatVersions:
            raise GlifLibError(f"Forbidden GLIF format version: {formatVersion!s}")

        try:
            readGlyphFromTree = _READ_GLYPH_FROM_TREE_FUNCS[formatVersion]
        except KeyError:
            raise NotImplementedError(formatVersion)

        readGlyphFromTree(
            tree=tree,
            glyphObject=glyphObject,
            pointPen=pointPen,
            validate=validate,
            formatMinor=formatVersion.minor,
        )

    def _readGlyphFromTreeFormat1(
        tree: ElementType,
        glyphObject: Optional[Any] = None,
        pointPen: Optional[AbstractPointPen] = None,
        validate: bool = False,
        **kwargs: Any,
    ) -> None:
        # get the name
        _readName(glyphObject, tree, validate)
        # populate the sub elements
        unicodes = []
        haveSeenAdvance = haveSeenOutline = haveSeenLib = haveSeenNote = False
        for element in tree:
            if glyphObject is None:
                continue

            if element.tag == "outline":
                if validate:
                    if haveSeenOutline:
                        raise GlifLibError("The outline element occurs more than once.")
                    if element.attrib:
                        raise GlifLibError(
                            "The outline element contains unknown attributes."
                        )
                    if element.text and element.text.strip() != "":
                        raise GlifLibError("Invalid outline structure.")
                haveSeenOutline = True
                buildOutlineFormat1(glyphObject, pointPen, element, validate)
            elif element.tag == "advance":
                if validate and haveSeenAdvance:
                    raise GlifLibError("The advance element occurs more than once.")
                haveSeenAdvance = True
                _readAdvance(glyphObject, element)
            elif element.tag == "unicode":
                v = element.get("hex")
                if v is None:
                    raise GlifLibError(
                        "A unicode element is missing its required hex attribute."
                    )
                try:
                    v = int(v, 16)
                    if v not in unicodes:
                        unicodes.append(v)
                except ValueError:
                    raise GlifLibError(
                        "Illegal value for hex attribute of unicode element."
                    )
            elif element.tag == "note":
                if validate and haveSeenNote:
                    raise GlifLibError("The note element occurs more than once.")
                haveSeenNote = True
                _readNote(glyphObject, element)
            elif element.tag == "lib":
                if validate and haveSeenLib:
                    raise GlifLibError("The lib element occurs more than once.")
                haveSeenLib = True
                _readLib(glyphObject, element, validate)
            else:
                raise GlifLibError("Unknown element in GLIF: %s" % element)
        # set the collected unicodes
        if unicodes:
            _relaxedSetattr(glyphObject, "unicodes", unicodes)

    def _readGlyphFromTreeFormat2(
        tree: ElementType,
        glyphObject: Optional[Any] = None,
        pointPen: Optional[AbstractPointPen] = None,
        validate: bool = False,
        formatMinor: int = 0,
    ) -> None:
        # get the name
        _readName(glyphObject, tree, validate)
        # populate the sub elements
        unicodes = []
        guidelines = []
        anchors = []
        haveSeenAdvance = haveSeenImage = haveSeenOutline = haveSeenLib = haveSeenNote = (
            False
        )
        identifiers: set[str] = set()
        for element in tree:
            if glyphObject is None:
                continue
            if element.tag == "outline":
                if validate:
                    if haveSeenOutline:
                        raise GlifLibError("The outline element occurs more than once.")
                    if element.attrib:
                        raise GlifLibError(
                            "The outline element contains unknown attributes."
                        )
                    if element.text and element.text.strip() != "":
                        raise GlifLibError("Invalid outline structure.")
                haveSeenOutline = True
                if pointPen is not None:
                    buildOutlineFormat2(
                        glyphObject, pointPen, element, identifiers, validate
                    )
            elif element.tag == "advance":
                if validate and haveSeenAdvance:
                    raise GlifLibError("The advance element occurs more than once.")
                haveSeenAdvance = True
                _readAdvance(glyphObject, element)
            elif element.tag == "unicode":
                v = element.get("hex")
                if v is None:
                    raise GlifLibError(
                        "A unicode element is missing its required hex attribute."
                    )
                try:
                    v = int(v, 16)
                    if v not in unicodes:
                        unicodes.append(v)
                except ValueError:
                    raise GlifLibError(
                        "Illegal value for hex attribute of unicode element."
                    )
            elif element.tag == "guideline":
                if validate and len(element):
                    raise GlifLibError("Unknown children in guideline element.")
                attrib = dict(element.attrib)
                for attr in ("x", "y", "angle"):
                    if attr in attrib:
                        attrib[attr] = _number(attrib[attr])
                guidelines.append(attrib)
            elif element.tag == "anchor":
                if validate and len(element):
                    raise GlifLibError("Unknown children in anchor element.")
                attrib = dict(element.attrib)
                for attr in ("x", "y"):
                    if attr in element.attrib:
                        attrib[attr] = _number(attrib[attr])
                anchors.append(attrib)
            elif element.tag == "image":
                if validate:
                    if haveSeenImage:
                        raise GlifLibError("The image element occurs more than once.")
                    if len(element):
                        raise GlifLibError("Unknown children in image element.")
                haveSeenImage = True
                _readImage(glyphObject, element, validate)
            elif element.tag == "note":
                if validate and haveSeenNote:
                    raise GlifLibError("The note element occurs more than once.")
                haveSeenNote = True
                _readNote(glyphObject, element)
            elif element.tag == "lib":
                if validate and haveSeenLib:
                    raise GlifLibError("The lib element occurs more than once.")
                haveSeenLib = True
                _readLib(glyphObject, element, validate)
            else:
                raise GlifLibError("Unknown element in GLIF: %s" % element)
        # set the collected unicodes
        if unicodes:
            _relaxedSetattr(glyphObject, "unicodes", unicodes)
        # set the collected guidelines
        if guidelines:
            if validate and not guidelinesValidator(guidelines, identifiers):
                raise GlifLibError("The guidelines are improperly formatted.")
            _relaxedSetattr(glyphObject, "guidelines", guidelines)
        # set the collected anchors
        if anchors:
            if validate and not anchorsValidator(anchors, identifiers):
                raise GlifLibError("The anchors are improperly formatted.")
            _relaxedSetattr(glyphObject, "anchors", anchors)

    _READ_GLYPH_FROM_TREE_FUNCS: dict[GLIFFormatVersion, Callable[..., Any]] = {
        GLIFFormatVersion.FORMAT_1_0: _readGlyphFromTreeFormat1,
        GLIFFormatVersion.FORMAT_2_0: _readGlyphFromTreeFormat2,
    }

    def _readName(glyphObject: Optional[Any], root: ElementType, validate: bool) -> None:
        glyphName = root.get("name")
        if validate and not glyphName:
            raise GlifLibError("Empty glyph name in GLIF.")
        if glyphName and glyphObject is not None:
            _relaxedSetattr(glyphObject, "name", glyphName)

    def _readAdvance(glyphObject: Optional[Any], advance: ElementType) -> None:
        width = _number(advance.get("width", 0))
        _relaxedSetattr(glyphObject, "width", width)
        height = _number(advance.get("height", 0))
        _relaxedSetattr(glyphObject, "height", height)

    def _readNote(glyphObject: Optional[Any], note: ElementType) -> None:
        if note.text is None:
            return
        lines = note.text.split("\n")
        note = "\n".join(line.strip() for line in lines if line.strip())
        _relaxedSetattr(glyphObject, "note", note)

    def _readLib(glyphObject: Optional[Any], lib: ElementType, validate: bool) -> None:
        assert len(lib) == 1
        child = lib[0]
        plist = plistlib.fromtree(child)
        if validate:
            valid, message = glyphLibValidator(plist)
            if not valid:
                raise GlifLibError(message)
        _relaxedSetattr(glyphObject, "lib", plist)

    def _readImage(glyphObject: Optional[Any], image: ElementType, validate: bool) -> None:
        imageData = dict(image.attrib)
        for attr, default in _transformationInfo:
            value = imageData.get(attr, default)
            imageData[attr] = _number(value)
        if validate and not imageValidator(imageData):
            raise GlifLibError("The image element is not properly formatted.")
        _relaxedSetattr(glyphObject, "image", imageData)

    # ----------------
    # GLIF to PointPen
    # ----------------

    contourAttributesFormat2: set[str] = {"identifier"}
    componentAttributesFormat1: set[str] = {
        "base",
        "xScale",
        "xyScale",
        "yxScale",
        "yScale",
        "xOffset",
        "yOffset",
    }
    componentAttributesFormat2: set[str] = componentAttributesFormat1 | {"identifier"}
    pointAttributesFormat1: set[str] = {"x", "y", "type", "smooth", "name"}
    pointAttributesFormat2: set[str] = pointAttributesFormat1 | {"identifier"}
    pointSmoothOptions: set[str] = {"no", "yes"}
    pointTypeOptions: set[str] = {"move", "line", "offcurve", "curve", "qcurve"}

    # format 1

    def buildOutlineFormat1(
        glyphObject: Any,
        pen: Optional[AbstractPointPen],
        outline: Iterable[ElementType],
        validate: bool,
    ) -> None:
        anchors = []
        for element in outline:
            if element.tag == "contour":
                if len(element) == 1:
                    point = element[0]
                    if point.tag == "point":
                        anchor = _buildAnchorFormat1(point, validate)
                        if anchor is not None:
                            anchors.append(anchor)
                            continue
                if pen is not None:
                    _buildOutlineContourFormat1(pen, element, validate)
            elif element.tag == "component":
                if pen is not None:
                    _buildOutlineComponentFormat1(pen, element, validate)
            else:
                raise GlifLibError("Unknown element in outline element: %s" % element)
        if glyphObject is not None and anchors:
            if validate and not anchorsValidator(anchors):
                raise GlifLibError("GLIF 1 anchors are not properly formatted.")
            _relaxedSetattr(glyphObject, "anchors", anchors)

    def _buildAnchorFormat1(point: ElementType, validate: bool) -> Optional[dict[str, Any]]:
        if point.get("type") != "move":
            return None
        name = point.get("name")
        if name is None:
            return None
        x = point.get("x")
        y = point.get("y")
        if validate and x is None:
            raise GlifLibError("Required x attribute is missing in point element.")
        assert x is not None
        if validate and y is None:
            raise GlifLibError("Required y attribute is missing in point element.")
        assert y is not None
        x = _number(x)
        y = _number(y)
        anchor = dict(x=x, y=y, name=name)
        return anchor

    def _buildOutlineContourFormat1(
        pen: AbstractPointPen, contour: ElementType, validate: bool
    ) -> None:
        if validate and contour.attrib:
            raise GlifLibError("Unknown attributes in contour element.")
        pen.beginPath()
        if len(contour):
            massaged = _validateAndMassagePointStructures(
                contour,
                pointAttributesFormat1,
                openContourOffCurveLeniency=True,
                validate=validate,
            )
            _buildOutlinePointsFormat1(pen, massaged)
        pen.endPath()

    def _buildOutlinePointsFormat1(
        pen: AbstractPointPen, contour: list[dict[str, Any]]
    ) -> None:
        for point in contour:
            x = point["x"]
            y = point["y"]
            segmentType = point["segmentType"]
            smooth = point["smooth"]
            name = point["name"]
            pen.addPoint((x, y), segmentType=segmentType, smooth=smooth, name=name)

    def _buildOutlineComponentFormat1(
        pen: AbstractPointPen, component: ElementType, validate: bool
    ) -> None:
        if validate:
            if len(component):
                raise GlifLibError("Unknown child elements of component element.")
            for attr in component.attrib.keys():
                if attr not in componentAttributesFormat1:
                    raise GlifLibError("Unknown attribute in component element: %s" % attr)
        baseGlyphName = component.get("base")
        if validate and baseGlyphName is None:
            raise GlifLibError("The base attribute is not defined in the component.")
        assert baseGlyphName is not None
        transformation = tuple(
            _number(component.get(attr) or default) for attr, default in _transformationInfo
        )
        transformation = cast(
            tuple[float, float, float, float, float, float], transformation
        )
        pen.addComponent(baseGlyphName, transformation)

    # format 2

    def buildOutlineFormat2(
        glyphObject: Any,
        pen: AbstractPointPen,
        outline: Iterable[ElementType],
        identifiers: set[str],
        validate: bool,
    ) -> None:
        for element in outline:
            if element.tag == "contour":
                _buildOutlineContourFormat2(pen, element, identifiers, validate)
            elif element.tag == "component":
                _buildOutlineComponentFormat2(pen, element, identifiers, validate)
            else:
                raise GlifLibError("Unknown element in outline element: %s" % element.tag)

    def _buildOutlineContourFormat2(
        pen: AbstractPointPen, contour: ElementType, identifiers: set[str], validate: bool
    ) -> None:
        if validate:
            for attr in contour.attrib.keys():
                if attr not in contourAttributesFormat2:
                    raise GlifLibError("Unknown attribute in contour element: %s" % attr)
        identifier = contour.get("identifier")
        if identifier is not None:
            if validate:
                if identifier in identifiers:
                    raise GlifLibError(
                        "The identifier %s is used more than once." % identifier
                    )
                if not identifierValidator(identifier):
                    raise GlifLibError(
                        "The contour identifier %s is not valid." % identifier
                    )
            identifiers.add(identifier)
        try:
            pen.beginPath(identifier=identifier)
        except TypeError:
            pen.beginPath()
            warn(
                "The beginPath method needs an identifier kwarg. The contour's identifier value has been discarded.",
                DeprecationWarning,
            )
        if len(contour):
            massaged = _validateAndMassagePointStructures(
                contour, pointAttributesFormat2, validate=validate
            )
            _buildOutlinePointsFormat2(pen, massaged, identifiers, validate)
        pen.endPath()

    def _buildOutlinePointsFormat2(
        pen: AbstractPointPen,
        contour: list[dict[str, Any]],
        identifiers: set[str],
        validate: bool,
    ) -> None:
        for point in contour:
            x = point["x"]
            y = point["y"]
            segmentType = point["segmentType"]
            smooth = point["smooth"]
            name = point["name"]
            identifier = point.get("identifier")
            if identifier is not None:
                if validate:
                    if identifier in identifiers:
                        raise GlifLibError(
                            "The identifier %s is used more than once." % identifier
                        )
                    if not identifierValidator(identifier):
                        raise GlifLibError("The identifier %s is not valid." % identifier)
                identifiers.add(identifier)
            try:
                pen.addPoint(
                    (x, y),
                    segmentType=segmentType,
                    smooth=smooth,
                    name=name,
                    identifier=identifier,
                )
            except TypeError:
                pen.addPoint((x, y), segmentType=segmentType, smooth=smooth, name=name)
                warn(
                    "The addPoint method needs an identifier kwarg. The point's identifier value has been discarded.",
                    DeprecationWarning,
                )

    def _buildOutlineComponentFormat2(
        pen: AbstractPointPen, component: ElementType, identifiers: set[str], validate: bool
    ) -> None:
        if validate:
            if len(component):
                raise GlifLibError("Unknown child elements of component element.")
            for attr in component.attrib.keys():
                if attr not in componentAttributesFormat2:
                    raise GlifLibError("Unknown attribute in component element: %s" % attr)
        baseGlyphName = component.get("base")
        if validate and baseGlyphName is None:
            raise GlifLibError("The base attribute is not defined in the component.")
        assert baseGlyphName is not None
        transformation = tuple(
            _number(component.get(attr) or default) for attr, default in _transformationInfo
        )
        transformation = cast(
            tuple[float, float, float, float, float, float], transformation
        )
        identifier = component.get("identifier")
        if identifier is not None:
            if validate:
                if identifier in identifiers:
                    raise GlifLibError(
                        "The identifier %s is used more than once." % identifier
                    )
                if validate and not identifierValidator(identifier):
                    raise GlifLibError("The identifier %s is not valid." % identifier)
            identifiers.add(identifier)
        try:
            pen.addComponent(baseGlyphName, transformation, identifier=identifier)
        except TypeError:
            pen.addComponent(baseGlyphName, transformation)
            warn(
                "The addComponent method needs an identifier kwarg. The component's identifier value has been discarded.",
                DeprecationWarning,
            )

    # all formats

    def _validateAndMassagePointStructures(
        contour, pointAttributes, openContourOffCurveLeniency=False, validate=True
    ):
        if not len(contour):
            return
        # store some data for later validation
        lastOnCurvePoint = None
        haveOffCurvePoint = False
        # validate and massage the individual point elements
        massaged = []
        for index, element in enumerate(contour):
            # not <point>
            if element.tag != "point":
                raise GlifLibError(
                    "Unknown child element (%s) of contour element." % element.tag
                )
            point = dict(element.attrib)
            massaged.append(point)
            if validate:
                # unknown attributes
                for attr in point.keys():
                    if attr not in pointAttributes:
                        raise GlifLibError("Unknown attribute in point element: %s" % attr)
                # search for unknown children
                if len(element):
                    raise GlifLibError("Unknown child elements in point element.")
            # x and y are required
            for attr in ("x", "y"):
                try:
                    point[attr] = _number(point[attr])
                except KeyError as e:
                    raise GlifLibError(
                        f"Required {attr} attribute is missing in point element."
                    ) from e
            # segment type
            pointType = point.pop("type", "offcurve")
            if validate and pointType not in pointTypeOptions:
                raise GlifLibError("Unknown point type: %s" % pointType)
            if pointType == "offcurve":
                pointType = None
            point["segmentType"] = pointType
            if pointType is None:
                haveOffCurvePoint = True
            else:
                lastOnCurvePoint = index
            # move can only occur as the first point
            if validate and pointType == "move" and index != 0:
                raise GlifLibError(
                    "A move point occurs after the first point in the contour."
                )
            # smooth is optional
            smooth = point.get("smooth", "no")
            if validate and smooth is not None:
                if smooth not in pointSmoothOptions:
                    raise GlifLibError("Unknown point smooth value: %s" % smooth)
            smooth = smooth == "yes"
            point["smooth"] = smooth
            # smooth can only be applied to curve and qcurve
            if validate and smooth and pointType is None:
                raise GlifLibError("smooth attribute set in an offcurve point.")
            # name is optional
            if "name" not in element.attrib:
                point["name"] = None
        if openContourOffCurveLeniency:
            # remove offcurves that precede a move. this is technically illegal,
            # but we let it slide because there are fonts out there in the wild like this.
            if massaged[0]["segmentType"] == "move":
                count = 0
                for point in reversed(massaged):
                    if point["segmentType"] is None:
                        count += 1
                    else:
                        break
                if count:
                    massaged = massaged[:-count]
        # validate the off-curves in the segments
        if validate and haveOffCurvePoint and lastOnCurvePoint is not None:
            # we only care about how many offCurves there are before an onCurve
            # filter out the trailing offCurves
            offCurvesCount = len(massaged) - 1 - lastOnCurvePoint
            for point in massaged:
                segmentType = point["segmentType"]
                if segmentType is None:
                    offCurvesCount += 1
                else:
                    if offCurvesCount:
                        # move and line can't be preceded by off-curves
                        if segmentType == "move":
                            # this will have been filtered out already
                            raise GlifLibError("move can not have an offcurve.")
                        elif segmentType == "line":
                            raise GlifLibError("line can not have an offcurve.")
                        elif segmentType == "curve":
                            if offCurvesCount > 2:
                                raise GlifLibError("Too many offcurves defined for curve.")
                        elif segmentType == "qcurve":
                            pass
                        else:
                            # unknown segment type. it'll be caught later.
                            pass
                    offCurvesCount = 0
        return massaged

    # ---------------------
    # Misc Helper Functions
    # ---------------------

    def _relaxedSetattr(object: Any, attr: str, value: Any) -> None:
        try:
            setattr(object, attr, value)
        except AttributeError:
            pass

    def _number(s: Union[str, int, float]) -> IntFloat:
        """
        Given a numeric string, return an integer or a float, whichever
        the string indicates. _number("1") will return the integer 1,
        _number("1.0") will return the float 1.0.

        >>> _number("1")
        1
        >>> _number("1.0")
        1.0
        >>> _number("a")  # doctest: +IGNORE_EXCEPTION_DETAIL
        Traceback (most recent call last):
            ...
        GlifLibError: Could not convert a to an int or float.
        """
        try:
            n: IntFloat = int(s)
            return n
        except ValueError:
            pass
        try:
            n = float(s)
            return n
        except ValueError:
            raise GlifLibError("Could not convert %s to an int or float." % s)

    # --------------------
    # Rapid Value Fetching
    # --------------------

    # base

    class _DoneParsing(Exception):
        pass

    class _BaseParser:
        def __init__(self) -> None:
            self._elementStack: list[str] = []

        def parse(self, text: bytes):
            from xml.parsers.expat import ParserCreate

            parser = ParserCreate()
            parser.StartElementHandler = self.startElementHandler
            parser.EndElementHandler = self.endElementHandler
            parser.Parse(text, True)

        def startElementHandler(self, name: str, attrs: Any) -> None:
            self._elementStack.append(name)

        def endElementHandler(self, name: str) -> None:
            other = self._elementStack.pop(-1)
            assert other == name

    # unicodes

    def _fetchUnicodes(glif: bytes) -> list[int]:
        """
        Get a list of unicodes listed in glif.
        """
        parser = _FetchUnicodesParser()
        parser.parse(glif)
        return parser.unicodes

    class _FetchUnicodesParser(_BaseParser):
        def __init__(self) -> None:
            self.unicodes: list[int] = []
            super().__init__()

        def startElementHandler(self, name: str, attrs: dict[str, str]) -> None:
            if (
                name == "unicode"
                and self._elementStack
                and self._elementStack[-1] == "glyph"
            ):
                value = attrs.get("hex")
                if value is not None:
                    try:
                        intValue = int(value, 16)
                        if intValue not in self.unicodes:
                            self.unicodes.append(intValue)
                    except ValueError:
                        pass
            super().startElementHandler(name, attrs)

    # image

    def _fetchImageFileName(glif: bytes) -> Optional[str]:
        """
        The image file name (if any) from glif.
        """
        parser = _FetchImageFileNameParser()
        try:
            parser.parse(glif)
        except _DoneParsing:
            pass
        return parser.fileName

    class _FetchImageFileNameParser(_BaseParser):
        def __init__(self) -> None:
            self.fileName: Optional[str] = None
            super().__init__()

        def startElementHandler(self, name: str, attrs: dict[str, str]) -> None:
            if name == "image" and self._elementStack and self._elementStack[-1] == "glyph":
                self.fileName = attrs.get("fileName")
                raise _DoneParsing
            super().startElementHandler(name, attrs)

    # component references

    def _fetchComponentBases(glif: bytes) -> list[str]:
        """
        Get a list of component base glyphs listed in glif.
        """
        parser = _FetchComponentBasesParser()
        try:
            parser.parse(glif)
        except _DoneParsing:
            pass
        return list(parser.bases)

    class _FetchComponentBasesParser(_BaseParser):
        def __init__(self) -> None:
            self.bases: list[str] = []
            super().__init__()

        def startElementHandler(self, name: str, attrs: dict[str, str]) -> None:
            if (
                name == "component"
                and self._elementStack
                and self._elementStack[-1] == "outline"
            ):
                base = attrs.get("base")
                if base is not None:
                    self.bases.append(base)
            super().startElementHandler(name, attrs)

        def endElementHandler(self, name: str) -> None:
            if name == "outline":
                raise _DoneParsing
            super().endElementHandler(name)

    # --------------
    # GLIF Point Pen
    # --------------

    _transformationInfo: list[tuple[str, int]] = [
        # field name, default value
        ("xScale", 1),
        ("xyScale", 0),
        ("yxScale", 0),
        ("yScale", 1),
        ("xOffset", 0),
        ("yOffset", 0),
    ]

    class GLIFPointPen(AbstractPointPen):
        """
        Helper class using the PointPen protocol to write the <outline>
        part of .glif files.
        """

        def __init__(
            self,
            element: ElementType,
            formatVersion: Optional[FormatVersion] = None,
            identifiers: Optional[set[str]] = None,
            validate: bool = True,
        ) -> None:
            if identifiers is None:
                identifiers = set()
            self.formatVersion = normalizeFormatVersion(formatVersion, GLIFFormatVersion)
            self.identifiers = identifiers
            self.outline = element
            self.contour = None
            self.prevOffCurveCount = 0
            self.prevPointTypes: list[str] = []
            self.validate = validate

        def beginPath(self, identifier=None, **kwargs):
            attrs = OrderedDict()
            if identifier is not None and self.formatVersion.major >= 2:
                if self.validate:
                    if identifier in self.identifiers:
                        raise GlifLibError(
                            "identifier used more than once: %s" % identifier
                        )
                    if not identifierValidator(identifier):
                        raise GlifLibError(
                            "identifier not formatted properly: %s" % identifier
                        )
                attrs["identifier"] = identifier
                self.identifiers.add(identifier)
            self.contour = etree.SubElement(self.outline, "contour", attrs)
            self.prevOffCurveCount = 0

        def endPath(self):
            if self.prevPointTypes and self.prevPointTypes[0] == "move":
                if self.validate and self.prevPointTypes[-1] == "offcurve":
                    raise GlifLibError("open contour has loose offcurve point")
            # prevent lxml from writing self-closing tags
            if not len(self.contour):
                self.contour.text = "\n  "
            self.contour = None
            self.prevPointType = None
            self.prevOffCurveCount = 0
            self.prevPointTypes = []

        def addPoint(
            self, pt, segmentType=None, smooth=None, name=None, identifier=None, **kwargs
        ):
            attrs = OrderedDict()
            # coordinates
            if pt is not None:
                if self.validate:
                    for coord in pt:
                        if not isinstance(coord, numberTypes):
                            raise GlifLibError("coordinates must be int or float")
                attrs["x"] = repr(pt[0])
                attrs["y"] = repr(pt[1])
            # segment type
            if segmentType == "offcurve":
                segmentType = None
            if self.validate:
                if segmentType == "move" and self.prevPointTypes:
                    raise GlifLibError(
                        "move occurs after a point has already been added to the contour."
                    )
                if (
                    segmentType in ("move", "line")
                    and self.prevPointTypes
                    and self.prevPointTypes[-1] == "offcurve"
                ):
                    raise GlifLibError("offcurve occurs before %s point." % segmentType)
                if segmentType == "curve" and self.prevOffCurveCount > 2:
                    raise GlifLibError("too many offcurve points before curve point.")
            if segmentType is not None:
                attrs["type"] = segmentType
            else:
                segmentType = "offcurve"
            if segmentType == "offcurve":
                self.prevOffCurveCount += 1
            else:
                self.prevOffCurveCount = 0
            self.prevPointTypes.append(segmentType)
            # smooth
            if smooth:
                if self.validate and segmentType == "offcurve":
                    raise GlifLibError("can't set smooth in an offcurve point.")
                attrs["smooth"] = "yes"
            # name
            if name is not None:
                attrs["name"] = name
            # identifier
            if identifier is not None and self.formatVersion.major >= 2:
                if self.validate:
                    if identifier in self.identifiers:
                        raise GlifLibError(
                            "identifier used more than once: %s" % identifier
                        )
                    if not identifierValidator(identifier):
                        raise GlifLibError(
                            "identifier not formatted properly: %s" % identifier
                        )
                attrs["identifier"] = identifier
                self.identifiers.add(identifier)
            etree.SubElement(self.contour, "point", attrs)

        def addComponent(self, glyphName, transformation, identifier=None, **kwargs):
            attrs = OrderedDict([("base", glyphName)])
            for (attr, default), value in zip(_transformationInfo, transformation):
                if self.validate and not isinstance(value, numberTypes):
                    raise GlifLibError("transformation values must be int or float")
                if value != default:
                    attrs[attr] = repr(value)
            if identifier is not None and self.formatVersion.major >= 2:
                if self.validate:
                    if identifier in self.identifiers:
                        raise GlifLibError(
                            "identifier used more than once: %s" % identifier
                        )
                    if self.validate and not identifierValidator(identifier):
                        raise GlifLibError(
                            "identifier not formatted properly: %s" % identifier
                        )
                attrs["identifier"] = identifier
                self.identifiers.add(identifier)
            etree.SubElement(self.outline, "component", attrs)

    if __name__ == "__main__":
        import doctest

        doctest.testmod()