PyByteBuffer

1.0.5 · maintenance · verified Sun Apr 12

PyByteBuffer is a Python library for manipulating byte buffers, drawing inspiration from Java's `java.nio.ByteBuffer`. It provides methods for writing and reading various data types (integers, strings, arrays, bytes) into a buffer with control over aspects like endianness and position. The current stable version is 1.0.5, released in late 2020, and it appears to be in a maintenance status, stable for its intended functionality.

Warnings

gotcha Operations like `get()` (for reading a single byte/value) do not advance the buffer's internal `position`, mimicking Java's `ByteBuffer`. This differs from typical Python stream-like objects where `read()` usually advances the cursor. Use `read()` methods or explicitly manage `position()` for sequential reading.
Fix: Explicitly call `buffer.position(new_pos)` or use `buffer.read(...)` methods which advance the position automatically.
gotcha When writing or reading integers, endianness matters. If not specified during a `write` operation, the system's default endianness is used. Reading with an incorrect endianness can lead to corrupted data. Be explicit, especially when dealing with network protocols or cross-platform data.
Fix: Always explicitly specify endianness (e.g., `bb.write(value, 'int', 4, endian='big')`) if data exchange requires it, or if consistency across different systems is important.
gotcha The library documentation notes that performance considerations 'are all around the conversion between int->bytes bytes<-int'. Frequent or unoptimized conversions, especially in performance-critical loops, could lead to bottlenecks.
Fix: Profile code that heavily uses `int` to `bytes` or `bytes` to `int` conversions. Consider batching operations or alternative approaches if performance becomes an issue.

Install

pip install PyByteBuffer Install latest version

Imports

ByteBuffer
```
from PyByteBuffer import ByteBuffer
```

Quickstart

This quickstart demonstrates how to create a ByteBuffer, write different data types into it, reset its position, and then read the data back. It also highlights the behavior of `get()` versus `read()` methods concerning position advancement.

from PyByteBuffer import ByteBuffer

# Create a ByteBuffer with an initial capacity
bb = ByteBuffer(1024)

# Write various data types
bb.write(12345, 'int', 4)  # Write an int (4 bytes)
bb.write('Hello PyByteBuffer', 'str') # Write a string
bb.write(b'\x01\x02\x03', 'bytes') # Write raw bytes

# Reset position to read from the beginning
bb.position(0)

# Read the data back
int_val = bb.read('int', 4)
str_val = bb.read('str', 18) # Read 18 characters for 'Hello PyByteBuffer'
bytes_val = bb.read('bytes', 3)

print(f'Read int: {int_val}')
print(f'Read string: {str_val}')
print(f'Read bytes: {bytes_val}')

# Example of getting without advancing position
bb.position(0)
first_byte = bb.get()
print(f'First byte (get, position unchanged): {first_byte}')
print(f'Position after get(): {bb.position()}')
first_byte_again = bb.get()
print(f'First byte again (get, position unchanged): {first_byte_again}')

view raw JSON →