API Reference

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

TPKT header structure as defined in [RFC 1006] section 6.

This class models the ISO transport service packetization layer on top of TCP, which introduces a simple 4-byte header in front of each TPDU.

vrsn: int = 3

Version number of the TPKT protocol. This value is fixed to 3. If any other value is received, the packet should be considered invalid.

reserved: int = 0

Reserved for future use

length: int = 0

Total length of the TPKT in octets, including the 4-byte header.

tpdu: bytes = b''

The encapsulated TPDU bytes. The size is determined by 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