pak.types.array

Types for contiguous data of the same Type.

class Array(elem_type, size=None)

Bases: Type

A Type for contiguous data.

Parameters:

  • elem_type (typelike) – The Type contained in the Array.

  • size (int or typelike or str or function or None) –

    The size of the Array.

    If an int, then the Array has a fixed size of size. This case will be deferred to Array.FixedSize.

    If a typelike, then the Array is prefixed by the typelike, and its value determines the number of elements in the Array. This case will be deferred to Array.SizePrefixed.

    If None, then the Array is read until the end of the buffer. This case will be deferred to Array.Unbounded.

    If a str, then the size is determined by getting the attribute of the same name from the Packet instance. This case will be deferred to Array.FunctionSized.

    If a function, then the size is determined by passing the Packet instance to the function. This case will be deferred to Array.FunctionSized.

class FixedSize(elem_type, size)

Bases: Array

An Array with a fixed size.

Parameters:

  • elem_type (typelike) – The Type contained in the Array.

  • size (int) – The number of elements in the Array.

Examples

>>> import pak
>>> pak.Int8[2].unpack(b"\x00\x01")
[0, 1]
>>> pak.Int8[2].pack([0, 1])
b'\x00\x01'
class FunctionSized(elem_type, size)

Bases: Array

An Array whose size is determined by calling a function.

The function will be passed the relevant Packet instance, and should return the number of elements in the Array.

Parameters:

  • elem_type (typelike) – The Type contained in the Array.

  • size (function or str) –

    If a function, then the number of elements of the Array is determined by calling the function with the relevant Packet instance.

    If a str, then a function which gets and returns the attribute named by the str is used as the effective function for the size of the Array.

Examples

If a str is used as size:

>>> import pak
>>> class MyPacket(pak.Packet):
...     length: pak.Int8
...     array:  pak.Int8["length"]
...
>>> packet = MyPacket.unpack(b"\x02\x00\x01")
>>> packet
MyPacket(length=2, array=[0, 1])
>>> packet.pack()
b'\x02\x00\x01'

If a normal function is used as size:

>>> import pak
>>> class MyPacket(pak.Packet):
...     half_length: pak.Int8
...     array:       pak.Int8[lambda p: 2 * p.half_length]
...
>>> packet = MyPacket.unpack(b'\x01\x00\x01')
>>> packet
MyPacket(half_length=1, array=[0, 1])
>>> packet.pack()
b'\x01\x00\x01'
class SizePrefixed(elem_type, size)

Bases: Array

An Array which is prefixed by the number of its elements.

Parameters:

  • elem_type (typelike) – The Type contained in the Array.

  • size (typelike) – The Type which corresponds to the prefixed size value.

Examples

>>> import pak
>>> pak.Int8[pak.Int8].unpack(b"\x02\x00\x01")
[0, 1]
>>> pak.Int8[pak.Int8].pack([0, 1])
b'\x02\x00\x01'
class Unbounded(elem_type)

Bases: Array

An unbounded Array.

An unbounded Array will read its elements until the end of the buffer.

Unless customized, an unbounded Array will read its elements until an Exception is thrown while unpacking them, at which point the Exception will be suppressed and the Array will contain all the elements that were able to be successfully read.

If a Type.UnsuppressedError is thrown while unpacking an element, then that Exception will not be suppressed.

Parameters:

elem_type (typelike) – The Type contained in the Array.

Examples

>>> import pak
>>> pak.Int8[None].unpack(b"\x00\x01\x02")
[0, 1, 2]
>>> pak.Int8[None].pack([0, 1, 2])
b'\x00\x01\x02'
array_size = None
elem_type = None