annotate mercurial/interfaces/modules.py @ 51976:54d9f496f07a

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()`.
author Matt Harbison <matt_harbison@yahoo.com>
date Sat, 05 Oct 2024 15:00:37 -0400
parents fa7059f031a9
children d7f17819ae9e
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
51969
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
1 # modules.py - protocol classes for dynamically loaded modules
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
2 #
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
3 # This software may be used and distributed according to the terms of the
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
4 # GNU General Public License version 2 or any later version.
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
5
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
6 from __future__ import annotations
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
7
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
8 import typing
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
9
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
10 from typing import (
51970
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
11 Callable,
51969
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
12 List,
51970
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
13 Optional,
51969
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
14 Protocol,
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
15 Tuple,
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
16 )
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
17
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
18 if typing.TYPE_CHECKING:
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
19 BDiffBlock = Tuple[int, int, int, int]
51970
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
20 """An entry in the list returned by bdiff.{xdiff,}blocks()."""
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
21
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
22 BDiffBlocksFnc = Callable[[bytes, bytes], List[BDiffBlock]]
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
23 """The signature of `bdiff.blocks()` and `bdiff.xdiffblocks()`."""
51969
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
24
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
25
51974
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
26 class Base85(Protocol):
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
27 """A Protocol class for the various base85 module implementations."""
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
28
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
29 def b85encode(self, text: bytes, pad: bool = False) -> bytes:
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
30 """encode text in base85 format"""
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
31
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
32 def b85decode(self, text: bytes) -> bytes:
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
33 """decode base85-encoded text"""
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
34
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51970
diff changeset
35
51969
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
36 class BDiff(Protocol):
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
37 """A Protocol class for the various bdiff module implementations."""
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
38
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
39 def splitnewlines(self, text: bytes) -> List[bytes]:
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
40 """like str.splitlines, but only split on newlines."""
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
41
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
42 def bdiff(self, a: bytes, b: bytes) -> bytes:
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
43 ...
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
44
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
45 def blocks(self, a: bytes, b: bytes) -> List[BDiffBlock]:
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
46 ...
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
47
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
48 def fixws(self, text: bytes, allws: bool) -> bytes:
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
49 ...
51970
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
50
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
51 xdiffblocks: Optional[BDiffBlocksFnc]
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51969
diff changeset
52 """This method is currently only available in the ``cext`` module."""
51976
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
53
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
54
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
55 class CharEncoding(Protocol):
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
56 """A Protocol class for the various charencoding module implementations."""
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
57
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
58 def isasciistr(self, s: bytes) -> bool:
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
59 """Can the byte string be decoded with the ``ascii`` codec?"""
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
60
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
61 def asciilower(self, s: bytes) -> bytes:
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
62 """convert a string to lowercase if ASCII
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
63
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
64 Raises UnicodeDecodeError if non-ASCII characters are found."""
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
65
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
66 def asciiupper(self, s: bytes) -> bytes:
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
67 """convert a string to uppercase if ASCII
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
68
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
69 Raises UnicodeDecodeError if non-ASCII characters are found."""
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
70
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
71 def jsonescapeu8fast(self, u8chars: bytes, paranoid: bool) -> bytes:
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
72 """Convert a UTF-8 byte string to JSON-escaped form (fast path)
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
73
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
74 Raises ValueError if non-ASCII characters have to be escaped.
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51974
diff changeset
75 """