test_dict.py

Overview

`test_dict.py` is a test suite designed to verify the serialization and deserialization correctness of Python dictionaries using the `orjson` library. It uses the `pytest` framework to run a series of unit tests that ensure `orjson.dumps()` and `orjson.loads()` correctly handle various dictionary scenarios, including:

• Basic dictionary encoding/decoding.

• Handling of duplicate keys during JSON loading.

• Empty and large dictionaries.

• Dictionaries with Unicode keys.

• Invalid key types leading to errors.

• Mutation operations on dictionaries and their effect on serialization.

• Edge cases involving dictionary sizes and repeated operations.

• Serialization of Python object's __dict__.

This suite ensures `orjson` maintains consistency, correctness, and robustness when working with dictionaries, which are fundamental data structures in JSON serialization.

Classes and Methods

Class: TestDict

A container for all dictionary-related test cases focused on the `orjson` library. Each method tests a specific aspect or edge case of dictionary serialization/deserialization.

Methods

test_dict(self)

• Purpose: Test simple dictionary serialization and deserialization.

• Parameters: self - instance of TestDict.

• Returns: None; assertions validate correctness.

• Details:

  • Serializes a dictionary {"key": "value"} to JSON bytes.

  • Deserializes JSON string back to dictionary.

• Usage:

  test = TestDict()
  test.test_dict()
  

• Verification: Serialized bytes match expected JSON, and deserialized object matches original.

test_dict_duplicate_loads(self)

• Purpose: Test behavior when JSON string has duplicate keys.

• Details:

  • Loads JSON string with duplicate key "1" but different boolean values.

  • Expected behavior: last key-value pair overwrites previous, resulting in {"1": False}.

• Usage:

  test = TestDict()
  test.test_dict_duplicate_loads()
  

• Note: Validates orjson.loads handles duplicate keys by overwriting previous keys.

test_dict_empty(self)

• Purpose: Test serialization/deserialization of deeply nested empty dictionaries in a large list.

• Details:

  • Creates a large nested structure with empty dicts.

  • Ensures serialization round-trip preserves structure without error.

test_dict_large_dict(self)

• Purpose: Test dictionary with more than 512 keys.

• Details:

  • Creates a dict with 513 keys, each mapped to a nested list/dict structure.

  • Verifies serialization and deserialization maintain data integrity.

test_dict_large_4096(self)

• Purpose: Test dictionary with more than 4096 keys.

• Details:

  • Creates a dictionary with 4097 key-value pairs.

  • Ensures orjson can handle large dictionaries efficiently.

test_dict_large_65536(self)

• Purpose: Test dictionary with more than 65536 keys.

• Details:

  • Creates a dictionary with 65537 keys.

  • Validates serialization and deserialization correctness at very large scale.

test_dict_large_keys(self)

• Purpose: Test dictionary with very large keys that exceed caching limits.

• Details:

  • Uses a very long string as a key.

  • Ensures orjson correctly serializes/deserializes without relying on key caching.

test_dict_unicode(self)

• Purpose: Test dictionary with Unicode keys.

• Details:

  • Uses an emoji ("🐈") as a key.

  • Validates correct UTF-8 encoding in JSON and successful round-trip.

test_dict_invalid_key_dumps(self)

• Purpose: Test error handling when dictionary keys are invalid types for JSON serialization.

• Details:

  • Keys tested: integer (1), bytes (b"key").

  • Expected: orjson.JSONEncodeError is raised.

test_dict_invalid_key_loads(self)

• Purpose: Test error handling when JSON strings have invalid keys.

• Details:

  • Invalid JSON strings with non-string keys or malformed keys.

  • Expected: orjson.JSONDecodeError is raised.

test_dict_similar_keys(self)

• Purpose: Regression test for loading JSON with similar keys.

• Details:

  • Ensures orjson.loads maintains all distinct keys correctly.

  • References a known regression fixed in orjson v3.4.2.

test_dict_pop_replace_first(self)

• Purpose: Test behavior of popping and re-adding the first key in a dictionary.

• Details:

  • Modifies dict by removing and then re-inserting a key.

  • Checks serialization output correctness.

test_dict_pop_replace_last(self)

• Purpose: Similar to above, but for the last key in a dictionary.

• Details: Verifies consistent serialization after modification.

test_dict_pop(self)

• Purpose: Test pop and replace key in a dictionary with no other keys.

• Details: Ensures empty dictionary and re-added key serialize correctly.

test_in_place(self)

• Purpose: Test in-place mutation of dictionary values.

• Details: Verifies serialization reflects updated values.

test_dict_0xff(self)

• Purpose: Test dictionary size less than or equal to 255 (0xff).

• Details: Tests pop and re-add of keys and verifies correctness.

test_dict_0xff_repeated(self)

• Purpose: Repeated test for dictionary size ≤ 255.

• Details: Runs the previous test 100 times to check consistency.

test_dict_0xffff(self)

• Purpose: Test dictionary size less than or equal to 65,535 (0xffff).

• Details: Similar pop and re-add test with larger dict.

test_dict_0xffff_repeated(self)

• Purpose: Repeated test for dictionary size ≤ 65,535.

• Details: Runs the above test 100 times.

test_dict_dict(self)

• Purpose: Test serialization of a Python object's __dict__ attribute.

• Details:

  • Defines class C with attributes.

  • Serializes instance's __dict__ to JSON.

  • Ensures output matches expected key-value pairs.

Implementation Details and Algorithms

• The tests use orjson.dumps() to convert Python dictionaries into JSON byte strings and orjson.loads() to parse JSON strings/bytes back into Python dictionaries.

• Several tests focus on edge cases of dictionary size to verify internal optimizations or limitations within orjson regarding key caching, hash collisions, or buffer sizes.

• The duplicate key test confirms that orjson.loads() behavior aligns with standard JSON parsers by overwriting earlier keys with later ones.

• The invalid key tests confirm strict enforcement of JSON standards (keys must be strings).

• Repeated tests check for consistency and detect any stateful bugs or memory issues during repeated serialization/deserialization cycles.

• The mutation tests check orjson's handling of dictionaries that are modified after creation, ensuring that serialization always reflects the current state.

Interaction with Other Parts of the System

• orjson Library: Core dependency being tested. This file verifies the correctness of orjson's dictionary serialization/deserialization.

• pytest Framework: Used for running tests and asserting conditions.

• This file is likely part of a larger test suite validating orjson's JSON encoding and decoding capabilities for various Python data types.

• No external system dependencies; purely focused on the correctness of JSON operations with dictionaries.

Usage Example

Run all tests with pytest:

pytest test_dict.py

This will execute all methods of the `TestDict` class, verifying that `orjson` handles dictionary serialization/deserialization correctly and raising errors where appropriate.

Mermaid Diagram: Class Structure

classDiagram
    class TestDict {
        +test_dict()
        +test_dict_duplicate_loads()
        +test_dict_empty()
        +test_dict_large_dict()
        +test_dict_large_4096()
        +test_dict_large_65536()
        +test_dict_large_keys()
        +test_dict_unicode()
        +test_dict_invalid_key_dumps()
        +test_dict_invalid_key_loads()
        +test_dict_similar_keys()
        +test_dict_pop_replace_first()
        +test_dict_pop_replace_last()
        +test_dict_pop()
        +test_in_place()
        +test_dict_0xff()
        +test_dict_0xff_repeated()
        +test_dict_0xffff()
        +test_dict_0xffff_repeated()
        +test_dict_dict()
    }

Summary

`test_dict.py` is a thorough and systematic test suite validating `orjson`'s handling of Python dictionaries across a broad spectrum of scenarios, sizes, and edge cases. It ensures that `orjson` complies with JSON standards, handles Unicode correctly, manages large datasets efficiently, and properly raises errors for invalid inputs. This file is critical for maintaining the quality and reliability of `orjson`'s dictionary serialization and deserialization features.