Mercurial > public > mercurial-scm > hg
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 |
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 ... |