{"id":4868,"library":"ytsaurus-yson","title":"YTsaurus YSON","description":"YTsaurus YSON (version 0.4.10) provides high-performance C++ bindings for YSON (Yandex Serialization Object Notation), enabling fast serialization and deserialization of YSON data. It is a sub-package of the larger `ytsaurus-python` project, specifically focused on YSON processing. Releases are tied to the `ytsaurus-python` project, with regular updates that reflect changes in the broader YTsaurus ecosystem.","status":"active","version":"0.4.10","language":"en","source_language":"en","source_url":"https://github.com/YTsaurus/ytsaurus-python","tags":["YSON","YTsaurus","serialization","data-format","binary-format","cpp-bindings"],"install":[{"cmd":"pip install ytsaurus-yson","lang":"bash","label":"Install `ytsaurus-yson`"}],"dependencies":[],"imports":[{"symbol":"loads","correct":"from ytsaurus_yson import loads"},{"symbol":"dumps","correct":"from ytsaurus_yson import dumps"},{"note":"The `ytsaurus-yson` package was separated from the monolithic `yt` library and `ytsaurus-python` package in version 0.4.0. Old import paths will no longer work.","wrong":"from yt.yson import YsonType","symbol":"YsonType","correct":"from ytsaurus_yson import YsonType"}],"quickstart":{"code":"from ytsaurus_yson import loads, dumps\n\n# Deserialize YSON bytes to Python object\ny_string_bytes = b'{key=\"value\";number=123;list=[a;b;c;];}'\ndata = loads(y_string_bytes)\nprint(f\"Deserialized: {data} (Type: {type(data)})\\n\")\n\n# Serialize Python object to YSON bytes\npython_object = {'name': 'Alice', 'age': 30, 'hobbies': ['reading', 'coding']}\nyson_bytes = dumps(python_object)\nprint(f\"Serialized: {yson_bytes} (Type: {type(yson_bytes)})\\n\")\n\n# Demonstrate basic usage with YSON attributes (advanced)\nyson_with_attrs = b'<\"version\"=\"1.0\">{data=\"payload\"}'\nloaded_with_attrs = loads(yson_with_attrs)\nprint(f\"Data with attributes: {loaded_with_attrs.value}, Attributes: {loaded_with_attrs.attributes}\")","lang":"python","description":"This quickstart demonstrates basic serialization (`dumps`) and deserialization (`loads`) of YSON data using `ytsaurus-yson`. Note that `loads` expects bytes and `dumps` produces bytes, consistent with the binary nature of YSON. It also shows how YSON attributes are handled."},"warnings":[{"fix":"Migrate your `pip install` commands from `ytsaurus-python` (if only YSON was needed) or `yt` to `pip install ytsaurus-yson`. Update import paths from `from yt.yson import ...` or `from ytsaurus_python.yson import ...` to `from ytsaurus_yson import ...`.","message":"The `ytsaurus-yson` package was refactored out of the main `ytsaurus-python` library and the legacy `yt` library. It is now a standalone installable package.","severity":"breaking","affected_versions":"<0.4.0"},{"fix":"Always encode Python strings to bytes (e.g., `s.encode('utf-8')`) before passing them to `loads` and decode `bytes` results to strings (e.g., `b.decode('utf-8')`) after `dumps` if string representation is needed. Example: `loads(b'{a=1}')`, `dumps({'a':1}).decode('utf-8')`.","message":"`ytsaurus-yson` functions `loads` and `dumps` primarily operate on `bytes` objects, not Python `str` objects, reflecting YSON's binary nature. Passing strings without encoding or expecting string output can lead to `TypeError` or incorrect deserialization.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that a C++ compiler (like GCC/Clang) and Python development headers are installed. On Debian/Ubuntu: `sudo apt-get install build-essential python3-dev`. On macOS with Homebrew: `xcode-select --install`.","message":"Installation of `ytsaurus-yson` requires a C++ compiler and associated build tools on the system, as it provides C++ bindings. This can be a common point of failure on environments without development dependencies.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of `YsonType` objects when deserializing YSON that contains these specific types or attributes. Use `isinstance()` checks and access `.value` or `.attributes` as needed. If strict Python types are required, manual conversion logic might be necessary.","message":"YSON has specific types (e.g., `entity`, `uint64`, `null`) and attributes which do not have direct, idiomatic Python equivalents. These are mapped to special `YsonType` objects (e.g., `YsonEntity`, `YsonUint64`) or accessed via `.attributes` on `YsonType` instances, which may require explicit handling.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}