JSON Decode Error

Purpose

The **JSON Decode Error** subtopic focuses on the specialized exception type used to signal errors encountered during JSON deserialization. While the parent topic broadly covers custom error types for encoding and decoding, this subtopic addresses the specific need to wrap and extend Python's standard `json.JSONDecodeError` to provide consistent, informative, and project-specific parse error reporting.

This exception serves as the central mechanism for communicating parse failures back to the Python API user. It captures detailed error context such as the position in the input where parsing failed, enabling better debugging and error handling in client code that consumes the JSON deserialization functionality.

Functionality

The `JSONDecodeError` class inherits directly from Python's built-in `json.JSONDecodeError`. This subclassing approach allows it to retain all standard error attributes and behaviors (like `msg`, `doc`, and `pos`) while being distinctively identifiable as originating from this high-performance JSON library.

Key aspects include:

• Error Wrapping: The Rust core or the embedded yyjson C parser detects errors during parsing. When an error occurs, it is translated into this Python exception type before being raised to the caller.

• Preservation of Error Context: The exception carries detailed information about what went wrong and where, consistent with Python’s standard error interface.

• Interoperability: Because it subclasses json.JSONDecodeError, existing Python code expecting this exception type for JSON read errors can handle this library’s exceptions transparently.

A minimal usage example from the type stub:

class JSONDecodeError(json.JSONDecodeError): ...

This line indicates `JSONDecodeError` acts as a thin wrapper to the native exception, without altering its interface or introducing new methods.

Relationship

`JSONDecodeError` integrates tightly with the deserialization workflow of the parent topic—custom error types for serialization and deserialization:

• In Deserialization Core: The Rust parser detects malformed JSON or invalid characters and triggers an error path that results in raising a JSONDecodeError.

• In Python API Layer: When calling orjson.loads, any parse failure raises this exception, allowing Python developers to catch and respond appropriately.

• Complementing Other Errors: While JSONEncodeError handles serialization errors, JSONDecodeError focuses exclusively on decoding failures, maintaining a clear separation of concerns.

• Consistent Error Model: By subclassing the standard Python error, this subtopic ensures compatibility with Python’s JSON ecosystem and existing error handling patterns.

In summary, it acts as a critical bridge between the low-level Rust/C parsing failures and the high-level Python exception handling conventions.

Diagram

The following flowchart illustrates the error handling pathway for JSON decoding errors:

flowchart TD
    Input[JSON Input] --> Parse[Parse JSON (Rust + yyjson)]
    Parse -->|Success| ReturnObj[Return Python Object]
    Parse -->|Error Detected| ConvertErr[Convert to JSONDecodeError]
    ConvertErr --> RaiseErr[Raise JSONDecodeError Exception]
    RaiseErr --> Caller[Python Caller Code]

This diagram highlights how the parsing stage detects errors and converts them into the `JSONDecodeError` exception that propagates to the user-facing Python layer.

This focused exception mechanism ensures robust, informative error reporting in the JSON deserialization process, fitting seamlessly into the overall error handling strategy of the library.