Основные понятия
================

Короткие объяснения терминов, которые встречаются в примерах.
Начать работу можно с :doc:`getting-started`, не читая эту страницу целиком.

.. glossary::

   binary format
      **Бинарный формат** — правила записи данных в байты: какое поле идёт первым,
      сколько места занимает число, где заканчивается строка.
      Например: один байт температуры, затем один байт заряда батареи.

   field
      **Поле** — одно именованное значение модели, например ``name: str``.
      Значение записывается в сообщение; имя ``name`` остаётся в Python-классе.

   wire format
      **Формат передачи** — точные байты, которыми обмениваются программы.
      Число 42 может выглядеть как ``2a`` или ``00 00 00 2a``: значение одно,
      но форматы разные. Те же правила применимы к файлам.

   header
      **Заголовок** — служебные данные перед полями сообщения.
      Например, идентификатор сообщения и число байтов после заголовка.
      Стандартный заголовок bytespec занимает 14 байт; его можно настроить или убрать.

   payload
      **Содержимое сообщения** — байты полей после заголовка, включая их префиксы длины.
      У ``name="Anna"`` со стандартной настройкой это четыре байта длины и
      четыре байта текста. ``PayloadLength`` не включает сам заголовок.

   framing
      **Выделение границ сообщений** — способ понять, где заканчивается один
      пакет и начинается следующий. Например, заголовок хранит длину содержимого.
      Это особенно полезно, когда в одном буфере лежат несколько сообщений.

   byte order
      **Порядок байтов** определяет запись числа, занимающего несколько байтов.
      Число 258 в двух байтах: ``01 02`` при big-endian и ``02 01`` при little-endian.
      Само значение не меняется; отправитель и получатель должны выбрать один порядок.

   length prefix
      **Префикс длины** — число перед данными, указывающее их размер в байтах.
      В ``04 41 6e 6e 61`` первый байт означает: прочитать ещё четыре байта (``Anna``).
      ``prefix_length=1`` задаёт размер самого числа длины, а не текста.

   offset
      **Смещение** — позиция в буфере, отсчитываемая от нуля, как индекс в Python.
      ``decode_from(buffer, 7)`` начинает чтение с восьмого байта.
      Возвращённое смещение указывает, где начинать чтение следующего сообщения.

   flags
   bitmask
      **Флаги, или битовая маска**, — число, в котором отдельные биты обозначают
      наличие необязательных полей. ``flag=0`` выделяет полю крайний правый бит:
      ``00000001`` — поле есть, ``00000000`` — его нет.
      bytespec вычисляет маску по значениям; вручную передавать её не нужно.

   codec
      **Кодек** — правило преобразования одного значения в байты и обратно.
      Например, ``UInt32Codec`` записывает целое число четырьмя байтами.
      Обычно bytespec выбирает кодек по аннотации; собственный нужен для особого формата.

   varint
      **Целое переменной длины**: небольшие числа занимают меньше байтов.
      Например, ``VarUInt`` записывает 1 как ``01``, а 300 как ``ac 02``.
      ``VarInt`` также поддерживает отрицательные числа и использует другую запись;
      именно он выбран для обычного Python ``int``.

Попробовать эти понятия на данных: :doc:`examples`.
Точные размеры и правила чтения: :doc:`wire-format`.