Skip to content

Commit 9bcf867

Browse files
committed
docs: improve the docstrings and add missing typing
1 parent 3b82557 commit 9bcf867

File tree

1 file changed

+48
-45
lines changed

1 file changed

+48
-45
lines changed

pymysqlreplication/binlogstream.py

Lines changed: 48 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55

66
import pymysql
77
from pymysql.constants.COMMAND import COM_BINLOG_DUMP, COM_REGISTER_SLAVE
8-
from pymysql.cursors import DictCursor, Cursor
8+
from pymysql.cursors import Cursor, DictCursor
9+
from pymysql.connections import Connection, MysqlPacket
910

1011
from .constants.BINLOG import TABLE_MAP_EVENT, ROTATE_EVENT, FORMAT_DESCRIPTION_EVENT
1112
from .event import (
@@ -21,7 +22,6 @@
2122
from .row_event import (
2223
UpdateRowsEvent, WriteRowsEvent, DeleteRowsEvent, TableMapEvent)
2324
from typing import ByteString, Union, Optional, List, Tuple, Dict, Any, Iterator, FrozenSet, Type
24-
from pymysql.connections import Connection
2525

2626
try:
2727
from pymysql.constants.COMMAND import COM_BINLOG_DUMP_GTID
@@ -36,8 +36,10 @@
3636

3737

3838
class ReportSlave(object):
39-
"""Represent the values that you may report when connecting as a slave
40-
to a master. SHOW SLAVE HOSTS related"""
39+
"""
40+
Represent the values that you may report
41+
when connecting as a slave to a master. SHOW SLAVE HOSTS related.
42+
"""
4143

4244
def __init__(self, value: Union[str, Tuple[str, str, str, int]]) -> None:
4345
"""
@@ -74,9 +76,9 @@ def __repr__(self) -> str:
7476

7577
def encoded(self, server_id: int, master_id: int = 0) -> ByteString:
7678
"""
77-
server_id: the slave server-id
78-
master_id: usually 0. Appears as "master id" in SHOW SLAVE HOSTS
79-
on the master. Unknown what else it impacts.
79+
:ivar server_id: int - the slave server-id
80+
:ivar master_id: int - usually 0. Appears as "master id" in SHOW SLAVE HOSTS on the master.
81+
Unknown what else it impacts.
8082
"""
8183

8284
# 1 [15] COM_REGISTER_SLAVE
@@ -124,9 +126,10 @@ def encoded(self, server_id: int, master_id: int = 0) -> ByteString:
124126

125127

126128
class BinLogStreamReader(object):
127-
"""Connect to replication stream and read event
128129
"""
129-
report_slave: Optional[ReportSlave] = None
130+
Connect to replication stream and read event
131+
"""
132+
report_slave: Optional[Union[str, Tuple[str, str, str, int]]] = None
130133

131134
def __init__(self, connection_settings: Dict, server_id: int,
132135
ctl_connection_settings: Optional[Dict] = None, resume_stream: bool = False,
@@ -137,7 +140,7 @@ def __init__(self, connection_settings: Dict, server_id: int,
137140
only_tables: Optional[List[str]] = None, ignored_tables: Optional[List[str]] = None,
138141
only_schemas: Optional[List[str]] = None, ignored_schemas: Optional[List[str]] = None,
139142
freeze_schema: bool = False, skip_to_timestamp: Optional[float] = None,
140-
report_slave: Optional[ReportSlave] = None, slave_uuid: Optional[str] = None,
143+
report_slave: Optional[Union[str, Tuple[str, str, str, int]]] = None, slave_uuid: Optional[str] = None,
141144
pymysql_wrapper: Optional[Connection] = None,
142145
fail_on_table_metadata_unavailable: bool = False,
143146
slave_heartbeat: Optional[float] = None,
@@ -146,44 +149,42 @@ def __init__(self, connection_settings: Dict, server_id: int,
146149
ignore_decode_errors: bool = False) -> None:
147150
"""
148151
Attributes:
149-
ctl_connection_settings: Connection settings for cluster holding
152+
ctl_connection_settings[Dict]: Connection settings for cluster holding
150153
schema information
151-
resume_stream: Start for event from position or the latest event of
154+
resume_stream[bool]: Start for event from position or the latest event of
152155
binlog or from older available event
153-
blocking: When master has finished reading/sending binlog it will
156+
blocking[bool]: When master has finished reading/sending binlog it will
154157
send EOF instead of blocking connection.
155-
only_events: Array of allowed events
156-
ignored_events: Array of ignored events
157-
log_file: Set replication start log file
158-
log_pos: Set replication start log pos (resume_stream should be
158+
only_events[List[str]]: Array of allowed events
159+
ignored_events[List[str]]: Array of ignored events
160+
log_file[str]: Set replication start log file
161+
log_pos[int]: Set replication start log pos (resume_stream should be
159162
true)
160-
end_log_pos: Set replication end log pos
161-
auto_position: Use master_auto_position gtid to set position
162-
only_tables: An array with the tables you want to watch (only works
163+
end_log_pos[int]: Set replication end log pos
164+
auto_position[str]: Use master_auto_position gtid to set position
165+
only_tables[List[str]]: An array with the tables you want to watch (only works
163166
in binlog_format ROW)
164-
ignored_tables: An array with the tables you want to skip
165-
only_schemas: An array with the schemas you want to watch
166-
ignored_schemas: An array with the schemas you want to skip
167-
freeze_schema: If true do not support ALTER TABLE. It's faster.
168-
skip_to_timestamp: Ignore all events until reaching specified
169-
timestamp.
170-
report_slave: Report slave in SHOW SLAVE HOSTS.
171-
slave_uuid: Report slave_uuid or replica_uuid in SHOW SLAVE HOSTS(MySQL 8.0.21-) or
167+
ignored_tables[List[str]]: An array with the tables you want to skip
168+
only_schemas[List[str]]: An array with the schemas you want to watch
169+
ignored_schemas[List[str]]: An array with the schemas you want to skip
170+
freeze_schema[bool]: If true do not support ALTER TABLE. It's faster.
171+
skip_to_timestamp[float]: Ignore all events until reaching specified timestamp.
172+
report_slave[ReportSlave]: Report slave in SHOW SLAVE HOSTS.
173+
slave_uuid[str]: Report slave_uuid or replica_uuid in SHOW SLAVE HOSTS(MySQL 8.0.21-) or
172174
SHOW REPLICAS(MySQL 8.0.22+) depends on your MySQL version.
173-
fail_on_table_metadata_unavailable: Should raise exception if we
174-
can't get table information on
175-
row_events
176-
slave_heartbeat: (seconds) Should master actively send heartbeat on
175+
fail_on_table_metadata_unavailable[bool]: Should raise exception if we
176+
can't get table information on row_events
177+
slave_heartbeat[float]: (seconds) Should master actively send heartbeat on
177178
connection. This also reduces traffic in GTID
178179
replication on replication resumption (in case
179180
many event to skip in binlog). See
180181
MASTER_HEARTBEAT_PERIOD in mysql documentation
181182
for semantics
182-
is_mariadb: Flag to indicate it's a MariaDB server, used with auto_position
183+
is_mariadb[bool]: Flag to indicate it's a MariaDB server, used with auto_position
183184
to point to Mariadb specific GTID.
184-
annotate_rows_event: Parameter value to enable annotate rows event in mariadb,
185+
annotate_rows_event[bool]: Parameter value to enable annotate rows event in mariadb,
185186
used with 'is_mariadb'
186-
ignore_decode_errors: If true, any decode errors encountered
187+
ignore_decode_errors[bool]: If true, any decode errors encountered
187188
when reading column data will be ignored.
188189
"""
189190

@@ -230,12 +231,12 @@ def __init__(self, connection_settings: Dict, server_id: int,
230231
self.is_past_end_log_pos: bool = False
231232

232233
if report_slave:
233-
self.report_slave: Optional[ReportSlave] = ReportSlave(report_slave)
234+
self.report_slave: ReportSlave = ReportSlave(report_slave)
234235
self.slave_uuid: Optional[str] = slave_uuid
235236
self.slave_heartbeat: Optional[float] = slave_heartbeat
236237

237238
if pymysql_wrapper:
238-
self.pymysql_wrapper: Optional[Connection] = pymysql_wrapper
239+
self.pymysql_wrapper: Connection = pymysql_wrapper
239240
else:
240241
self.pymysql_wrapper: Optional[Union[Connection, Type[Connection]]] = pymysql.connect
241242
self.mysql_version: Tuple = (0, 0, 0)
@@ -262,7 +263,9 @@ def __connect_to_ctl(self) -> None:
262263
self.__connected_ctl: bool = True
263264

264265
def __checksum_enabled(self) -> bool:
265-
"""Return True if binlog-checksum = CRC32. Only for MySQL > 5.6"""
266+
"""
267+
Return True if binlog-checksum = CRC32. Only for MySQL > 5.6
268+
"""
266269
cur: Cursor = self._stream_connection.cursor()
267270
cur.execute("SHOW GLOBAL VARIABLES LIKE 'BINLOG_CHECKSUM'")
268271
result: Optional[Tuple[str, str]] = cur.fetchone()
@@ -295,19 +298,19 @@ def __connect_to_stream(self) -> None:
295298
# flags (2) BINLOG_DUMP_NON_BLOCK (0 or 1)
296299
# server_id (4) -- server id of this slave
297300
# log_file (string.EOF) -- filename of the binlog on the master
298-
self._stream_connection = self.pymysql_wrapper(**self.__connection_settings)
301+
self._stream_connection: Connection = self.pymysql_wrapper(**self.__connection_settings)
299302

300303
self.__use_checksum: bool = self.__checksum_enabled()
301304

302305
# If checksum is enabled we need to inform the server about the that
303306
# we support it
304307
if self.__use_checksum:
305-
cur = self._stream_connection.cursor()
308+
cur: Cursor = self._stream_connection.cursor()
306309
cur.execute("SET @master_binlog_checksum= @@global.binlog_checksum")
307310
cur.close()
308311

309312
if self.slave_uuid:
310-
cur = self._stream_connection.cursor()
313+
cur: Cursor = self._stream_connection.cursor()
311314
cur.execute("SET @slave_uuid = %s, @replica_uuid = %s", (self.slave_uuid, self.slave_uuid))
312315
cur.close()
313316

@@ -339,14 +342,14 @@ def __connect_to_stream(self) -> None:
339342

340343
if not self.auto_position:
341344
if self.is_mariadb:
342-
prelude = self.__set_mariadb_settings()
345+
prelude: ByteString = self.__set_mariadb_settings()
343346
else:
344347
# only when log_file and log_pos both provided, the position info is
345348
# valid, if not, get the current position from master
346349
if self.log_file is None or self.log_pos is None:
347350
cur: Cursor = self._stream_connection.cursor()
348351
cur.execute("SHOW MASTER STATUS")
349-
master_status: Optional[Tuple[str, int, ...]] = cur.fetchone()
352+
master_status: Optional[Tuple[str, int, Any]] = cur.fetchone()
350353
if master_status is None:
351354
raise BinLogNotEnabled()
352355
self.log_file, self.log_pos = master_status[:2]
@@ -507,9 +510,9 @@ def fetchone(self) -> Union[BinLogPacketWrapper, None]:
507510

508511
try:
509512
if pymysql.__version__ < LooseVersion("0.6"):
510-
pkt = self._stream_connection.read_packet()
513+
pkt: MysqlPacket = self._stream_connection.read_packet()
511514
else:
512-
pkt = self._stream_connection._read_packet()
515+
pkt: MysqlPacket = self._stream_connection._read_packet()
513516
except pymysql.OperationalError as error:
514517
code, message = error.args
515518
if code in MYSQL_EXPECTED_ERROR_CODES:

0 commit comments

Comments
 (0)