Python bytearray(): Mutable Byte Buffers & In-Place Binary Operations

1. Syntax & Formal Parameter Specifications 🔝

The bytearray() constructor supports four distinct initialization patterns:

# Formal syntax of built-in bytearray()
# Form 1: Zero-argument constructor
empty_ba = bytearray()

# Form 2: Integer size (pre-allocates zero-filled buffer)
zero_ba = bytearray(size)

# Form 3: String with required encoding and error policies
encoded_ba = bytearray(string, encoding='utf-8', errors='strict')

# Form 4: Iterable of integers (0 <= x <= 255)
seq_ba = bytearray(iterable_of_ints)

2. Basic Usage: Integers, Strings & Integer Lists 🔝

Passing an integer preallocates a buffer of null bytes. When passing strings, specify the encoding:

# 1. Zero-filled mutable byte allocation
ba_zeros = bytearray(5)
print("bytearray(5):       ", ba_zeros)       # bytearray(b'\x00\x00\x00\x00\x00')
print("Length:             ", len(ba_zeros))  # 5

# 2. String encoding (encoding is mandatory)
text = "plus2net.com"
ba_str = bytearray(text, encoding='utf-8')
print("bytearray(str):     ", ba_str)         # bytearray(b'plus2net.com')
print("Type:               ", type(ba_str))   # 

# 3. Iterable of integers (0-255)
ba_list = bytearray([1, 2, 3, 4])
print("bytearray([1,2,3,4]):", ba_list)       # bytearray(b'\x01\x02\x03\x04')

Output:

bytearray(5):        bytearray(b'\x00\x00\x00\x00\x00')
Length:              5
bytearray(str):      bytearray(b'plus2net.com')
Type:                
bytearray([1,2,3,4]): bytearray(b'\x01\x02\x03\x04')

3. In-Place Mutation: Indexing, Slicing & Appending 🔝

Unlike bytes, elements of a bytearray can be mutated in-place without memory reallocation:

# In-place mutation: item assignment, append, and slice replacement
buffer = bytearray(b"Hello!")
print("Initial buffer:  ", buffer)

# 1. Modifying a byte in-place via indexing
buffer[0] = ord('J')  # Assign ASCII 74
print("After buffer[0]: ", buffer)  # bytearray(b'Jello!')

# 2. Appending and extending
buffer.append(ord('?'))
print("After append:    ", buffer)  # bytearray(b'Jello!?')

# 3. Slice replacement without recreating the object
buffer[0:5] = b"Python"
print("After slice edit:", buffer)  # bytearray(b'Python!?')

Output:

Initial buffer:   bytearray(b'Hello!')
After buffer[0]:  bytearray(b'Jello!')
After append:     bytearray(b'Jello!?')
After slice edit: bytearray(b'Python!?')

4. String Encodings & Error Handling Schemes 🔝

Configure error handlers when decoding characters outside the specified character set:

# Handling non-ASCII characters with error policies
raw_text = "plus2net.cÖm"

# strict: default mode, raises UnicodeEncodeError
try:
    bytearray(raw_text, encoding='ascii', errors='strict')
except UnicodeEncodeError as err:
    print("strict error: ", err)

# ignore: skips non-ASCII characters
ba_ignore = bytearray(raw_text, encoding='ascii', errors='ignore')
print("errors='ignore': ", ba_ignore)   # bytearray(b'plus2net.cm')

# replace: inserts ASCII question mark '?'
ba_replace = bytearray(raw_text, encoding='ascii', errors='replace')
print("errors='replace':", ba_replace)  # bytearray(b'plus2net.c?m')

Output:

strict error:  'ascii' codec can't encode character '\xd6' in position 10: ordinal not in range(128)
errors='ignore':  bytearray(b'plus2net.cm')
errors='replace': bytearray(b'plus2net.c?m')

5. Hexadecimal Conversions: bytearray.fromhex() & .hex() 🔝

Translate between hex strings and mutable byte buffers:

# Hexadecimal conversion: fromhex() and .hex()
# Parsing hex digit pairs into mutable buffer
ba_hex = bytearray.fromhex('F1 F1')
print("bytearray.fromhex('F1 F1'):", ba_hex)  # bytearray(b'\xf1\xf1')

# Modifying hex bytes in-place
ba_hex[0] = 0xAA
print("After modification:        ", ba_hex)  # bytearray(b'\xaa\xf1')
print("Exported hex string:       ", ba_hex.hex())

Output:

bytearray.fromhex('F1 F1'): bytearray(b'\xf1\xf1')
After modification:         bytearray(b'\xaa\xf1')
Exported hex string:        aaf1

6. bytearray vs. bytes: Performance & Mutability 🔝

Compare memory mutability and zero-copy slicing:

# bytearray (mutable) vs bytes (immutable)
b_immutable = b"immutable"
ba_mutable = bytearray(b"mutable")

# memoryview zero-copy slicing
mv = memoryview(ba_mutable)
mv[0:3] = b"MUT"
print("Modified via memoryview:", ba_mutable)  # bytearray(b'MUTable')

# Attempting mutation on bytes raises TypeError
try:
    b_immutable[0] = ord('I')
except TypeError as err:
    print("bytes error:            ", err)

Output:

Modified via memoryview: bytearray(b'MUTable')
bytes error:             'bytes' object does not support item assignment

7. Production Recipes & Practical Applications 🔝

Below is a real-world algorithm demonstrating bytearray in binary XOR packet encryption:

# Recipe A: Binary socket packet masking (XOR cipher)
def xor_mask_buffer(payload: bytearray, key: int) -> bytearray:
    for i in range(len(payload)):
        payload[i] ^= key
    return payload

message = bytearray(b"ConfidentialData")
key_byte = 0x5A

print("Original: ", message)
masked = xor_mask_buffer(message, key_byte)
print("Masked:   ", masked)
unmasked = xor_mask_buffer(masked, key_byte)
print("Unmasked: ", unmasked)

Output:

Original:  bytearray(b'ConfidentialData')
Masked:    bytearray(b'yUTLO^UT_OEXnK^K')
Unmasked:  bytearray(b'ConfidentialData')

8. Common Pitfalls & Developer Traps 🔝

# Pitfall 1: Assigning string or float to byte index raises TypeError
ba = bytearray(b"abc")
try:
    ba[0] = "A"  # Must assign int 0-255, not str!
except TypeError as err:
    print("TypeError caught:", err)

# Pitfall 2: Integer outside 0-255 raises ValueError
try:
    ba[0] = 300
except ValueError as err:
    print("ValueError caught:", err)

Output:

TypeError caught: an integer is required
ValueError caught: byte must be in range(0, 256)

9. Interactive Notebook & Practice Exercises 🔝

Practice mutable byte buffer modifications, in-place XOR masking, and hex conversions in our companion Jupyter Notebook:

Self-Verifying Assertion Suite

Run these unit checks directly in Python or your local environment to verify bytearray() mechanics:

def test_bytearray_mechanics():
    # 1. Basic constructor
    assert bytearray() == bytearray(b"")
    assert bytearray(3) == bytearray(b"\x00\x00\x00")
    assert bytearray([65, 66]) == bytearray(b"AB")
    
    # 2. In-place mutation
    ba = bytearray(b"ABC")
    ba[0] = 90  # 'Z'
    assert ba == bytearray(b"ZBC")
    
    # 3. Hex parsing
    assert bytearray.fromhex("f1f1") == bytearray(b"\xf1\xf1")
    
    print("All bytearray() unit assertions passed! 100% verified.")

test_bytearray_mechanics()

Output:

All bytearray() unit assertions passed! 100% verified.

10. Related Built-in Functions & Binary Tools 🔝

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: