Cluster · разработчикам

Socket

Объект WSS-соединения. Перед отправкой и получением вызови open() или используй async with.

Все методы SDK · Типы и ошибки

Получение объекта

socket = app.web.socket("wss://example.org/events")

socket открыт через open() или async with; после close() нужен новый объект.

__init__

Создаёт Socket. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

def __init__(web: Web, url: str) -> None: ...

Аргументы

• web: Web, обязательный. Сетевая служба текущего приложения.
• url: str, обязательный. Полный HTTPS-адрес; для Socket требуется WSS. Ядро проверяет домен и допустимость адреса.

Результат

None. Создаёт Socket. Обычный способ получения объекта показан выше; прямой конструктор не выполняет сетевые запросы.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

# Обычный способ получения объекта:
socket = app.web.socket("wss://example.org/events")

open

Открывает соединение один раз и сохраняет ID ядра.

async def open() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Открывает соединение один раз и сохраняет ID ядра.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• ValueError('The socket has already been opened'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await socket.open()

active

Проверяет, что соединение открыто и не закрыто локально.

def active() -> None: ...

Аргументы

Нет.

Результат

None. Проверяет, что соединение открыто и не закрыто локально.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• ValueError('The socket is not active'): условие проверяется до продолжения операции.

Пример

result = socket.active()

send

Отправляет строку в активное соединение.

async def send(value: str) -> Self: ...

Аргументы

• value: str, обязательный. Текст кадра WSS. Для JSON используй send_json().

Результат

Self. Тот же объект после успешной операции. Отправляет строку в активное соединение.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• TypeError('A string is required; use send_json for JSON'): условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

await socket.send("ping")

send_json

Сериализует JSON без NaN и отправляет строковый кадр.

async def send_json(value: JSON) -> Self: ...

Аргументы

• value: JSON, обязательный. JSON-значение: только поддерживаемые типы; NaN, бесконечность и произвольные объекты запрещены.

Результат

Self. Тот же объект после успешной операции. Сериализует JSON без NaN и отправляет строковый кадр.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await socket.send_json({"count": 1})

receive

Ожидает кадр до wait секунд; возвращает str, bytes или None при отсутствии кадра.

async def receive(wait: float = 10) -> SocketValue: ...

Аргументы

• wait: float, по умолчанию 10. Время ожидания следующей порции или кадра в секундах в пределах службы ядра.

Результат

SocketValue. Ожидает кадр до wait секунд; возвращает str, bytes или None при отсутствии кадра.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await socket.receive()

receive_json

Разбирает полученный кадр как JSON; при отсутствии кадра возвращает None.

async def receive_json(wait: float = 10) -> JSON: ...

Аргументы

• wait: float, по умолчанию 10. Время ожидания следующей порции или кадра в секундах в пределах службы ядра.

Результат

JSON. Разбирает полученный кадр как JSON; при отсутствии кадра возвращает None.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.
• json.JSONDecodeError, если полученная строка не является JSON; UnicodeDecodeError, если байты нельзя декодировать.

Пример

result = await socket.receive_json()

__aiter__

Возвращает этот объект как асинхронный итератор. Сам запрос не выполняет.

def __aiter__() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Возвращает этот объект как асинхронный итератор. Сам запрос не выполняет.

Права

Не требует прав: операция выполняется локально и сама не обращается к ядру. Права понадобятся при отправке, сохранении или чтении через службу.

Ошибки

• Отдельного исключения SDK нет. Действуют обычные ошибки типов Python и ошибки переданных функций, если они используются.

Пример

async for value in socket:
    break

__anext__

Ожидает следующее значение, пропуская пустые опросы. После локального закрытия завершает перебор через StopAsyncIteration.

async def __anext__() -> SocketValue: ...

Аргументы

Нет.

Результат

SocketValue. Ожидает следующее значение, пропуская пустые опросы. После локального закрытия завершает перебор через StopAsyncIteration.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• StopAsyncIteration: условие проверяется до продолжения операции.
• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

async for value in socket:
    break

close

Закрывает активное соединение и запрещает дальнейшие операции этого объекта.

async def close() -> None: ...

Аргументы

Нет.

Результат

None. Закрывает активное соединение и запрещает дальнейшие операции этого объекта.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

result = await socket.close()

__aenter__

Вход в async with. Открывает соединение.

async def __aenter__() -> Self: ...

Аргументы

Нет.

Результат

Self. Тот же объект после успешной операции. Вход в async with. Открывает соединение.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

async with socket as active:
    pass

__aexit__

Выход из async with. Закрывает соединение, если оно ещё не закрыто. Исключения блока не подавляются.

async def __aexit__(kind: type[BaseException] | None, error: BaseException | None, traceback: TracebackType | None) -> None: ...

Аргументы

• kind: type[BaseException] | None, обязательный. Тип исключения блока либо None. Передаётся Python автоматически.
• error: BaseException | None, обязательный. Исключение блока async with либо None; контекстный протокол передаёт автоматически.
• traceback: TracebackType | None, обязательный. Трассировка исключения контекстного блока; передаётся Python автоматически.

Результат

None. Выход из async with. Закрывает соединение, если оно ещё не закрыто. Исключения блока не подавляются.

Права

Нужны web.request. Ограничение domains проверяется при запросе; web.full может заменить web.request.

Ошибки

• Ошибки ядра: AccessDenied при нехватке прав или выходе за ограничения, InvalidInput для неверных параметров, InvalidState для недоступного состояния, QuotaExceeded при превышении лимита, Unavailable при недоступной службе. Остальные коды представлены SDKError; см. TYPES.md. Ошибка канала связи вызывает RuntimeError. Действие с неизвестным результатом нельзя автоматически считать невыполненным.

Пример

async with socket as active:
    pass