PyStreamHandler 1.0.0

PyStreamHandler is a lightweight Python package designed to facilitate reading and writing binary data from buffers using Python's built-in `struct` module and `bytearray`.

PyStreamHandler

PyStreamHandler is a lightweight Python package designed to facilitate reading and writing binary data from buffers using Python's built-in struct module and bytearray. It provides two main classes:

• ReadStreamHandler: For parsing binary streams with automatic buffer management and error handling.
• WriteStreamHandler: For constructing binary streams with value range validation and ease of use.

Features

• Binary Parsing: Read signed and unsigned values (byte, short, int, long) with automatic buffer overflow checks.
• Data Construction: Write binary data to a mutable buffer using simple methods that ensure correct value ranges.
• Pythonic Design: Uses Python's native bytearray for storage and the struct module for packing/unpacking binary data.

Installation

You can install PyStreamHandler via pip (if it's published):

pip install pystreamhandler

Alternatively, to install locally from your repository, clone the repository and run:

git clone https://github.com/hansenchristoffer/pystreamhandler.git
cd pystreamhandler
pip install .

Usage

Writing Data

Here's an example that demonstrates how to write various types of data to a binary buffer:

from pystreamhandler import WriteStreamHandler

# Initialize the write stream handler
writer = WriteStreamHandler()

# Write various types of data
writer.write_byte(127)                            # Signed byte (-128 to 127)
writer.write_unsigned_byte(255)                   # Unsigned byte (0 to 255)
writer.write_short(32767)                         # Signed short (-32768 to 32767)
writer.write_unsigned_short(65535)                # Unsigned short (0 to 65535)
writer.write_int(2147483647)                      # Signed int (-2147483648 to 2147483647)
writer.write_unsigned_int(4294967295)             # Unsigned int (0 to 4294967295)
writer.write_long(9223372036854775807)            # Signed long (-9223372036854775808 to 9223372036854775807)
writer.write_unsigned_long(18446744073709551615)  # Unsigned long (0 to 18446744073709551615)

# Retrieve the binary buffer
buffer = writer.get_buffer()

Reading Data

And here is how you can read data back from a binary buffer:

from pystreamhandler import ReadStreamHandler

# Assume 'buffer' is a bytearray containing binary data
reader = ReadStreamHandler(buffer)

# Read data in the same order as written
byte_value = reader.read_byte()     # also, pushes cursor forward by 1 byte
short_value = reader.read_short()   # also, pushes cursor forward by 2 bytes
int_value = reader.read_int()       # also, pushes cursor forward by 4 bytes
long_value = reader.read_long()     # also, pushes cursor forward by 8 bytes

print(f"Byte: {byte_value}, Short: {short_value}, Int: {int_value}, Long: {long_value}")

Running Tests

A test suite is included to verify functionality and error handling. To run the tests, use Python’s unittest discovery:

python -m unittest discover tests

Or if you prefer pytest, simply run:

pytest

Contributing

Contributions are welcome! If you have suggestions or improvements:

• Fork the repository.
• Create a new branch for your changes.
• Submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For any questions, suggestions, or feedback, please contact [e-mail]