API Reference#

class icspacket.proto.tpkt.TPKT(vrsn: int = 3, reserved: int = 0, length: int = 0, tpdu: bytes = b'')[source]#

Frames a single TPDU for transmission over a TCP byte stream, according to RFC 1006, section 6.

TCP has no notion of message boundaries, so every TPDU handed to it is prefixed with this fixed 4-byte header before being written to the socket; the header’s length field is what lets the receiving side figure out where one TPDU ends and the next begins.

vrsn: int = 3#

Protocol version marker. This implementation always writes 3 and treats any other value seen on the wire as a sign of a corrupt or unsupported packet.

reserved: int = 0#

Reserved for future use

length: int = 0#

Byte count of the whole TPKT, header and encapsulated TPDU together.

tpdu: bytes = b''#

Payload carried by this TPKT; its byte count is derived from the header as length - 4.

static from_octets(octets: bytes) → TPKT[source]#

Deserialize a TPKT from a raw byte sequence.

Parameters:

octets (bytes) – Byte buffer containing at least one full TPKT.

Raises:

ValueError – If the length field does not match the actual number of received octets.

Returns:

Parsed TPKT instance.

Return type:

TPKT

build() → bytes[source]#

Serialize the TPKT into its octet representation.

Updates the length field based on the TPDU size and produces a byte sequence suitable for transmission over TCP.

Returns:

Encoded TPKT packet.

Return type:

bytes

class icspacket.proto.tpkt.tpktsock(family: int = -1, type: int = -1, proto: int = -1, fileno: int | None = None)[source]#

Socket wrapper that transparently applies TPKT encapsulation.

This class extends socket.socket to provide automatic encoding and decoding of ISO 8073 (TPKT) headers for connection-oriented transport protocols. Applications can use tpktsock as a drop-in replacement for raw sockets when working with TPKT-based communication.

Enhancements since 0.2.4:

  • An internal queue.Queue (in_queue) is now used to buffer partially received or multiple consecutive TPKT PDUs.

  • Improved handling of cases where more than one PDU arrives in a single TCP segment. Excess packets are queued for later retrieval.

  • Extended validation ensures incomplete headers are safely discarded and logged.

Changed in version 0.2.4: Added internal buffering and support for multiple PDUs per TCP segment.

in_queue: Queue[bytes]#

Internal queue for buffered TPKT PDUs awaiting delivery.

Added in version 0.2.4.

unpack_tpkt(octets: bytes) → bytes[source]#

Unpack a TPKT-encapsulated buffer.

Parameters:

octets (bytes) – Raw bytes received from the socket.

Returns:

Extracted TPDU payload.

Return type:

bytes

recv(bufsize: int, flags: int = 0, /) → bytes[source]#

Receive a TPKT-encapsulated payload.

If multiple PDUs are present in a single TCP segment, the first is returned immediately and subsequent ones are stored in in_queue for later retrieval.

Parameters:

  • bufsize (int) – Maximum number of bytes to read from the socket.

  • flags (int) – Optional flags passed through to the underlying socket.socket.recv().

Returns:

The payload of a single decoded TPKT PDU.

Return type:

bytes

Raises:

ValueError – If the received header length is inconsistent with the actual payload size.

Changed in version 0.2.4: Now returns buffered PDUs if available and supports handling multiple PDUs per TCP segment.

recvfrom(bufsize: int, flags: int = 0, /) → tuple[bytes, tuple][source]#

Receive a TPKT packet along with the sender’s address.

Parameters:

  • bufsize (int) – Maximum number of bytes to receive.

  • flags (int, optional) – Optional socket flags.

Returns:

A tuple of (TPDU bytes, sender address).

Return type:

tuple[bytes, tuple]

send(data: bytes, flags: int = 0, /) → int[source]#

Send TPDU bytes, encapsulated into a TPKT.

Parameters:

  • data (bytes) – The raw TPDU bytes to send.

  • flags (int, optional) – Optional socket flags.

Returns:

Number of bytes sent.

Return type:

int

sendall(data: bytes, flags: int = 0, /) → None[source]#

Send all TPDU bytes, encapsulated into a TPKT.

Ensures the entire buffer is transmitted, as in the standard socket.socket.sendall().

Parameters:

  • data (bytes) – The raw TPDU bytes to send.

  • flags (int, optional) – Optional socket flags.

sendto(data: bytes, address: tuple, /) → int[source]#

Send TPDU bytes, encapsulated into a TPKT, to a specific address.

Parameters:

  • data (bytes) – The raw TPDU bytes to send.

  • address (tuple) – Destination address (host, port).

Returns:

Number of bytes sent.

Return type:

int