GTID documentation

Document:

- Gtid.encode
- Gtid.decode
- GtidSet.encode
- GtidSet.encode
- Gtid.__contains__

Author: darnuria

pymysqlreplication/gtid.py

@@ -139,6 +139,12 @@ def __sub_interval(self, itvl):
         self.intervals = new
 
     def __contains__(self, other):
+        """Test if other is contained within self.
+        First we compare sid they must be equals.
+
+        Then we search if intervals from other are contained within
+        self intervals.
+        """
         if other.sid != self.sid:
             return False
 
@@ -204,6 +210,31 @@ def encoded_length(self):
                 len(self.intervals))
 
     def encode(self):
+        """Encode a Gtid in binary
+        Bytes are in **little endian**.
+
+        Format:
+
+        - sid will be uncoded as hex-binary without the dashes as a [u8; 16]
+        - size of the interval list as a u64
+        - all the interval as a pair: (start: u64, end: u64).
+
+        ## Diagram
+
+        ```txt
+        Alligned on u64 bit.
+        +-+-+-+-+-+-+-+-+-+-+
+        | sid [16;u8]       |
+        |                   |
+        +-+-+-+-+-+-+-+-+-+-+
+        | intervals_len u64 |
+        +-+-+-+-+-+-+-+-+-+-+
+        |start u64             <-+
+        - - - - - - - - - - -    + Repeated
+        |stop u64              <-+  interval_len times
+        - - - - - - - - - - -
+        ```
+        """
         buffer = b''
         # sid
         buffer += binascii.unhexlify(self.sid.replace('-', ''))
@@ -220,6 +251,10 @@ def encode(self):
 
     @classmethod
     def decode(cls, payload):
+        """Decode from binary a Gtid
+
+        :param BytesIO payload to decode
+        """
         assert isinstance(payload, BytesIO), \
             'payload is expected to be a BytesIO'
         sid = b''
@@ -368,13 +403,33 @@ def encoded_length(self):
                 sum(x.encoded_length for x in self.gtids))
 
     def encoded(self):
+        """Encode a GtidSet in binary
+        Bytes are in **little endian**.
+
+        - `n_sid`: u64 is the number of Gtid to read
+        - `Gtid`: `n_sid` * `Gtid_encoded_size` times.
+          See`Gtid.encode` documentation for details.
+
+        ```txt
+        Alligned on u64 bit.
+        +-+-+-+-+-+-+-+-+-+-+
+        | n_gtid u64        |
+        +-+-+-+-+-+-+-+-+-+-+
+        | Gtid              | - Repeated n_gtid times
+        - - - - - - - - - - -
+        ```
+        """
         return b'' + (struct.pack('<Q', len(self.gtids)) +
                       b''.join(x.encode() for x in self.gtids))
 
     encode = encoded
 
     @classmethod
     def decode(cls, payload):
+        """Decode a GtidSet from binary.
+
+        :param BytesIO payload to decode
+        """
         assert isinstance(payload, BytesIO), \
             'payload is expected to be a BytesIO'
         (n_sid,) = struct.unpack('<Q', payload.read(8))