Skip to content

Bytes assertions

Assertions for bytes and bytearray values.

Assertions for bytes and bytearray values.

is_valid_utf8 

is_valid_utf8() -> Self

Assert that val is valid UTF-8.

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val is not valid UTF-8
Source code in assertpy2/bytes_mixin.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
def is_valid_utf8(self) -> Self:
    """Assert that val is valid UTF-8.

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val is not valid UTF-8
    """
    self._check_bytes()
    try:
        self.val.decode("utf-8")
    except UnicodeDecodeError:
        return self.error("Expected valid UTF-8, but decoding failed.")
    return self

is_valid_encoding 

is_valid_encoding(encoding: str) -> Self

Assert that val is valid in the given encoding.

Parameters:

Name Type Description Default
encoding str

the encoding to validate against (e.g. "ascii", "utf-16").

 required

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val cannot be decoded with the given encoding
Source code in assertpy2/bytes_mixin.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def is_valid_encoding(self, encoding: str) -> Self:
    """Assert that val is valid in the given encoding.

    Args:
        encoding: the encoding to validate against (e.g. ``"ascii"``, ``"utf-16"``).

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val cannot be decoded with the given encoding
    """
    self._check_bytes()
    try:
        self.val.decode(encoding)
    except (UnicodeDecodeError, LookupError):
        return self.error(f"Expected valid {encoding} encoding, but decoding failed.")
    return self

starts_with_bytes 

starts_with_bytes(prefix: bytes) -> Self

Assert that val starts with the given byte prefix.

Parameters:

Name Type Description Default
prefix bytes

the expected byte prefix.

 required

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not start with the prefix
Source code in assertpy2/bytes_mixin.py 
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def starts_with_bytes(self, prefix: bytes) -> Self:
    """Assert that val starts with the given byte prefix.

    Args:
        prefix: the expected byte prefix.

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does not start with the prefix
    """
    self._check_bytes()
    if not self.val.startswith(prefix):
        return self.error(f"Expected to start with <{prefix!r}>, but did not.")
    return self

contains_bytes 

contains_bytes(sub: bytes) -> Self

Assert that val contains the given byte subsequence.

Parameters:

Name Type Description Default
sub bytes

the byte subsequence to find.

 required

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not contain the subsequence
Source code in assertpy2/bytes_mixin.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def contains_bytes(self, sub: bytes) -> Self:
    """Assert that val contains the given byte subsequence.

    Args:
        sub: the byte subsequence to find.

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does not contain the subsequence
    """
    self._check_bytes()
    if sub not in self.val:
        return self.error(f"Expected to contain <{sub!r}>, but did not.")
    return self

has_byte_at 

has_byte_at(index: int, expected: int) -> Self

Assert that the byte at the given index equals the expected value.

Parameters:

Name Type Description Default
index int

zero-based byte index.

 required
expected int

expected byte value (0-255).

 required

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if the byte at index does not match
Source code in assertpy2/bytes_mixin.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def has_byte_at(self, index: int, expected: int) -> Self:
    """Assert that the byte at the given index equals the expected value.

    Args:
        index: zero-based byte index.
        expected: expected byte value (0-255).

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if the byte at index does not match
    """
    self._check_bytes()
    if index < 0 or index >= len(self.val):
        raise IndexError(f"Expected index {index} to be in range [0, {len(self.val)}), but was out of range.")
    actual = self.val[index]
    if actual != expected:
        return self.error(f"Expected byte at index {index} to be <0x{expected:02x}>, but was <0x{actual:02x}>.")
    return self

is_hex_equal_to 

is_hex_equal_to(expected_hex: str) -> Self

Assert that val equals the given hex string.

Parameters:

Name Type Description Default
expected_hex str

hex string without prefix (e.g. "abcdef").

 required

Returns:

Name Type Description
AssertionBuilder Self

returns this instance to chain to the next assertion

Raises:

Type Description
AssertionError

if val does not match the hex string
Source code in assertpy2/bytes_mixin.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
def is_hex_equal_to(self, expected_hex: str) -> Self:
    """Assert that val equals the given hex string.

    Args:
        expected_hex: hex string without prefix (e.g. ``"abcdef"``).

    Returns:
        AssertionBuilder: returns this instance to chain to the next assertion

    Raises:
        AssertionError: if val does not match the hex string
    """
    self._check_bytes()
    expected = bytes.fromhex(expected_hex)
    if self.val != expected:
        return self.error(f"Expected hex <{expected_hex}>, but was <{self.val.hex()}>.")
    return self

decoded_as 

decoded_as(encoding: str = 'utf-8') -> Self

Decode val and return a new builder with the decoded string.

Parameters:

Name Type Description Default
encoding str

the encoding to use (default "utf-8").

 'utf-8'

Returns:

Name Type Description
AssertionBuilder Self

a new instance with the decoded string as val

Raises:

Type Description
UnicodeDecodeError

if val cannot be decoded
Source code in assertpy2/bytes_mixin.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def decoded_as(self, encoding: str = "utf-8") -> Self:
    """Decode val and return a new builder with the decoded string.

    Args:
        encoding: the encoding to use (default ``"utf-8"``).

    Returns:
        AssertionBuilder: a new instance with the decoded string as val

    Raises:
        UnicodeDecodeError: if val cannot be decoded
    """
    self._check_bytes()
    decoded = self.val.decode(encoding)
    return self.builder(decoded, self.description, self.kind)