Skip to content

Exceptions

Error handling for device communication issues. KazunokoError is the base exception, with specific subclasses for different error types: connection failures, command issues, response problems, and timeouts.

Catch KazunokoError to handle all errors uniformly. For advanced use, catch specific exceptions to implement different recovery strategies.

kazunoko.exceptions

Custom exceptions for kazunoko device communication

CommandError

Bases: KazunokoError

Command execution error

Raised when sending a command to the device fails.

Example 
from kazunoko import MockDevice, CommandError

device = None
try:
    device = MockDevice()
    device.send_command("INVALID_COMMAND")
except CommandError as e:
    print(f"Command failed: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
class CommandError(KazunokoError):
    """
    Command execution error

    Raised when sending a command to the device fails.

    Example:
        ```python
        from kazunoko import MockDevice, CommandError

        device = None
        try:
            device = MockDevice()
            device.send_command("INVALID_COMMAND")
        except CommandError as e:
            print(f"Command failed: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass

CommandTimeout

Bases: CommandError

Command reception timeout

Raised when command acknowledgment is not received within timeout period.

Example 
from kazunoko import connect, CommandTimeout

device = None
try:
    device = connect()
    device.send_command("STATUS")
except CommandTimeout as e:
    print(f"Command timed out: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
class CommandTimeout(CommandError):
    """
    Command reception timeout

    Raised when command acknowledgment is not received within timeout period.

    Example:
        ```python
        from kazunoko import connect, CommandTimeout

        device = None
        try:
            device = connect()
            device.send_command("STATUS")
        except CommandTimeout as e:
            print(f"Command timed out: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass

DeviceError

Bases: KazunokoError

Device initialization or connection error

Raised when device connection fails or device is not open.

Example 
from kazunoko import connect, DeviceError

device = None
try:
    device = connect("/dev/ttyUSB0")
except DeviceError as e:
    print(f"Failed to connect to device: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
class DeviceError(KazunokoError):
    """
    Device initialization or connection error

    Raised when device connection fails or device is not open.

    Example:
        ```python
        from kazunoko import connect, DeviceError

        device = None
        try:
            device = connect("/dev/ttyUSB0")
        except DeviceError as e:
            print(f"Failed to connect to device: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass

EventTimeout

Bases: ResponseError

Event reception timeout during streaming

Raised when no event is received from device within the event_timeout period. Unlike ResponseTimeout which indicates total communication failure, EventTimeout indicates that no detection event arrived within the configured timeout window. This is expected behavior when event_timeout is exceeded - streaming should continue to the next event.

Example 
from kazunoko import connect, Reader, EventTimeout

device = None
try:
    device = connect()
    reader = Reader(device, event_timeout=5.0)
    event = reader.read_event()
except EventTimeout as e:
    print(f"No event detected within timeout: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
class EventTimeout(ResponseError):
    """
    Event reception timeout during streaming

    Raised when no event is received from device within the event_timeout period.
    Unlike ResponseTimeout which indicates total communication failure, EventTimeout
    indicates that no detection event arrived within the configured timeout window.
    This is expected behavior when event_timeout is exceeded - streaming should
    continue to the next event.

    Example:
        ```python
        from kazunoko import connect, Reader, EventTimeout

        device = None
        try:
            device = connect()
            reader = Reader(device, event_timeout=5.0)
            event = reader.read_event()
        except EventTimeout as e:
            print(f"No event detected within timeout: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass

KazunokoError

Bases: Exception

Base exception for all kazunoko errors

All kazunoko-specific exceptions inherit from this class for easy catching.

Example 
from kazunoko import connect, KazunokoError, DeviceError, ResponseTimeout

# Catch all kazunoko errors
try:
    device = connect()
    response = device.query("STATUS")
except KazunokoError as e:
    print(f"Device communication failed: {e}")
finally:
    device.close()

# Catch specific errors
device = None
try:
    device = connect()
except DeviceError as e:
    print(f"Connection failed: {e}")
except ResponseTimeout as e:
    print(f"Device not responding: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
class KazunokoError(Exception):
    """
    Base exception for all kazunoko errors

    All kazunoko-specific exceptions inherit from this class for easy catching.

    Example:
        ```python
        from kazunoko import connect, KazunokoError, DeviceError, ResponseTimeout

        # Catch all kazunoko errors
        try:
            device = connect()
            response = device.query("STATUS")
        except KazunokoError as e:
            print(f"Device communication failed: {e}")
        finally:
            device.close()

        # Catch specific errors
        device = None
        try:
            device = connect()
        except DeviceError as e:
            print(f"Connection failed: {e}")
        except ResponseTimeout as e:
            print(f"Device not responding: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass

ProtocolError

Bases: KazunokoError

Protocol parsing or validation error

Raised when JSONL parsing fails or response validation against model fails.

Example 
from kazunoko.parser import parse_jsonl, ProtocolError

try:
    response = parse_jsonl('{"invalid": json}')
except ProtocolError as e:
    print(f"Parse error: {e}")
finally:
    # No device to close for parsing-only operations
    pass
Source code in src/kazunoko/exceptions.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
class ProtocolError(KazunokoError):
    """
    Protocol parsing or validation error

    Raised when JSONL parsing fails or response validation against model fails.

    Example:
        ```python
        from kazunoko.parser import parse_jsonl, ProtocolError

        try:
            response = parse_jsonl('{"invalid": json}')
        except ProtocolError as e:
            print(f"Parse error: {e}")
        finally:
            # No device to close for parsing-only operations
            pass
        ```
    """

    pass

ResponseError

Bases: KazunokoError

Invalid or malformed response from device

Raised when device response is invalid, missing required fields, or has unexpected type.

Example 
from kazunoko import connect, ResponseError

device = None
try:
    device = connect()
    response = device.query("STATUS")
except ResponseError as e:
    print(f"Invalid response: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
class ResponseError(KazunokoError):
    """
    Invalid or malformed response from device

    Raised when device response is invalid, missing required fields, or has unexpected type.

    Example:
        ```python
        from kazunoko import connect, ResponseError

        device = None
        try:
            device = connect()
            response = device.query("STATUS")
        except ResponseError as e:
            print(f"Invalid response: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass

ResponseTimeout

Bases: ResponseError

Response reception timeout

Raised when no response is received from device within timeout period.

Example 
from kazunoko import connect, ResponseTimeout

device = None
try:
    device = connect()
    response = device.query("STATUS")
except ResponseTimeout as e:
    print(f"Device not responding: {e}")
finally:
    if device:
        device.close()
Source code in src/kazunoko/exceptions.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
class ResponseTimeout(ResponseError):
    """
    Response reception timeout

    Raised when no response is received from device within timeout period.

    Example:
        ```python
        from kazunoko import connect, ResponseTimeout

        device = None
        try:
            device = connect()
            response = device.query("STATUS")
        except ResponseTimeout as e:
            print(f"Device not responding: {e}")
        finally:
            if device:
                device.close()
        ```
    """

    pass