datastream

Because construct was too complicated.

This is a simple and easy to use library that provides two classes. One class serializes data, and the other one deserializes. These classes behave like streams in which they have read, write, close among other stream related functions. The goal of this library is to be as simple as possible while providing flexibility.

To install the library, use the following:

python -m pip install --user -U pydatastreams

To import the library, use the following:

from datastream import SerializingStream, DeserializingStream, TwoWayStream, ByteOrder

Retrieving serialized data from a SerializingStream:

with SerializingStream() as stream:
    stream.write_int32(42)

    serialized = stream.bytes()

    # this also works
    serialized = bytes(stream)

Note: This library also contains a stream for both serializing and deserializing data. This stream is called TwoWayStream.

The stream classes support serializing/deserializing the standard data types:

Data Type	Description	Serializer	Deserializer
int8_t	Signed 8-bit number	write_int8(value: int)	read_int8() -> int
uint8_t	Unsigned 8-bit number	write_uint8(value: int)	read_uint8() -> int
int16_t	Signed 16-bit number	write_int16(value: int)	read_int16() -> int
uint16_t	Unsigned 16-bit number	write_uint16(value: int)	read_uint16() -> int
int32_t	Signed 32-bit number	write_int32(value: int)	read_int32() -> int
uint32_t	Unsigned 32-bit number	write_uint32(value: int)	read_uint32() -> int
int64_t	Signed 64-bit number	write_int64(value: int)	read_int64() -> int
uint64_t	Unsigned 64-bit number	write_uint64(value: int)	read_uint64() -> int
float	32-bit floating point number	write_float(value: float)	read_float() -> float
double	64-bit floating point number	write_double(value: float)	read_double() -> float

Additionally, the stream classes also provide the following non-standard data types:

Data Type	Description	Serializer	Deserializer
bool	True/False value encoded as a single byte	write_bool(value: bool)	read_bool() -> bool
uleb128	Variable sized unsigned 128-bit number	write_uleb128(value: int)	read_uleb128() -> int
		write_uleb128_safe(value: int, max_bytes: int = 16)	read_uleb128_safe(max_bytes: int = 16) -> int
sleb128	Variable sized signed 128-bit number	write_sleb128(value: int)	read_sleb128() -> int
		write_sleb128_safe(value: int, max_bytes: int = 16)	read_sleb128_safe(max_bytes: int = 16) -> int

Finally, the stream classes also provide the following utility functions:

Function	Description
set(buffer: bytes | typing.IO[bytes])	Sets the backing stream to the given buffer. DeserializingStream only.
read_until(terminator: bytes) -> bytes	Reads len(terminator) bytes from the stream until terminator is found. DeserializingStream only.
read(size: int) -> bytes	Reads up to size bytes from the backing stream.
write(data: bytes)	Writes the given data to the backing stream.
size() -> int	Returns the size of the backing stream.
seek(offset: int, whence: int = io.SEEK_SET)	Change the stream position to the given offset.
tell() -> int	Returns the current position of the stream.
close()	Closes the backing stream.
remaining() -> int	Returns the number of bytes remaining in the backing stream.
clone() -> typing.Self	Returns a new instance of the same class with the same byte order and contents.
substream(start: int, end: int) -> typing.Self	Returns a new instance of the same class, representing a substream of the current stream.
peek(size: int) -> bytes	Returns the next size bytes from the stream without advancing the position.
seekpeek(offset: int, size: int) -> bytes	Seeks to the specified offset in the data stream, reads the specified number of bytes, and then restores the original position.
search(data: bytes) -> int	Searches for the given data in the backing stream.
rsearch(data: bytes) -> int	Searches for the given data in the reverse order within the backing stream.
clear()	Clears the backing stream by truncating it to 0 bytes and resetting the stream position to the beginning.