{"id":8247,"library":"json-tricks","title":"json-tricks: Extended JSON Serialization","description":"json-tricks is a Python library that extends the standard `json` module with extra features like support for comments, preserving dictionary order, and native serialization/deserialization of complex types such as NumPy arrays, Pandas DataFrames/Series, datetime objects, and custom Python classes. It is currently at version 3.17.3 and is actively maintained with regular updates.","status":"active","version":"3.17.3","language":"en","source_language":"en","source_url":"https://github.com/mverleg/pyjson_tricks","tags":["json","serialization","numpy","pandas","datetime","comments","custom-objects"],"install":[{"cmd":"pip install json-tricks","lang":"bash","label":"Install core library"},{"cmd":"pip install json-tricks[numpy,pandas]","lang":"bash","label":"Install with NumPy and Pandas support"}],"dependencies":[{"reason":"Required for native serialization/deserialization of NumPy arrays.","package":"numpy","optional":true},{"reason":"Required for native serialization/deserialization of Pandas DataFrames and Series.","package":"pandas","optional":true}],"imports":[{"note":"Since version 3.x, the numpy and pandas functionalities are integrated into the main json_tricks module, making direct imports of submodules like json_tricks.numpy unnecessary.","wrong":"import json_tricks.numpy","symbol":"json_tricks","correct":"import json_tricks"},{"note":"The top-level `dumps` function in `json_tricks` automatically handles NumPy arrays and other extended types when installed with optional dependencies.","wrong":"json_tricks.numpy.dumps","symbol":"dumps","correct":"json_tricks.dumps"},{"note":"To correctly deserialize objects encoded with `json_tricks` (especially with metadata or comments), always use `json_tricks.loads`.","wrong":"json.loads","symbol":"loads","correct":"json_tricks.loads"}],"quickstart":{"code":"import json_tricks\nimport numpy as np\nimport datetime\nimport pandas as pd\n\n# Example data with extended types\ndata = {\n    'numbers': np.array([1, 2, 3]),\n    'timestamp': datetime.datetime.now(),\n    'dataframe': pd.DataFrame({'a': [1, 2], 'b': [3, 4]}),\n    'mixed_list': [1, 'text', {'key': True}],\n    'comments_example': '// This is a comment inside JSON' # Will be stripped unless allow_comments is used in dump\n}\n\n# Dump to a JSON string with metadata to enable full round-tripping\njson_string = json_tricks.dumps(data, indent=4, store_python_metadata=True)\nprint('--- Dumped JSON ---')\nprint(json_string)\n\n# Load from the JSON string\nloaded_data = json_tricks.loads(json_string)\n\nprint('\\n--- Loaded Data ---')\nprint(loaded_data)\n\n# Verify types were restored\nprint(f\"Type of 'numbers': {type(loaded_data['numbers'])} \")\nprint(f\"Content of 'numbers': {loaded_data['numbers']}\")\nprint(f\"Type of 'timestamp': {type(loaded_data['timestamp'])}\")\nprint(f\"Type of 'dataframe': {type(loaded_data['dataframe'])}\")","lang":"python","description":"This quickstart demonstrates how to serialize and deserialize data containing NumPy arrays, datetime objects, and Pandas DataFrames using `json_tricks.dumps` and `json_tricks.loads`. It highlights the importance of `store_python_metadata=True` for successful round-tripping of complex types."},"warnings":[{"fix":"Always use `json_tricks.dumps(data, store_python_metadata=True)` when serializing complex Python objects that need to be fully restored.","message":"For `json-tricks` to properly restore complex Python objects (like custom classes, NumPy arrays, Pandas DataFrames, or datetimes) to their original types upon deserialization, you must pass `store_python_metadata=True` to the `json_tricks.dumps` function. Without it, these objects might be loaded as generic lists, dictionaries, or strings.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Simply `import json_tricks` and use `json_tricks.dumps`/`loads` directly. Ensure `numpy` and `pandas` are installed if you intend to use their serialization features.","message":"Before version 3.x, you might have imported specific submodules like `json_tricks.numpy` or `json_tricks.pandas` to access their enhanced serialization. Since version 3.x, these functionalities are directly integrated into the main `json_tricks` module, making the submodule imports largely obsolete and potentially leading to `AttributeError`.","severity":"breaking","affected_versions":"< 3.0.0 (transition to 3.x and newer)"},{"fix":"Always use `json_tricks.loads` to load JSON that may contain comments, as it is designed to parse them correctly.","message":"While `json-tricks` supports comments in JSON, standard Python's `json` module does not. If you dump JSON with comments using `json_tricks.dumps(..., allow_comments=True)` and then attempt to load it with `json.loads` or `json.load`, it will raise a `json.JSONDecodeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only load JSON generated by trusted sources. If you must load untrusted JSON, disable `store_python_metadata=True` and avoid using `extra_obj_hooks` or `ignore_errors=False` (which allows calling `__init__` for unknown types).","message":"Loading JSON from untrusted sources with `store_python_metadata=True` or custom `extra_obj_hooks` can lead to arbitrary code execution. `json-tricks` can dynamically instantiate objects based on metadata, which is a security risk if malicious data is provided.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Define `__json_encode__(self)` and `__json_decode__(cls, **kwargs)` methods in your custom class. Then, ensure you call `json_tricks.dumps(your_object, store_python_metadata=True)`.","cause":"You are attempting to serialize a custom Python object that `json-tricks` doesn't know how to handle by default, and you haven't provided custom serialization methods (`__json_encode__`, `__json_decode__`) or enabled metadata storage.","error":"TypeError: Object of type <class 'your_module.CustomClass'> is not JSON serializable"},{"fix":"Remove the `.numpy` (or `.pandas`) from your imports and function calls. Simply use `import json_tricks` and then `json_tricks.dumps` or `json_tricks.loads`. Ensure `numpy` is installed.","cause":"You are trying to access the `numpy` submodule (e.g., `json_tricks.numpy`) in version 3.x or newer of `json-tricks`. This submodule access is deprecated and its functionality is now integrated directly into the main module.","error":"AttributeError: module 'json_tricks' has no attribute 'numpy'"},{"fix":"Use `json_tricks.loads` (or `json_tricks.load` for files) instead of `json.loads`. `json_tricks` is designed to correctly parse JSON containing comments.","cause":"This error typically occurs when you try to load JSON that contains C-style comments (which `json-tricks` supports) using Python's standard `json.loads` or `json.load` function, which does not understand comments.","error":"json.JSONDecodeError: Expecting value: line X column Y (char Z)"}]}