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 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
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.

The bytes-only spelling of starts_with(), which it delegates to. It carried its own implementation until starts_with learned to handle bytes: before that, a byte string fell through to the element-wise branch and b"foo" compared its first element, the int 102, against b"f". Two implementations of one relation is how they drift, and these two already had: this one accepted an empty prefix, which asserts nothing.

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
TypeError

if val is not bytes/bytearray
ValueError

if the prefix is empty, which no value can fail
AssertionError

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

    The bytes-only spelling of [`starts_with()`][assertpy2.string.StringMixin.starts_with], which it
    delegates to.  It carried its own implementation until `starts_with` learned to handle ``bytes``:
    before that, a byte string fell through to the element-wise branch and ``b"foo"`` compared its
    first element, the int ``102``, against ``b"f"``.  Two implementations of one relation is how they
    drift, and these two already had: this one accepted an empty prefix, which asserts nothing.

    Args:
        prefix: the expected byte prefix.

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

    Raises:
        TypeError: if val is not ``bytes``/``bytearray``
        ValueError: if the prefix is empty, which no value can fail
        AssertionError: if val does not start with the prefix
    """
    self._check_bytes()
    return self.starts_with(prefix)

contains_bytes 

contains_bytes(sub: bytes) -> Self

Assert that val contains the given byte subsequence.

The bytes-only spelling of contains(), which it delegates to. Delegating is what gives the failure the value under test and a structured diff, neither of which its own implementation produced.

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
TypeError

if val is not bytes/bytearray
AssertionError

if val does not contain the subsequence
Source code in assertpy2/bytes_mixin.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def contains_bytes(self, sub: bytes) -> Self:
    """Assert that val contains the given byte subsequence.

    The bytes-only spelling of [`contains()`][assertpy2.contains.ContainsMixin.contains], which it
    delegates to.  Delegating is what gives the failure the value under test and a structured diff,
    neither of which its own implementation produced.

    Args:
        sub: the byte subsequence to find.

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

    Raises:
        TypeError: if val is not ``bytes``/``bytearray``
        AssertionError: if val does not contain the subsequence
    """
    self._check_bytes()
    return self.contains(sub)

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 
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
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 >= sized_len(self.val):
        raise IndexError(f"Expected index {index} to be in range [0, {sized_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 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
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 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
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)