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