tikv-python 0.1.0__py3-none-any.whl

tikv/_proto/metapb_pb2.py

@@ -0,0 +1,39 @@
+# Generated by scripts/generate_protos.py. DO NOT EDIT.
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: metapb.proto
+# Protobuf Python Version: 4.25.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x0cmetapb.proto\x12\x06metapb\"\xb5\x01\n\x06Region\x12\n\n\x02id\x18\x01 \x01(\x04\x12\x11\n\tstart_key\x18\x02 \x01(\x0c\x12\x0f\n\x07\x65nd_key\x18\x03 \x01(\x0c\x12)\n\x0cregion_epoch\x18\x04 \x01(\x0b\x32\x13.metapb.RegionEpoch\x12\x1b\n\x05peers\x18\x05 \x03(\x0b\x32\x0c.metapb.Peer\x12\x17\n\x0fis_in_flashback\x18\x07 \x01(\x08\x12\x1a\n\x12\x66lashback_start_ts\x18\x08 \x01(\x04\"0\n\x0bRegionEpoch\x12\x10\n\x08\x63onf_ver\x18\x01 \x01(\x04\x12\x0f\n\x07version\x18\x02 \x01(\x04\"X\n\x04Peer\x12\n\n\x02id\x18\x01 \x01(\x04\x12\x10\n\x08store_id\x18\x02 \x01(\x04\x12\x1e\n\x04role\x18\x03 \x01(\x0e\x32\x10.metapb.PeerRole\x12\x12\n\nis_witness\x18\x04 \x01(\x08\"(\n\nStoreLabel\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t\"\xaa\x01\n\x05Store\x12\n\n\x02id\x18\x01 \x01(\x04\x12\x0f\n\x07\x61\x64\x64ress\x18\x02 \x01(\t\x12!\n\x05state\x18\x03 \x01(\x0e\x32\x12.metapb.StoreState\x12\"\n\x06labels\x18\x04 \x03(\x0b\x32\x12.metapb.StoreLabel\x12\x0f\n\x07version\x18\x05 \x01(\t\x12\x14\n\x0cpeer_address\x18\x06 \x01(\t\x12\x16\n\x0estatus_address\x18\x07 \x01(\t*H\n\x08PeerRole\x12\t\n\x05Voter\x10\x00\x12\x0b\n\x07Learner\x10\x01\x12\x11\n\rIncomingVoter\x10\x02\x12\x11\n\rDemotingVoter\x10\x03*0\n\nStoreState\x12\x06\n\x02Up\x10\x00\x12\x0b\n\x07Offline\x10\x01\x12\r\n\tTombstone\x10\x02\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'metapb_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_PEERROLE']._serialized_start=563
+  _globals['_PEERROLE']._serialized_end=635
+  _globals['_STORESTATE']._serialized_start=637
+  _globals['_STORESTATE']._serialized_end=685
+  _globals['_REGION']._serialized_start=25
+  _globals['_REGION']._serialized_end=206
+  _globals['_REGIONEPOCH']._serialized_start=208
+  _globals['_REGIONEPOCH']._serialized_end=256
+  _globals['_PEER']._serialized_start=258
+  _globals['_PEER']._serialized_end=346
+  _globals['_STORELABEL']._serialized_start=348
+  _globals['_STORELABEL']._serialized_end=388
+  _globals['_STORE']._serialized_start=391
+  _globals['_STORE']._serialized_end=561
+# @@protoc_insertion_point(module_scope)

tikv/_proto/metapb_pb2.pyi

@@ -0,0 +1,92 @@
+# Generated by scripts/generate_protos.py. DO NOT EDIT.
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class PeerRole(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    Voter: _ClassVar[PeerRole]
+    Learner: _ClassVar[PeerRole]
+    IncomingVoter: _ClassVar[PeerRole]
+    DemotingVoter: _ClassVar[PeerRole]
+
+class StoreState(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    Up: _ClassVar[StoreState]
+    Offline: _ClassVar[StoreState]
+    Tombstone: _ClassVar[StoreState]
+Voter: PeerRole
+Learner: PeerRole
+IncomingVoter: PeerRole
+DemotingVoter: PeerRole
+Up: StoreState
+Offline: StoreState
+Tombstone: StoreState
+
+class Region(_message.Message):
+    __slots__ = ("id", "start_key", "end_key", "region_epoch", "peers", "is_in_flashback", "flashback_start_ts")
+    ID_FIELD_NUMBER: _ClassVar[int]
+    START_KEY_FIELD_NUMBER: _ClassVar[int]
+    END_KEY_FIELD_NUMBER: _ClassVar[int]
+    REGION_EPOCH_FIELD_NUMBER: _ClassVar[int]
+    PEERS_FIELD_NUMBER: _ClassVar[int]
+    IS_IN_FLASHBACK_FIELD_NUMBER: _ClassVar[int]
+    FLASHBACK_START_TS_FIELD_NUMBER: _ClassVar[int]
+    id: int
+    start_key: bytes
+    end_key: bytes
+    region_epoch: RegionEpoch
+    peers: _containers.RepeatedCompositeFieldContainer[Peer]
+    is_in_flashback: bool
+    flashback_start_ts: int
+    def __init__(self, id: _Optional[int] = ..., start_key: _Optional[bytes] = ..., end_key: _Optional[bytes] = ..., region_epoch: _Optional[_Union[RegionEpoch, _Mapping]] = ..., peers: _Optional[_Iterable[_Union[Peer, _Mapping]]] = ..., is_in_flashback: bool = ..., flashback_start_ts: _Optional[int] = ...) -> None: ...
+
+class RegionEpoch(_message.Message):
+    __slots__ = ("conf_ver", "version")
+    CONF_VER_FIELD_NUMBER: _ClassVar[int]
+    VERSION_FIELD_NUMBER: _ClassVar[int]
+    conf_ver: int
+    version: int
+    def __init__(self, conf_ver: _Optional[int] = ..., version: _Optional[int] = ...) -> None: ...
+
+class Peer(_message.Message):
+    __slots__ = ("id", "store_id", "role", "is_witness")
+    ID_FIELD_NUMBER: _ClassVar[int]
+    STORE_ID_FIELD_NUMBER: _ClassVar[int]
+    ROLE_FIELD_NUMBER: _ClassVar[int]
+    IS_WITNESS_FIELD_NUMBER: _ClassVar[int]
+    id: int
+    store_id: int
+    role: PeerRole
+    is_witness: bool
+    def __init__(self, id: _Optional[int] = ..., store_id: _Optional[int] = ..., role: _Optional[_Union[PeerRole, str]] = ..., is_witness: bool = ...) -> None: ...
+
+class StoreLabel(_message.Message):
+    __slots__ = ("key", "value")
+    KEY_FIELD_NUMBER: _ClassVar[int]
+    VALUE_FIELD_NUMBER: _ClassVar[int]
+    key: str
+    value: str
+    def __init__(self, key: _Optional[str] = ..., value: _Optional[str] = ...) -> None: ...
+
+class Store(_message.Message):
+    __slots__ = ("id", "address", "state", "labels", "version", "peer_address", "status_address")
+    ID_FIELD_NUMBER: _ClassVar[int]
+    ADDRESS_FIELD_NUMBER: _ClassVar[int]
+    STATE_FIELD_NUMBER: _ClassVar[int]
+    LABELS_FIELD_NUMBER: _ClassVar[int]
+    VERSION_FIELD_NUMBER: _ClassVar[int]
+    PEER_ADDRESS_FIELD_NUMBER: _ClassVar[int]
+    STATUS_ADDRESS_FIELD_NUMBER: _ClassVar[int]
+    id: int
+    address: str
+    state: StoreState
+    labels: _containers.RepeatedCompositeFieldContainer[StoreLabel]
+    version: str
+    peer_address: str
+    status_address: str
+    def __init__(self, id: _Optional[int] = ..., address: _Optional[str] = ..., state: _Optional[_Union[StoreState, str]] = ..., labels: _Optional[_Iterable[_Union[StoreLabel, _Mapping]]] = ..., version: _Optional[str] = ..., peer_address: _Optional[str] = ..., status_address: _Optional[str] = ...) -> None: ...

tikv/_proto/pdpb_pb2.py

@@ -0,0 +1,56 @@
+# Generated by scripts/generate_protos.py. DO NOT EDIT.
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: pdpb.proto
+# Protobuf Python Version: 4.25.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from . import metapb_pb2 as metapb__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\npdpb.proto\x12\x04pdpb\x1a\x0cmetapb.proto\"c\n\rRequestHeader\x12\x12\n\ncluster_id\x18\x01 \x01(\x04\x12\x11\n\tsender_id\x18\x02 \x01(\x04\x12\x11\n\tcaller_id\x18\x03 \x01(\t\x12\x18\n\x10\x63\x61ller_component\x18\x04 \x01(\t\"@\n\x0eResponseHeader\x12\x12\n\ncluster_id\x18\x01 \x01(\x04\x12\x1a\n\x05\x65rror\x18\x02 \x01(\x0b\x32\x0b.pdpb.Error\"7\n\x05\x45rror\x12\x1d\n\x04type\x18\x01 \x01(\x0e\x32\x0f.pdpb.ErrorType\x12\x0f\n\x07message\x18\x02 \x01(\t\"Q\n\x06Member\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x11\n\tmember_id\x18\x02 \x01(\x04\x12\x11\n\tpeer_urls\x18\x03 \x03(\t\x12\x13\n\x0b\x63lient_urls\x18\x04 \x03(\t\"8\n\x11GetMembersRequest\x12#\n\x06header\x18\x01 \x01(\x0b\x32\x13.pdpb.RequestHeader\"w\n\x12GetMembersResponse\x12$\n\x06header\x18\x01 \x01(\x0b\x32\x14.pdpb.ResponseHeader\x12\x1d\n\x07members\x18\x02 \x03(\x0b\x32\x0c.pdpb.Member\x12\x1c\n\x06leader\x18\x03 \x01(\x0b\x32\x0c.pdpb.Member\"H\n\x0fGetStoreRequest\x12#\n\x06header\x18\x01 \x01(\x0b\x32\x13.pdpb.RequestHeader\x12\x10\n\x08store_id\x18\x02 \x01(\x04\"V\n\x10GetStoreResponse\x12$\n\x06header\x18\x01 \x01(\x0b\x32\x14.pdpb.ResponseHeader\x12\x1c\n\x05store\x18\x02 \x01(\x0b\x32\r.metapb.Store\"K\n\x10GetRegionRequest\x12#\n\x06header\x18\x01 \x01(\x0b\x32\x13.pdpb.RequestHeader\x12\x12\n\nregion_key\x18\x02 \x01(\x0c\"w\n\x11GetRegionResponse\x12$\n\x06header\x18\x01 \x01(\x0b\x32\x14.pdpb.ResponseHeader\x12\x1e\n\x06region\x18\x02 \x01(\x0b\x32\x0e.metapb.Region\x12\x1c\n\x06leader\x18\x03 \x01(\x0b\x32\x0c.metapb.Peer\"l\n\x12ScanRegionsRequest\x12#\n\x06header\x18\x01 \x01(\x0b\x32\x13.pdpb.RequestHeader\x12\x11\n\tstart_key\x18\x02 \x01(\x0c\x12\r\n\x05limit\x18\x03 \x01(\x05\x12\x0f\n\x07\x65nd_key\x18\x04 \x01(\x0c\"F\n\x06Region\x12\x1e\n\x06region\x18\x01 \x01(\x0b\x32\x0e.metapb.Region\x12\x1c\n\x06leader\x18\x02 \x01(\x0b\x32\x0c.metapb.Peer\"\x9f\x01\n\x13ScanRegionsResponse\x12$\n\x06header\x18\x01 \x01(\x0b\x32\x14.pdpb.ResponseHeader\x12$\n\x0cregion_metas\x18\x02 \x03(\x0b\x32\x0e.metapb.Region\x12\x1d\n\x07leaders\x18\x03 \x03(\x0b\x32\x0c.metapb.Peer\x12\x1d\n\x07regions\x18\x04 \x03(\x0b\x32\x0c.pdpb.Region*\xab\x02\n\tErrorType\x12\x06\n\x02OK\x10\x00\x12\x0b\n\x07UNKNOWN\x10\x01\x12\x14\n\x10NOT_BOOTSTRAPPED\x10\x02\x12\x13\n\x0fSTORE_TOMBSTONE\x10\x03\x12\x18\n\x14\x41LREADY_BOOTSTRAPPED\x10\x04\x12\x18\n\x14INCOMPATIBLE_VERSION\x10\x05\x12\x14\n\x10REGION_NOT_FOUND\x10\x06\x12\x1b\n\x17GLOBAL_CONFIG_NOT_FOUND\x10\x07\x12\x14\n\x10\x44UPLICATED_ENTRY\x10\x08\x12\x13\n\x0f\x45NTRY_NOT_FOUND\x10\t\x12\x11\n\rINVALID_VALUE\x10\n\x12\x12\n\x0e\x44\x41TA_COMPACTED\x10\x0b\x12%\n!REGIONS_NOT_CONTAIN_ALL_KEY_RANGE\x10\x0c\x32\xce\x02\n\x02PD\x12\x41\n\nGetMembers\x12\x17.pdpb.GetMembersRequest\x1a\x18.pdpb.GetMembersResponse\"\x00\x12;\n\x08GetStore\x12\x15.pdpb.GetStoreRequest\x1a\x16.pdpb.GetStoreResponse\"\x00\x12>\n\tGetRegion\x12\x16.pdpb.GetRegionRequest\x1a\x17.pdpb.GetRegionResponse\"\x00\x12\x42\n\rGetPrevRegion\x12\x16.pdpb.GetRegionRequest\x1a\x17.pdpb.GetRegionResponse\"\x00\x12\x44\n\x0bScanRegions\x12\x18.pdpb.ScanRegionsRequest\x1a\x19.pdpb.ScanRegionsResponse\"\x00\x62\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'pdpb_pb2', _globals)
+if _descriptor._USE_C_DESCRIPTORS == False:
+  DESCRIPTOR._options = None
+  _globals['_ERRORTYPE']._serialized_start=1225
+  _globals['_ERRORTYPE']._serialized_end=1524
+  _globals['_REQUESTHEADER']._serialized_start=34
+  _globals['_REQUESTHEADER']._serialized_end=133
+  _globals['_RESPONSEHEADER']._serialized_start=135
+  _globals['_RESPONSEHEADER']._serialized_end=199
+  _globals['_ERROR']._serialized_start=201
+  _globals['_ERROR']._serialized_end=256
+  _globals['_MEMBER']._serialized_start=258
+  _globals['_MEMBER']._serialized_end=339
+  _globals['_GETMEMBERSREQUEST']._serialized_start=341
+  _globals['_GETMEMBERSREQUEST']._serialized_end=397
+  _globals['_GETMEMBERSRESPONSE']._serialized_start=399
+  _globals['_GETMEMBERSRESPONSE']._serialized_end=518
+  _globals['_GETSTOREREQUEST']._serialized_start=520
+  _globals['_GETSTOREREQUEST']._serialized_end=592
+  _globals['_GETSTORERESPONSE']._serialized_start=594
+  _globals['_GETSTORERESPONSE']._serialized_end=680
+  _globals['_GETREGIONREQUEST']._serialized_start=682
+  _globals['_GETREGIONREQUEST']._serialized_end=757
+  _globals['_GETREGIONRESPONSE']._serialized_start=759
+  _globals['_GETREGIONRESPONSE']._serialized_end=878
+  _globals['_SCANREGIONSREQUEST']._serialized_start=880
+  _globals['_SCANREGIONSREQUEST']._serialized_end=988
+  _globals['_REGION']._serialized_start=990
+  _globals['_REGION']._serialized_end=1060
+  _globals['_SCANREGIONSRESPONSE']._serialized_start=1063
+  _globals['_SCANREGIONSRESPONSE']._serialized_end=1222
+  _globals['_PD']._serialized_start=1527
+  _globals['_PD']._serialized_end=1861
+# @@protoc_insertion_point(module_scope)

tikv/_proto/pdpb_pb2.pyi

@@ -0,0 +1,160 @@
+# Generated by scripts/generate_protos.py. DO NOT EDIT.
+from . import metapb_pb2 as _metapb_pb2
+from google.protobuf.internal import containers as _containers
+from google.protobuf.internal import enum_type_wrapper as _enum_type_wrapper
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import message as _message
+from typing import ClassVar as _ClassVar, Iterable as _Iterable, Mapping as _Mapping, Optional as _Optional, Union as _Union
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class ErrorType(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+    __slots__ = ()
+    OK: _ClassVar[ErrorType]
+    UNKNOWN: _ClassVar[ErrorType]
+    NOT_BOOTSTRAPPED: _ClassVar[ErrorType]
+    STORE_TOMBSTONE: _ClassVar[ErrorType]
+    ALREADY_BOOTSTRAPPED: _ClassVar[ErrorType]
+    INCOMPATIBLE_VERSION: _ClassVar[ErrorType]
+    REGION_NOT_FOUND: _ClassVar[ErrorType]
+    GLOBAL_CONFIG_NOT_FOUND: _ClassVar[ErrorType]
+    DUPLICATED_ENTRY: _ClassVar[ErrorType]
+    ENTRY_NOT_FOUND: _ClassVar[ErrorType]
+    INVALID_VALUE: _ClassVar[ErrorType]
+    DATA_COMPACTED: _ClassVar[ErrorType]
+    REGIONS_NOT_CONTAIN_ALL_KEY_RANGE: _ClassVar[ErrorType]
+OK: ErrorType
+UNKNOWN: ErrorType
+NOT_BOOTSTRAPPED: ErrorType
+STORE_TOMBSTONE: ErrorType
+ALREADY_BOOTSTRAPPED: ErrorType
+INCOMPATIBLE_VERSION: ErrorType
+REGION_NOT_FOUND: ErrorType
+GLOBAL_CONFIG_NOT_FOUND: ErrorType
+DUPLICATED_ENTRY: ErrorType
+ENTRY_NOT_FOUND: ErrorType
+INVALID_VALUE: ErrorType
+DATA_COMPACTED: ErrorType
+REGIONS_NOT_CONTAIN_ALL_KEY_RANGE: ErrorType
+
+class RequestHeader(_message.Message):
+    __slots__ = ("cluster_id", "sender_id", "caller_id", "caller_component")
+    CLUSTER_ID_FIELD_NUMBER: _ClassVar[int]
+    SENDER_ID_FIELD_NUMBER: _ClassVar[int]
+    CALLER_ID_FIELD_NUMBER: _ClassVar[int]
+    CALLER_COMPONENT_FIELD_NUMBER: _ClassVar[int]
+    cluster_id: int
+    sender_id: int
+    caller_id: str
+    caller_component: str
+    def __init__(self, cluster_id: _Optional[int] = ..., sender_id: _Optional[int] = ..., caller_id: _Optional[str] = ..., caller_component: _Optional[str] = ...) -> None: ...
+
+class ResponseHeader(_message.Message):
+    __slots__ = ("cluster_id", "error")
+    CLUSTER_ID_FIELD_NUMBER: _ClassVar[int]
+    ERROR_FIELD_NUMBER: _ClassVar[int]
+    cluster_id: int
+    error: Error
+    def __init__(self, cluster_id: _Optional[int] = ..., error: _Optional[_Union[Error, _Mapping]] = ...) -> None: ...
+
+class Error(_message.Message):
+    __slots__ = ("type", "message")
+    TYPE_FIELD_NUMBER: _ClassVar[int]
+    MESSAGE_FIELD_NUMBER: _ClassVar[int]
+    type: ErrorType
+    message: str
+    def __init__(self, type: _Optional[_Union[ErrorType, str]] = ..., message: _Optional[str] = ...) -> None: ...
+
+class Member(_message.Message):
+    __slots__ = ("name", "member_id", "peer_urls", "client_urls")
+    NAME_FIELD_NUMBER: _ClassVar[int]
+    MEMBER_ID_FIELD_NUMBER: _ClassVar[int]
+    PEER_URLS_FIELD_NUMBER: _ClassVar[int]
+    CLIENT_URLS_FIELD_NUMBER: _ClassVar[int]
+    name: str
+    member_id: int
+    peer_urls: _containers.RepeatedScalarFieldContainer[str]
+    client_urls: _containers.RepeatedScalarFieldContainer[str]
+    def __init__(self, name: _Optional[str] = ..., member_id: _Optional[int] = ..., peer_urls: _Optional[_Iterable[str]] = ..., client_urls: _Optional[_Iterable[str]] = ...) -> None: ...
+
+class GetMembersRequest(_message.Message):
+    __slots__ = ("header",)
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    header: RequestHeader
+    def __init__(self, header: _Optional[_Union[RequestHeader, _Mapping]] = ...) -> None: ...
+
+class GetMembersResponse(_message.Message):
+    __slots__ = ("header", "members", "leader")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    MEMBERS_FIELD_NUMBER: _ClassVar[int]
+    LEADER_FIELD_NUMBER: _ClassVar[int]
+    header: ResponseHeader
+    members: _containers.RepeatedCompositeFieldContainer[Member]
+    leader: Member
+    def __init__(self, header: _Optional[_Union[ResponseHeader, _Mapping]] = ..., members: _Optional[_Iterable[_Union[Member, _Mapping]]] = ..., leader: _Optional[_Union[Member, _Mapping]] = ...) -> None: ...
+
+class GetStoreRequest(_message.Message):
+    __slots__ = ("header", "store_id")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    STORE_ID_FIELD_NUMBER: _ClassVar[int]
+    header: RequestHeader
+    store_id: int
+    def __init__(self, header: _Optional[_Union[RequestHeader, _Mapping]] = ..., store_id: _Optional[int] = ...) -> None: ...
+
+class GetStoreResponse(_message.Message):
+    __slots__ = ("header", "store")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    STORE_FIELD_NUMBER: _ClassVar[int]
+    header: ResponseHeader
+    store: _metapb_pb2.Store
+    def __init__(self, header: _Optional[_Union[ResponseHeader, _Mapping]] = ..., store: _Optional[_Union[_metapb_pb2.Store, _Mapping]] = ...) -> None: ...
+
+class GetRegionRequest(_message.Message):
+    __slots__ = ("header", "region_key")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    REGION_KEY_FIELD_NUMBER: _ClassVar[int]
+    header: RequestHeader
+    region_key: bytes
+    def __init__(self, header: _Optional[_Union[RequestHeader, _Mapping]] = ..., region_key: _Optional[bytes] = ...) -> None: ...
+
+class GetRegionResponse(_message.Message):
+    __slots__ = ("header", "region", "leader")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    REGION_FIELD_NUMBER: _ClassVar[int]
+    LEADER_FIELD_NUMBER: _ClassVar[int]
+    header: ResponseHeader
+    region: _metapb_pb2.Region
+    leader: _metapb_pb2.Peer
+    def __init__(self, header: _Optional[_Union[ResponseHeader, _Mapping]] = ..., region: _Optional[_Union[_metapb_pb2.Region, _Mapping]] = ..., leader: _Optional[_Union[_metapb_pb2.Peer, _Mapping]] = ...) -> None: ...
+
+class ScanRegionsRequest(_message.Message):
+    __slots__ = ("header", "start_key", "limit", "end_key")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    START_KEY_FIELD_NUMBER: _ClassVar[int]
+    LIMIT_FIELD_NUMBER: _ClassVar[int]
+    END_KEY_FIELD_NUMBER: _ClassVar[int]
+    header: RequestHeader
+    start_key: bytes
+    limit: int
+    end_key: bytes
+    def __init__(self, header: _Optional[_Union[RequestHeader, _Mapping]] = ..., start_key: _Optional[bytes] = ..., limit: _Optional[int] = ..., end_key: _Optional[bytes] = ...) -> None: ...
+
+class Region(_message.Message):
+    __slots__ = ("region", "leader")
+    REGION_FIELD_NUMBER: _ClassVar[int]
+    LEADER_FIELD_NUMBER: _ClassVar[int]
+    region: _metapb_pb2.Region
+    leader: _metapb_pb2.Peer
+    def __init__(self, region: _Optional[_Union[_metapb_pb2.Region, _Mapping]] = ..., leader: _Optional[_Union[_metapb_pb2.Peer, _Mapping]] = ...) -> None: ...
+
+class ScanRegionsResponse(_message.Message):
+    __slots__ = ("header", "region_metas", "leaders", "regions")
+    HEADER_FIELD_NUMBER: _ClassVar[int]
+    REGION_METAS_FIELD_NUMBER: _ClassVar[int]
+    LEADERS_FIELD_NUMBER: _ClassVar[int]
+    REGIONS_FIELD_NUMBER: _ClassVar[int]
+    header: ResponseHeader
+    region_metas: _containers.RepeatedCompositeFieldContainer[_metapb_pb2.Region]
+    leaders: _containers.RepeatedCompositeFieldContainer[_metapb_pb2.Peer]
+    regions: _containers.RepeatedCompositeFieldContainer[Region]
+    def __init__(self, header: _Optional[_Union[ResponseHeader, _Mapping]] = ..., region_metas: _Optional[_Iterable[_Union[_metapb_pb2.Region, _Mapping]]] = ..., leaders: _Optional[_Iterable[_Union[_metapb_pb2.Peer, _Mapping]]] = ..., regions: _Optional[_Iterable[_Union[Region, _Mapping]]] = ...) -> None: ...

tikv/_region.py

@@ -0,0 +1,228 @@
+"""Region routing: which region owns a key, and who leads it.
+
+Everything here is pure, in-memory bookkeeping shared by the sync and async
+clients.  Network I/O lives in ``_async`` (and the generated ``_sync``).
+"""
+
+from __future__ import annotations
+
+import bisect
+import threading
+from dataclasses import dataclass, replace
+
+from ._backoff import Wait
+from ._errors import RegionError, UndeterminedError
+from ._proto import errorpb_pb2, kvrpcpb_pb2, metapb_pb2
+
+# Reverse scans need an exclusive upper bound, and TiKV treats an empty one as
+# "nothing" rather than "+inf".  This key sorts after every key TiKV accepts
+# (``storage.max-key-size`` defaults to 8 KiB), so it stands in for +inf.
+MAX_KEY = b"\xff" * (8 * 1024 + 1)
+
+
+@dataclass(frozen=True, slots=True)
+class Region:
+    """A contiguous key range ``[start, end)`` served by one Raft group.
+
+    An empty ``end`` means the region extends to +inf.
+    """
+
+    meta: metapb_pb2.Region
+    leader: metapb_pb2.Peer | None
+
+    @property
+    def id(self) -> int:
+        return self.meta.id
+
+    @property
+    def start(self) -> bytes:
+        return self.meta.start_key
+
+    @property
+    def end(self) -> bytes:
+        return self.meta.end_key
+
+    def contains(self, key: bytes) -> bool:
+        return self.start <= key and (not self.end or key < self.end)
+
+    def contains_end(self, key: bytes) -> bool:
+        """Whether *key*, as an exclusive upper bound, falls in this region."""
+        return self.start < key and (not self.end or key <= self.end)
+
+    def context(self) -> kvrpcpb_pb2.Context:
+        """The request context that routes a request to this region's leader."""
+        return kvrpcpb_pb2.Context(
+            region_id=self.meta.id, region_epoch=self.meta.region_epoch, peer=self.leader
+        )
+
+    def __repr__(self) -> str:
+        epoch = self.meta.region_epoch
+        leader = self.leader.store_id if self.leader else None
+        return (
+            f"Region(id={self.id}, start={self.start!r}, end={self.end!r}, "
+            f"epoch={epoch.conf_ver}:{epoch.version}, leader_store={leader})"
+        )
+
+
+def make_region(meta: metapb_pb2.Region, leader: metapb_pb2.Peer | None) -> Region:
+    """Build a :class:`Region`, treating PD's empty leader (id 0) as unknown."""
+    return Region(meta, leader if leader is not None and leader.id else None)
+
+
+class RegionCache:
+    """Thread-safe cache of regions (sorted by start key) and store addresses."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._starts: list[bytes] = []
+        self._regions: list[Region] = []
+        self._stores: dict[int, str] = {}
+
+    def find(self, key: bytes) -> Region | None:
+        """The cached region containing *key*, if any."""
+        with self._lock:
+            i = bisect.bisect_right(self._starts, key) - 1
+            if i >= 0 and self._regions[i].contains(key):
+                return self._regions[i]
+        return None
+
+    def find_end(self, key: bytes) -> Region | None:
+        """The cached region where *key* is a valid exclusive upper bound."""
+        with self._lock:
+            i = bisect.bisect_left(self._starts, key) - 1
+            if i >= 0 and self._regions[i].contains_end(key):
+                return self._regions[i]
+        return None
+
+    def put(self, region: Region) -> None:
+        """Cache *region*, evicting any cached region it overlaps."""
+        with self._lock:
+            lo = bisect.bisect_right(self._starts, region.start) - 1
+            if lo < 0 or not self._overlaps(self._regions[lo], region):
+                lo += 1
+            hi = lo
+            while hi < len(self._regions) and self._overlaps(self._regions[hi], region):
+                hi += 1
+            self._starts[lo:hi] = [region.start]
+            self._regions[lo:hi] = [region]
+
+    @staticmethod
+    def _overlaps(a: Region, b: Region) -> bool:
+        return (not a.end or b.start < a.end) and (not b.end or a.start < b.end)
+
+    def invalidate(self, region: Region) -> None:
+        """Forget *region* so the next lookup asks PD again."""
+        with self._lock:
+            i = bisect.bisect_left(self._starts, region.start)
+            if i < len(self._regions) and self._regions[i].id == region.id:
+                del self._starts[i]
+                del self._regions[i]
+
+    def update_leader(self, region: Region, leader: metapb_pb2.Peer) -> bool:
+        """Point *region* at a new *leader*; False if the peer is unknown."""
+        for peer in region.meta.peers:
+            if peer.store_id == leader.store_id:
+                with self._lock:
+                    i = bisect.bisect_left(self._starts, region.start)
+                    # Only patch the entry we routed with; if it was replaced
+                    # meanwhile, the newer entry wins.
+                    if i < len(self._regions) and self._regions[i].meta == region.meta:
+                        self._regions[i] = replace(region, leader=peer)
+                return True
+        self.invalidate(region)
+        return False
+
+    def store_address(self, store_id: int) -> str | None:
+        return self._stores.get(store_id)
+
+    def set_store_address(self, store_id: int, address: str) -> None:
+        self._stores[store_id] = address
+
+    def forget_store(self, store_id: int) -> None:
+        self._stores.pop(store_id, None)
+
+    def clear(self) -> None:
+        with self._lock:
+            self._starts.clear()
+            self._regions.clear()
+            self._stores.clear()
+
+
+def on_region_error(
+    cache: RegionCache,
+    region: Region,
+    error: errorpb_pb2.Error,
+    *,
+    idempotent: bool,
+) -> tuple[Wait, float]:
+    """Update *cache* after *region* reported *error*; decide how to retry.
+
+    Returns the backoff reason and a server-suggested minimum delay.  Raises
+    when retrying cannot help.  The policy follows client-go and client-rust.
+    """
+    store_id = region.leader.store_id if region.leader else 0
+    kind = _kind(error)
+
+    if kind == "not_leader":
+        if error.not_leader.HasField("leader") and cache.update_leader(region, error.not_leader.leader):
+            return Wait.REGION_SCHEDULING, 0.0
+        cache.invalidate(region)  # leader unknown: an election is in progress
+        return Wait.REGION_SCHEDULING, 0.0
+    if kind == "server_is_busy":
+        return Wait.SERVER_BUSY, error.server_is_busy.backoff_ms / 1000
+    if kind == "raft_entry_too_large":
+        raise RegionError(f"request too large for region {region.id}: {error.message}")
+    if kind in _MAYBE_APPLIED and not idempotent:
+        # The write may have been proposed before this error: replaying it
+        # could apply it twice, so let the caller decide.
+        detail = error.undetermined_result.message
+        raise UndeterminedError(describe_region_error(region, error) + (f" ({detail})" if detail else ""))
+    if kind in _SCHEDULING:
+        return Wait.REGION_SCHEDULING, 0.0
+    if kind == "disk_full":
+        return Wait.SERVER_BUSY, 0.0
+
+    # Epoch changes, missing regions, store mismatches and anything unknown:
+    # the cached routing is stale, so refetch it from PD.
+    cache.invalidate(region)
+    if kind not in _REGION_ONLY and store_id:
+        cache.forget_store(store_id)
+    return Wait.REGION_MISS, 0.0
+
+
+# Transient conditions that resolve once the region settles.
+_SCHEDULING = frozenset(
+    {
+        "stale_command",
+        "max_timestamp_not_synced",
+        "read_index_not_ready",
+        "proposal_in_merging_mode",
+        "data_is_not_ready",
+        "region_not_initialized",
+        "RecoveryInProgress",
+        "FlashbackInProgress",
+        "FlashbackNotPrepared",
+        "undetermined_result",
+    }
+)
+# Errors a store may report after proposing a write to Raft, so the write
+# might still be applied: TiKV answers pending proposals with RegionNotFound
+# when the peer is destroyed, and with StaleCommand when leadership changes.
+_MAYBE_APPLIED = frozenset({"undetermined_result", "region_not_found", "stale_command"})
+# Stale routing that does not implicate the store address.
+_REGION_ONLY = frozenset({"epoch_not_match", "region_not_found", "key_not_in_region"})
+
+_KINDS = tuple(field.name for field in errorpb_pb2.Error.DESCRIPTOR.fields if field.message_type is not None)
+
+
+def describe_region_error(region: Region, error: errorpb_pb2.Error) -> str:
+    """A one-line summary such as ``region 12: epoch_not_match: ...``."""
+    return f"region {region.id}: {_kind(error) or 'error'}: {error.message}".rstrip(": ")
+
+
+def _kind(error: errorpb_pb2.Error) -> str | None:
+    """The name of the specific error field set on *error*, if any."""
+    for name in _KINDS:
+        if error.HasField(name):
+            return name
+    return None