Датаклассы

Внимание

Датаклассы поддерживаются только в Python 3.

Основной способ представления строк таблицы — это классы с полями, которые размечены типами (аналог dataclasses). См. также пример.

Мотивация

  1. Удобство: так как система скалярных типов YTsaurus более богатая, чем в Python, разметка типами помогает явно выразить желаемые типы колонок. Ещё лучше видно удобство при работе со сложными типами, например, структурами.
  2. Строгая типизация позволяет распознавать ошибки в коде до того, как они приведут к появлению некорректных данных и другим неприятным эффектам. В этом также могут помогать линтеры и IDE.
  3. Скорость: за счёт использования формата Skiff и некоторых других оптимизаций потребление CPU в несколько раз меньше, чем для нетипизированных данных.

Установка

Для работы с модулем yt.wrapper.schema установите пакеты:

  • typing_extensions
  • ytsaurus-yson
  • six

Введение

Для работы с табличными данными нужно объявить класс с декоратором yt.wrapper.yt_dataclass и разметить его поля типами. После двоеточия указывается тип поля. Это могут быть:

  • встроенные типы в Python: int, float, str и другие;
  • пользовательские классы с декоратором @yt_dataclass;
  • композитные типы из модуля typing. Сейчас поддерживаются List, Dict, Optional, Tuple. В планах поддержка ряда других типов.
  • специальные типы из yt.wrapper.schema: Int8, Uint16, OtherColumns и другие (более полный список ниже).

Пример:

@yt.wrapper.yt_dataclass
class Row:
    id: int
    name: str
    is_robot: bool = False

Для описанного таким образом класса будут сгенерированы конструктор и прочие служебные методы, в частности, __eq__ и __repr__. Для некоторых полей можно указать значение по умолчанию. Оно попадёт в сигнатуру конструктора. Объект данного класса можно создавать обычным образом: row = Row(id=123, name="foo"). При этом для всех полей, для которых не указаны значения по умолчанию (как для robot: bool = False), необходимо передать соответствующие поля в конструктор, иначе будет порождено исключение.

Для датаклассов поддерживается наследование.

Имея такой класс, можно:

  1. Создать таблицу с соответствующей схемой (можно просто начать писать в пустую или несуществующую таблицу или использовать функцию TableSchema.from_row_type()).
  2. Писать и читать таблицы, пример.
  3. Запускать операции, пример.

Также можно создавать датаклассы на основе схемы таблицы явно или автоматически, читая структурированные данные

yt_table_schema = client.get(f"{table_path}/@schema")
dataclass_type = yt.schema.make_dataclass_from_table_schema(yt.schema.TableSchema.from_yson_type(yt_table_schema))

# or

typed_table_data = list(client.read_table_structured(table=table_path, row_type=None))

Специальные типы

yt.wrapper.schema Python Схема
Int8, Int16, Int32, Int64 int int8, int16, int32, int64
Uint8, Uint16, Uint32, Uint64 int uint8, uint16, uint32, uint64
YsonBytes bytes yson/any
OtherColumns OtherColumns Соответствует нескольким колонкам.
Предыдущая
Следующая