mercurial/typelib.py

interfaces: introduce and use a protocol class for the `charencoding` module

See f2832de2a46c for details when this was done for the `bdiff` module.

This lets us dump the hack where the `pure` implementation was imported during
the type checking phase to provide signatures for the module methods it
provides.  Now the protocol classes are starting to shine, because these methods
are provided by `pure.charencoding` and `cext.parsers`, and references to
`cffi.charencoding` and `cext.charencoding` are forwarded to them as appropriate
by the `policy` module.  But none of that matters, as long as the module
returned provides the listed methods.

The interface was copy/pasted from the `pure` module, but `jsonescapeu8fallback`
is omitted because it is accessed from the `pure` module directly when the
escaping fails in the primary module's `jsonescapeu8()`.

# typelib.py - type hint aliases and support
#
# Copyright 2022 Matt Harbison <[e-mail]>
#
# This software may be used and distributed according to the terms of the
# GNU General Public License version 2 or any later version.

from __future__ import annotations

import typing

from typing import (
    Callable,
)

# Note: this is slightly different from pycompat.TYPE_CHECKING, as using
# pycompat causes the BinaryIO_Proxy type to be resolved to ``object`` when
# used as the base class during a pytype run.
TYPE_CHECKING = typing.TYPE_CHECKING


# The BinaryIO class provides empty methods, which at runtime means that
# ``__getattr__`` on the proxy classes won't get called for the methods that
# should delegate to the internal object.  So to avoid runtime changes because
# of the required typing inheritance, just use BinaryIO when typechecking, and
# ``object`` otherwise.
if TYPE_CHECKING:
    from typing import (
        BinaryIO,
        Union,
    )

    from . import (
        node,
        posix,
        windows,
    )

    BinaryIO_Proxy = BinaryIO
    CacheStat = Union[posix.cachestat, windows.cachestat]
    NodeConstants = node.sha1nodeconstants
else:
    from typing import Any

    BinaryIO_Proxy = object
    CacheStat = Any
    NodeConstants = Any

# scmutil.getuipathfn() related callback.
UiPathFn = Callable[[bytes], bytes]