annotate mercurial/interfaces/modules.py @ 51960:d7f17819ae9e

interfaces: introduce and use a protocol class for the `mpatch` module See f2832de2a46c for details when this was done for the `bdiff` module. Two things worth pointing out- 1) The `cffi` module "inherits" the `pure` implementation of `patchedsize()` because of its wildcard import. 2) It's odd that the `mpatchError` lives in both `pure` and `cext` modules. I initially thought to move the exception into the new class, and make the existing class name an alias to the class in the new location, but the exception is created in C code by the `cext` module, so that won't work. I don't think a protocol class is approriate, because there's nothing special about the class to distinguish from any other `Exception`. Fortunately, nobody is catching this exception in core, so we can kick the can down the road.
author Matt Harbison <matt_harbison@yahoo.com>
date Sat, 05 Oct 2024 18:58:20 -0400
parents 54d9f496f07a
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
51929
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 (
51930
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
11 Callable,
51929
f2832de2a46c interfaces: introduce and use a protocol class for the `bdiff` module
Matt Harbison <matt_harbison@yahoo.com>
parents:
diff changeset
12 List,
51930
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
13 Optional,
51929
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]
51930
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
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: 51929
diff changeset
21
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
22 BDiffBlocksFnc = Callable[[bytes, bytes], List[BDiffBlock]]
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
23 """The signature of `bdiff.blocks()` and `bdiff.xdiffblocks()`."""
51929
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
51934
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51930
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: 51930
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: 51930
diff changeset
28
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51930
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: 51930
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: 51930
diff changeset
31
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51930
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: 51930
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: 51930
diff changeset
34
fa7059f031a9 interfaces: introduce and use a protocol class for the `base85` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51930
diff changeset
35
51929
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 ...
51930
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
50
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
51 xdiffblocks: Optional[BDiffBlocksFnc]
09f3a6790e56 interfaces: add the optional `bdiff.xdiffblocks()` method
Matt Harbison <matt_harbison@yahoo.com>
parents: 51929
diff changeset
52 """This method is currently only available in the ``cext`` module."""
51936
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
diff changeset
53
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
diff changeset
54
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
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: 51934
diff changeset
57
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
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: 51934
diff changeset
60
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
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: 51934
diff changeset
63
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
diff changeset
65
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
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: 51934
diff changeset
68
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
diff changeset
70
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
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: 51934
diff changeset
73
54d9f496f07a interfaces: introduce and use a protocol class for the `charencoding` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51934
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: 51934
diff changeset
75 """
51960
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
76
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
77
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
78 class MPatch(Protocol):
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
79 """A protocol class for the various mpatch module implementations."""
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
80
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
81 def patches(self, a: bytes, bins: List[bytes]) -> bytes:
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
82 ...
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
83
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
84 def patchedsize(self, orig: int, delta: bytes) -> int:
d7f17819ae9e interfaces: introduce and use a protocol class for the `mpatch` module
Matt Harbison <matt_harbison@yahoo.com>
parents: 51936
diff changeset
85 ...