Skip to content

Header

Tannic protocol header utilities.

This module defines the binary header format used for tensor and metadata transport over networks or in files.

Header layout (little-endian):

[magic: 4 bytes][version: 1 byte][checksum: 2 bytes][nbytes: 8 bytes]
  • magic : 32-bit unsigned int identifying the protocol (default: ASCII 'ERIC')
  • version : 8-bit unsigned int protocol version
  • checksum : 16-bit unsigned int for optional payload verification
  • nbytes : 64-bit unsigned int size of the payload in bytes

Header dataclass

Binary header for tannic tensor/metadata messages.

Attributes

magic : int Protocol identifier (default: MAGIC). version : int Protocol version number. checksum : int Optional checksum for payload validation. nbytes : int Size of the payload in bytes.

Class Attributes

FORMAT : str Struct format string for packing/unpacking: "<I B H Q" (little-endian: uint32, uint8, uint16, uint64)

Source code in pytannic/header.py 
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@dataclass
class Header:
    """
    Binary header for tannic tensor/metadata messages.

    Attributes
    ----------
    magic : int
        Protocol identifier (default: `MAGIC`).
    version : int
        Protocol version number.
    checksum : int
        Optional checksum for payload validation.
    nbytes : int
        Size of the payload in bytes.

    Class Attributes
    ----------------
    FORMAT : str
        Struct format string for packing/unpacking:
        `"<I B H Q"` (little-endian: uint32, uint8, uint16, uint64)
    """
    FORMAT = "<I B H Q"   
    magic: int
    version: int
    checksum: int
    nbytes: int 

    def pack(self) -> bytes:
        """
        Pack the header fields into a binary representation.

        Returns
        -------
        bytes
            Serialized header in little-endian byte order.
        """
        return pack(
            self.FORMAT,
            self.magic,
            self.version,
            self.checksum,
            self.nbytes, 
        )

    @classmethod
    def unpack(cls, data: bytes):
        """
        Deserialize a binary blob into a Header instance.

        Parameters
        ----------
        data : bytes
            Byte string of length equal to `calcsize(Header.FORMAT)`.

        Returns
        -------
        Header
            Header instance with fields populated from `data`.

        Raises
        ------
        struct.error
            If `data` does not match the expected format length.
        """
        unpacked = unpack(cls.FORMAT, data)
        return cls(*unpacked)

pack()

Pack the header fields into a binary representation.

Returns

bytes Serialized header in little-endian byte order.

Source code in pytannic/header.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
def pack(self) -> bytes:
    """
    Pack the header fields into a binary representation.

    Returns
    -------
    bytes
        Serialized header in little-endian byte order.
    """
    return pack(
        self.FORMAT,
        self.magic,
        self.version,
        self.checksum,
        self.nbytes, 
    )

unpack(data) classmethod

Deserialize a binary blob into a Header instance.

Parameters

data : bytes Byte string of length equal to calcsize(Header.FORMAT).

Returns

Header Header instance with fields populated from data.

Raises

struct.error If data does not match the expected format length.

Source code in pytannic/header.py 
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@classmethod
def unpack(cls, data: bytes):
    """
    Deserialize a binary blob into a Header instance.

    Parameters
    ----------
    data : bytes
        Byte string of length equal to `calcsize(Header.FORMAT)`.

    Returns
    -------
    Header
        Header instance with fields populated from `data`.

    Raises
    ------
    struct.error
        If `data` does not match the expected format length.
    """
    unpacked = unpack(cls.FORMAT, data)
    return cls(*unpacked)