YTsaurus YSON

0.4.10 · active · verified Sun Apr 12

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.

Warnings

breaking 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.
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 ...`.
gotcha `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.
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')`.
gotcha 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.
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`.
gotcha 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.
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.

Install

pip install ytsaurus-yson Install `ytsaurus-yson`

Imports

loads
```
from ytsaurus_yson import loads
```
dumps
```
from ytsaurus_yson import dumps
```
YsonType
```
from ytsaurus_yson import YsonType
```
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.

Quickstart

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.

from ytsaurus_yson import loads, dumps

# Deserialize YSON bytes to Python object
y_string_bytes = b'{key="value";number=123;list=[a;b;c;];}'
data = loads(y_string_bytes)
print(f"Deserialized: {data} (Type: {type(data)})\n")

# Serialize Python object to YSON bytes
python_object = {'name': 'Alice', 'age': 30, 'hobbies': ['reading', 'coding']}
yson_bytes = dumps(python_object)
print(f"Serialized: {yson_bytes} (Type: {type(yson_bytes)})\n")

# Demonstrate basic usage with YSON attributes (advanced)
yson_with_attrs = b'<"version"="1.0">{data="payload"}'
loaded_with_attrs = loads(yson_with_attrs)
print(f"Data with attributes: {loaded_with_attrs.value}, Attributes: {loaded_with_attrs.attributes}")

view raw JSON →