test_circular.py

Overview

`test_circular.py` is a test module designed to verify the behavior of the `orjson` JSON serialization library when handling circular references within Python data structures. Circular references occur when an object directly or indirectly references itself, which can cause infinite loops or errors during serialization.

This file contains a suite of unit tests that ensure `orjson.dumps()` raises the appropriate `orjson.JSONEncodeError` exception when attempting to serialize circular references. The tests cover various scenarios, including circular dictionaries, lists, nested structures, and the use of different serialization options like `OPT_SORT_KEYS` and `OPT_NON_STR_KEYS`.

Classes and Methods

Class: TestCircular

This class groups together tests related to the serialization of circular references using the `orjson` library.

Method: test_circular_dict(self)

**Purpose:** Tests that serializing a dictionary containing a direct circular reference raises `orjson.JSONEncodeError`.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Creates an empty dictionary obj.

• Assigns obj["obj"] = obj, creating a circular reference.

• Asserts that orjson.dumps(obj) raises orjson.JSONEncodeError.

**Usage Example:**

test = TestCircular()
test.test_circular_dict()

Method: test_circular_dict_sort_keys(self)

**Purpose:** Tests serialization of a circular dictionary with the `OPT_SORT_KEYS` option enabled.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Creates a circular dictionary as above.

• Calls orjson.dumps() with option=orjson.OPT_SORT_KEYS.

• Expects orjson.JSONEncodeError to be raised.

Method: test_circular_dict_non_str_keys(self)

**Purpose:** Tests serialization of a circular dictionary with the `OPT_NON_STR_KEYS` option enabled.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Creates a circular dictionary.

• Calls orjson.dumps() with option=orjson.OPT_NON_STR_KEYS.

• Expects orjson.JSONEncodeError.

Method: test_circular_list(self)

**Purpose:** Tests serialization of a list containing a circular reference to itself.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Creates an empty list obj.

• Appends itself to the list (obj.append(obj)).

• Calls orjson.dumps(obj).

• Expects orjson.JSONEncodeError.

Method: test_circular_nested(self)

**Purpose:** Tests serialization of nested data structures where a dictionary contains a list which in turn references the dictionary, forming a circular reference.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Creates dictionary obj.

• Assigns obj["list"] to a list containing a dictionary that references obj.

• Calls orjson.dumps(obj).

• Expects orjson.JSONEncodeError.

Method: test_circular_nested_sort_keys(self)

**Purpose:** Tests nested circular reference serialization with the `OPT_SORT_KEYS` option.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Same as test_circular_nested, but calls orjson.dumps() with option=orjson.OPT_SORT_KEYS.

• Expects orjson.JSONEncodeError.

Method: test_circular_nested_non_str_keys(self)

**Purpose:** Tests nested circular reference serialization with the `OPT_NON_STR_KEYS` option.

**Parameters:**

• self: instance of TestCircular.

**Behavior:**

• Same as test_circular_nested, but calls orjson.dumps() with option=orjson.OPT_NON_STR_KEYS.

• Expects orjson.JSONEncodeError.

Important Implementation Details

• The tests use the pytest framework, relying on pytest.raises() to assert exceptions.

• The orjson.JSONEncodeError exception is expected to be raised whenever a circular reference is detected by orjson.dumps().

• The # type: ignore comments are used to suppress type checker warnings about circular references or type inconsistencies.

• The options tested (OPT_SORT_KEYS and OPT_NON_STR_KEYS) are flags available in orjson to modify serialization behavior, ensuring that circular reference detection works consistently regardless of option usage.

Interaction with Other Parts of the System

• This test file interacts primarily with the orjson serialization library, specifically its dumps() method and error handling.

• It depends on the pytest testing framework for running tests and asserting expected exceptions.

• The file is likely part of a larger test suite validating the robustness of the orjson library or any system that uses it for JSON serialization.

• No direct interaction with other application modules is present; the file serves as a low-level validation of orjson's circular reference handling capabilities.

Visual Diagram

classDiagram
    class TestCircular {
        +test_circular_dict()
        +test_circular_dict_sort_keys()
        +test_circular_dict_non_str_keys()
        +test_circular_list()
        +test_circular_nested()
        +test_circular_nested_sort_keys()
        +test_circular_nested_non_str_keys()
    }
    TestCircular ..> orjson : uses
    TestCircular ..> pytest : uses

• Explanation: The diagram shows the TestCircular class with its test methods.

• It also illustrates the dependencies on orjson (for serialization and exception) and pytest (for testing utilities).

Summary

`test_circular.py` is a focused test suite ensuring that the `orjson` library correctly detects and rejects circular references in various data structures during JSON serialization, whether or not certain serialization options are enabled. It helps maintain the reliability and correctness of JSON encoding by preventing infinite loops or corrupted outputs caused by circular data.