socket – низкоуровневый сетевой интерфейс¶socket – Low-level networking interface

Семейства сокетов¶Socket families

В зависимости от системы и параметров сборки этим модулем поддерживаются различные семейства сокетов.

Формат адреса, требуемый для конкретного объекта сокета, автоматически выбирается на основе семейства адресов, указанного при создании объекта сокета. Адреса сокетов представляются следующим образом:

• Адрес сокета AF_UNIX, привязанного к узлу файловой системы, представляется в виде строки с использованием кодировки файловой системы и обработчика ошибок 'surrogateescape' (см. PEP 383). Адрес в абстрактном пространстве имён Linux возвращается как байтоподобный объект с начальным нулевым байтом; обратите внимание, что сокеты в этом пространстве имён могут взаимодействовать с обычными файловыми сокетами, поэтому программы, предназначенные для работы в Linux, возможно, должны работать с обоими типами адресов. Строка или байтоподобный объект могут использоваться для любого из этих типов адресов при передаче в качестве аргумента.

  Изменено в версии 3.3: Ранее предполагалось, что пути сокетов AF_UNIX используют кодировку UTF-8.

  Изменено в версии 3.5: Теперь принимается записываемый байтоподобный объект.

• Пара (host, port) используется для семейства адресов AF_INET, где host – строка, представляющая либо имя хоста в доменной нотации Интернета, например 'daring.cwi.nl', либо IPv4-адрес, например '100.50.200.5', а port – целое число.

  • Для IPv4-адресов вместо адреса хоста принимаются две специальные формы: '' представляет INADDR_ANY, что используется для привязки ко всем интерфейсам, а строка '<broadcast>' представляет INADDR_BROADCAST. Такое поведение несовместимо с IPv6, поэтому, возможно, следует избегать их, если предполагается поддержка IPv6 в программах на Python.

• Для семейства адресов AF_INET6 используется четвёрка (host, port, flowinfo, scope_id), где flowinfo и scope_id представляют элементы sin6_flowinfo и sin6_scope_id в struct sockaddr_in6 на языке C. Для методов модуля socket flowinfo и scope_id могут быть опущены только для обратной совместимости. Однако обратите внимание, что пропуск scope_id может вызвать проблемы при работе с адресами IPv6, имеющими область действия (scoped).

  Изменено в версии 3.7: Для многоадресных адресов (когда scope_id имеет значение) address может не содержать часть %scope_id (или zone id). Эта информация является избыточной и может быть безопасно опущена (рекомендуется).

• Сокеты AF_NETLINK представляются в виде пар (pid, groups).

• Поддержка TIPC только в Linux доступна через семейство адресов AF_TIPC. TIPC – это открытый сетевой протокол, не основанный на IP, предназначенный для использования в кластерных средах. Адреса представляются кортежем, и поля зависят от типа адреса. Общий вид кортежа: (addr_type, v1, v2, v3 [, scope]), где:

  • addr_type – одно из значений TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME или TIPC_ADDR_ID.

  • scope – одно из значений TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE и TIPC_NODE_SCOPE.

  • Если addr_type равно TIPC_ADDR_NAME, то v1 – тип сервера, v2 – идентификатор порта, а v3 должно быть 0.

    Если addr_type равно TIPC_ADDR_NAMESEQ, то v1 – тип сервера, v2 – нижний номер порта, а v3 – верхний номер порта.

    Если addr_type равно TIPC_ADDR_ID, то v1 – узел, v2 – ссылка, а v3 должно быть установлено в 0.

• Кортеж (interface, ) используется для семейства адресов AF_CAN, где interface – строка, представляющая имя сетевого интерфейса, например 'can0'. Имя сетевого интерфейса '' может использоваться для приёма пакетов от всех сетевых интерфейсов данного семейства.

  • CAN_ISOTP протокол требует кортеж (interface, rx_addr, tx_addr) где оба дополнительных параметра представляют собой беззнаковое длинное целое, задающее идентификатор CAN (стандартный или расширенный).

  • CAN_J1939 протокол требует кортеж (interface, name, pgn, addr) где дополнительные параметры – 64-битное беззнаковое целое, представляющее имя ECU, 32-битное беззнаковое целое, представляющее номер группы параметров (PGN), и 8-битное целое, представляющее адрес.

• Строка или кортеж (id, unit) используется для протокола SYSPROTO_CONTROL семейства PF_SYSTEM. Строка – это имя элемента управления ядра с динамически назначаемым ID. Кортеж может использоваться, если известны ID и номер устройства элемента управления ядра или если используется зарегистрированный ID.

  Новое в версии 3.3.

• AF_BLUETOOTH поддерживает следующие протоколы и форматы адресов:

  • BTPROTO_L2CAP принимает (bdaddr, psm), где bdaddr – адрес Bluetooth в виде строки, а psm – целое число.

  • BTPROTO_RFCOMM принимает (bdaddr, channel), где bdaddr – это Bluetooth-адрес в виде строки, а channel – целое число.

  • BTPROTO_HCI принимает (device_id,), где device_id – это либо целое число, либо строка с Bluetooth-адресом интерфейса. (Зависит от ОС: NetBSD и DragonFlyBSD ожидают Bluetooth-адрес, все остальные – целое число.)

    Изменено в версии 3.2: Добавлена поддержка NetBSD и DragonFlyBSD.

  • BTPROTO_SCO принимает bdaddr, где bdaddr – это объект bytes, содержащий Bluetooth-адрес в строковом формате (например, b'12:23:34:45:56:67'). Этот протокол не поддерживается в FreeBSD.

• AF_ALG – это интерфейс на основе сокетов, доступный только в Linux, для работы с криптографией ядра. Сокет алгоритма настраивается кортежем из двух-четырёх элементов (type, name [, feat [, mask]]), где:

  • type – тип алгоритма в виде строки, напр. aead, hash, skcipher или rng.

  • name – имя алгоритма и режим работы в виде строки, напр. sha256, hmac(sha256), cbc(aes) или drbg_nopr_ctr_aes256.

  • feat и mask – это 32-битные целые числа без знака.

  Доступность: Linux >= 2.6.38.

  Некоторые типы алгоритмов требуют более новых версий ядра.

  Новое в версии 3.6.

• AF_VSOCK обеспечивает взаимодействие между виртуальными машинами и их хостами. Сокеты представлены кортежем (CID, port), где идентификатор контекста (CID) и порт – целые числа.

  Доступность: Linux >= 3.9

  См. vsock(7)

  Добавлено в версии 3.7.

• AF_PACKET – низкоуровневый интерфейс для прямого доступа к сетевым устройствам. Адреса представляются кортежем (ifname, proto[, pkttype[, hatype[, addr]]]), где:

  • ifname – строка, задающая имя устройства.

  • proto – целое число, задающее номер протокола Ethernet.

  • pkttype – необязательное целое число, задающее тип пакета:

    • PACKET_HOST (по умолчанию) – пакет, адресованный локальному хосту.

    • PACKET_BROADCAST – широковещательный пакет физического уровня.

    • PACKET_MULTICAST – пакет, отправленный на многоадресный адрес физического уровня.

    • PACKET_OTHERHOST – пакет, предназначенный другому хосту, но перехваченный драйвером устройства в неразборчивом режиме (promiscuous).

    • PACKET_OUTGOING – пакет, отправленный с локального хоста и возвращённый обратно на пакетный сокет.

  • hatype – необязательное целое число, задающее тип аппаратного адреса ARP.

  • addr – необязательный байтоподобный объект, задающий аппаратный физический адрес; его интерпретация зависит от устройства.

  Доступность: Linux >= 2.2.

• AF_QIPCRTR – это интерфейс на основе сокетов, доступный только в Linux, для связи с сервисами, работающими на сопроцессорах в платформах Qualcomm. Семейство адресов представляется в виде кортежа (node, port), где узел и порт являются неотрицательными целыми числами.

  Доступность: Linux >= 4.7.

  Новое в версии 3.8.

• IPPROTO_UDPLITE – это вариант UDP, который позволяет указать, какая часть пакета покрывается контрольной суммой. Добавляются два параметра сокета, которые можно изменить. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) изменяет какую часть исходящих пакетов покрывает контрольная сумма, а self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) отфильтровывает пакеты, которые покрывают слишком малую часть своих данных. В обоих случаях length должен быть в range(8, 2**16, 8).

  Такой сокет следует создавать с помощью socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv4 или socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv6.

  Доступность: Linux >= 2.6.20, FreeBSD >= 10.1

  Новое в версии 3.9.

Если в части узел адреса сокета IPv4/v6 указано имя узла, программа может демонстрировать недетерминированное поведение, так как Python использует первый адрес, возвращённый при разрешении DNS. Адрес сокета будет разрешаться по-разному в фактический IPv4/v6-адрес в зависимости от результатов разрешения DNS и/или конфигурации узла. Для детерминированного поведения используйте числовой адрес в части узел.

Все ошибки порождают исключения. Могут возникать обычные исключения для недопустимых типов аргументов и состояний нехватки памяти. Ошибки, связанные с семантикой сокетов или адресов, порождают OSError или одно из его подклассов.

Неблокирующий режим поддерживается через setblocking(). Его обобщение на основе тайм-аутов поддерживается через settimeout().

Содержимое модуля¶Module contents

Модуль socket экспортирует следующие элементы.

Объекты сокетов¶Socket Objects

Объекты сокетов имеют следующие методы. За исключением makefile(), они соответствуют системным вызовам Unix, применимым к сокетам.

socket.accept()¶

Принимает соединение. Сокет должен быть привязан к адресу и находиться в режиме прослушивания. Возвращаемое значение – пара (conn, address), где conn – это новый объект сокета, пригодный для отправки и получения данных по соединению, а address – адрес, привязанный к сокету на другом конце соединения.

Новый созданный сокет ненаследуемый.

Изменено в версии 3.4: Сокет теперь ненаследуемый.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.bind(address)¶

Привязывает сокет к address. Сокет не должен быть уже привязан. (Формат address зависит от семейства адресов – см. выше.)

Возбуждает событие аудита socket.bind с аргументами self, address.

Доступность: не WASI.

socket.close()¶

Помечает сокет как закрытый. Базовый системный ресурс (например, файловый дескриптор) также закрывается, когда все файловые объекты из makefile() будут закрыты. Как только это происходит, все последующие операции с объектом сокета будут завершаться ошибкой. Удалённая сторона больше не получит данных (после сброса поставленных в очередь данных).

Сокеты автоматически закрываются при сборке мусора, но рекомендуется явно close() их закрывать или использовать оператор with вокруг них.

Изменено в версии 3.6: Теперь OSError возбуждается, если при выполнении close() возникает ошибка.

Примечание

close() освобождает ресурс, связанный с соединением, но не обязательно немедленно закрывает соединение. Если требуется своевременно закрыть соединение, вызовите shutdown() перед close().

socket.connect(address)¶

Подключается к удалённому сокету по адресу address. (Формат address зависит от семейства адресов – см. выше.)

Если соединение прерывается сигналом, метод ожидает его завершения или вызывает исключение TimeoutError по таймауту, если обработчик сигнала не возбуждает исключение, а сокет является блокирующим или имеет таймаут. Для неблокирующих сокетов метод вызывает исключение InterruptedError, если соединение прерывается сигналом (или исключение, возбуждённое обработчиком сигнала).

Возбуждает событие аудита socket.connect с аргументами self, address.

Изменено в версии 3.5: Теперь метод ждёт завершения соединения вместо возбуждения исключения InterruptedError, если соединение прервано сигналом, обработчик сигнала не вызывает исключение, а сокет является блокирующим или имеет тайм-аут (см. PEP 475 с обоснованием).

Доступность: не WASI.

socket.connect_ex(address)¶

Как и connect(address), но возвращает индикатор ошибки вместо возбуждения исключения для ошибок, возвращаемых вызовом connect() на уровне C (другие проблемы, например «хост не найден», по-прежнему могут вызывать исключения). Индикатор ошибки равен 0, если операция выполнена успешно, в противном случае – значению переменной errno. Это удобно, например, для поддержки асинхронных подключений.

Возбуждает событие аудита socket.connect с аргументами self, address.

Доступность: не WASI.

socket.detach()¶

Переводит объект сокета в закрытое состояние без фактического закрытия базового файлового дескриптора. Файловый дескриптор возвращается и может быть повторно использован для других целей.

Новое в версии 3.2.

socket.dup()¶

Дублирует сокет.

Новый созданный сокет ненаследуемый.

Изменено в версии 3.4: Сокет теперь ненаследуемый.

Доступность: не WASI.

socket.fileno()¶

Возвращает файловый дескриптор сокета (небольшое целое число) или -1 в случае ошибки. Это полезно с select.select().

В Windows небольшое целое число, возвращаемое этим методом, нельзя использовать там, где может быть использован файловый дескриптор (например, os.fdopen()). В Unix такого ограничения нет.

socket.get_inheritable()¶

Получить наследуемый флаг файлового дескриптора сокета или handle сокета: True, если сокет может наследоваться в дочерних процессах, False, если не может.

Новое в версии 3.4.

socket.getpeername()¶

Возвращает удалённый адрес, к которому подключён сокет. Это полезно, например, для определения номера порта удалённого сокета IPv4/v6. (Формат возвращаемого адреса зависит от семейства адресов – см. выше.) На некоторых системах эта функция не поддерживается.

socket.getsockname()¶

Возвращает собственный адрес сокета. Это полезно, например, для определения номера порта сокета IPv4/v6. (Формат возвращаемого адреса зависит от семейства адресов – см. выше.)

socket.getsockopt(level, optname[, buflen])¶

Возвращает значение заданной опции сокета (см. man-страницу Unix getsockopt(2)). Нужные символические константы (SO_* и т.д.) определены в этом модуле. Если параметр buflen отсутствует, предполагается целочисленная опция, и функция возвращает её целое значение. Если buflen присутствует, он задаёт максимальную длину буфера для получения опции, и этот буфер возвращается в виде объекта bytes. Задача вызывающего кода – декодировать содержимое буфера (см. встроенный необязательный модуль struct для способа декодирования C-структур, закодированных как байтовые строки).

Доступность: не WASI.

socket.getblocking()¶

Возвращает True, если сокет в блокирующем режиме, и False, если в неблокирующем.

Это эквивалентно проверке socket.gettimeout() != 0.

Добавлено в версии 3.7.

socket.gettimeout()¶

Возвращает тайм-аут в секундах (число с плавающей точкой), связанный с операциями сокета, или None, если тайм-аут не установлен. Это отражает последний вызов setblocking() или settimeout().

socket.ioctl(control, option)¶

Платформа:

Windows

Метод ioctl() является ограниченным интерфейсом к системному интерфейсу WSAIoctl. За дополнительной информацией обратитесь к документации Win32.

На других платформах можно использовать общие функции fcntl.fcntl() и fcntl.ioctl(); они принимают объект сокета в качестве первого аргумента.

В настоящее время поддерживаются только следующие управляющие коды: SIO_RCVALL, SIO_KEEPALIVE_VALS и SIO_LOOPBACK_FAST_PATH.

Изменено в версии 3.6: добавлен SIO_LOOPBACK_FAST_PATH.

socket.listen([backlog])¶

Включает возможность сервера принимать соединения. Если указан backlog, он должен быть не менее 0 (если меньше, устанавливается в 0); он задаёт количество непринятых соединений, которые система разрешит до отказа в новых соединениях. Если не указан, выбирается разумное значение по умолчанию.

Доступность: не WASI.

Изменено в версии 3.5: Параметр backlog теперь необязателен.

socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)¶

Возвращает файловый объект, связанный с сокетом. Точный возвращаемый тип зависит от аргументов, переданных в makefile(). Эти аргументы интерпретируются так же, как и встроенной функцией open(), за исключением того, что единственные поддерживаемые значения режима – 'r' (по умолчанию), 'w' и 'b'.

Сокет должен быть в блокирующем режиме; можно установить тайм-аут, но при его срабатывании внутренний буфер файлового объекта может оказаться в несогласованном состоянии.

Закрытие файлового объекта, возвращённого makefile(), не закроет исходный сокет, если только все остальные файловые объекты не будут закрыты и для объекта сокета не будет вызван socket.close().

Примечание

В Windows файлоподобный объект, созданный makefile(), нельзя использовать там, где ожидается файловый объект с дескриптором файла, например, в аргументах потока subprocess.Popen().

socket.recv(bufsize[, flags])¶

Принимает данные из сокета. Возвращаемое значение – объект bytes, представляющий полученные данные. Максимальный объём данных, который может быть принят за один раз, задаётся параметром bufsize. Пустой объект bytes означает, что клиент отключился. Смысл необязательного аргумента flags описан в справочной странице Unix recv(2); по умолчанию он равен нулю.

Примечание

Для наилучшего соответствия реальным характеристикам оборудования и сети значение bufsize должно быть относительно небольшой степенью двойки, например, 4096.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.recvfrom(bufsize[, flags])¶

Принимает данные из сокета. Возвращаемое значение – пара (bytes, address), где bytes – объект bytes, представляющий принятые данные, а address – адрес сокета, отправившего данные. См. страницу руководства Unix recv(2) для описания необязательного аргумента flags; по умолчанию он равен нулю. (Формат address зависит от семейства адресов – см. выше.)

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

Изменено в версии 3.7: Для многоадресного IPv6-адреса первый элемент address больше не содержит часть %scope_id. Чтобы получить полный IPv6-адрес, используйте getnameinfo().

socket.recvmsg(bufsize[, ancbufsize[, flags]])¶

Принимает обычные данные (до bufsize байт) и вспомогательные данные из сокета. Аргумент ancbufsize задаёт размер внутреннего буфера для приёма вспомогательных данных в байтах; по умолчанию равен 0, то есть вспомогательные данные приниматься не будут. Подходящие размеры буфера для вспомогательных данных можно вычислить с помощью CMSG_SPACE() или CMSG_LEN(); данные, не помещающиеся в буфер, могут быть усечены или отброшены. Аргумент flags по умолчанию равен 0 и имеет тот же смысл, что и для recv().

Возвращаемое значение – кортеж из 4 элементов: (data, ancdata, msg_flags, address). Элемент data – это объект bytes, содержащий принятые невспомогательные данные. Элемент ancdata – это список из нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), представляющих принятые вспомогательные данные (управляющие сообщения): cmsg_level и cmsg_type – целые числа, задающие уровень протокола и тип протокола соответственно, а cmsg_data – объект bytes с соответствующими данными. Элемент msg_flags – побитовое ИЛИ различных флагов, указывающих на состояние принятого сообщения; подробнее см. в системной документации. Если принимающий сокет не подключён, address – это адрес отправляющего сокета (если доступен); в противном случае его значение не определено.

В некоторых системах sendmsg() и recvmsg() можно использовать для передачи файловых дескрипторов между процессами через сокет AF_UNIX. Если эта возможность используется (часто она ограничена сокетами SOCK_STREAM), то recvmsg() вернёт во вспомогательных данных элементы вида (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds), где fds – объект bytes, представляющий новые файловые дескрипторы в виде двоичного массива нативного C-типа int. Если recvmsg() вызывает исключение после возврата из системного вызова, он сначала попытается закрыть все файловые дескрипторы, полученные через этот механизм.

Некоторые системы не указывают усечённую длину частично принятых вспомогательных данных. Если элемент, по-видимому, выходит за конец буфера, recvmsg() выдаст RuntimeWarning и вернёт ту его часть, которая находится в буфере, при условии, что она не была усечена до начала соответствующих данных.

В системах, поддерживающих механизм SCM_RIGHTS, следующая функция будет принимать до maxfds файловых дескрипторов, возвращая данные сообщения и список, содержащий дескрипторы (игнорируя неожиданные ситуации, такие как приём посторонних управляющих сообщений). См. также sendmsg().

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Массив целых чисел
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Добавить данные, игнорируя любые усечённые целые числа в конце.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Доступность: Unix.

Большинство Unix-платформ.

Новое в версии 3.3.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.recvmsg_into(buffers[, ancbufsize[, flags]])¶

Принимает обычные и вспомогательные данные из сокета, действуя как recvmsg(), но разбрасывает невспомогательные данные по нескольким буферам вместо возврата нового объекта bytes. Аргумент buffers должен быть итерируемым объектом, содержащим объекты, предоставляющие буферы для записи (например, объекты bytearray); они будут заполняться последовательными фрагментами невспомогательных данных, пока все данные не будут записаны или буферы не закончатся. Операционная система может установить ограничение (значение sysconf() SC_IOV_MAX) на количество используемых буферов. Аргументы ancbufsize и flags имеют тот же смысл, что и для recvmsg().

Возвращаемое значение – кортеж из 4 элементов: (nbytes, ancdata, msg_flags, address), где nbytes – общее количество байт невспомогательных данных, записанных в буферы, а ancdata, msg_flags и address такие же, как для recvmsg().

Пример:

>>> import socket
>>> s1, s2 = socket.socketpair()
>>> b1 = bytearray(b'----')
>>> b2 = bytearray(b'0123456789')
>>> b3 = bytearray(b'--------------')
>>> s1.send(b'Mary had a little lamb')
22
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
(22, [], 0, None)
>>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]

Доступность: Unix.

Большинство Unix-платформ.

Новое в версии 3.3.

socket.recvfrom_into(buffer[, nbytes[, flags]])¶

Принимает данные из сокета, записывая их в buffer вместо создания новой последовательности байтов. Возвращаемое значение – пара (nbytes, address), где nbytes – количество принятых байтов, а address – адрес отправляющего сокета. Смысл необязательного аргумента flags описан на странице руководства Unix recv(2); по умолчанию он равен нулю. (Формат address зависит от семейства адресов – см. выше.)

socket.recv_into(buffer[, nbytes[, flags]])¶

Принимает до nbytes байт из сокета, сохраняя данные в буфер вместо создания новой строки байтов. Если nbytes не указан (или равен 0), принимает до размера доступного места в указанном буфере. Возвращает количество принятых байт. Смысл необязательного аргумента flags описан в справочной странице Unix recv(2); по умолчанию равен нулю.

socket.send(bytes[, flags])¶

Отправляет данные в сокет. Сокет должен быть подключён к удалённому сокету. Необязательный аргумент flags имеет тот же смысл, что и для recv() выше. Возвращает количество отправленных байтов. Приложения обязаны проверять, что все данные были отправлены; если передана только часть данных, приложение должно попытаться отправить оставшиеся. Дополнительную информацию по этой теме можно найти в Socket Programming HOWTO.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.sendall(bytes[, flags])¶

Отправляет данные в сокет. Сокет должен быть подключён к удалённому сокету. Необязательный аргумент flags имеет тот же смысл, что и для recv() выше. В отличие от send(), этот метод продолжает отправлять данные из bytes, пока не будут отправлены все данные или не произойдёт ошибка. При успехе возвращается None. В случае ошибки выбрасывается исключение, и невозможно определить, сколько данных, если вообще, было успешно отправлено.

Изменено в версии 3.5: Тайм-аут сокета больше не сбрасывается при каждой успешной отправке данных. Теперь тайм-аут сокета – это максимальная общая продолжительность отправки всех данных.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.sendto(bytes, address)¶

socket.sendto(bytes, flags, address)

Отправляет данные в сокет. Сокет не должен быть подключён к удалённому сокету, поскольку целевой сокет задаётся параметром address. Необязательный аргумент flags имеет тот же смысл, что и для recv() выше. Возвращает количество отправленных байтов. (Формат address зависит от семейства адресов – см. выше.)

Возбуждает событие аудита socket.sendto с аргументами self, address.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.sendmsg(buffers[, ancdata[, flags[, address]]])¶

Отправляет обычные и вспомогательные данные в сокет, собирая невспомогательные данные из серии буферов и объединяя их в одно сообщение. Аргумент buffers задаёт невспомогательные данные как итерируемый объект из bytes-подобных объектов (например, объекты bytes); операционная система может установить ограничение (значение sysconf() SC_IOV_MAX) на количество буферов, которые можно использовать. Аргумент ancdata задаёт вспомогательные данные (управляющие сообщения) как итерируемый объект из нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), где cmsg_level и cmsg_type – целые числа, определяющие уровень протокола и тип протокола соответственно, а cmsg_data – bytes-подобный объект, содержащий соответствующие данные. Обратите внимание, что некоторые системы (в частности, системы без CMSG_SPACE()) могут поддерживать отправку только одного управляющего сообщения за вызов. Аргумент flags по умолчанию равен 0 и имеет то же значение, что и для send(). Если address указан и не равен None, он устанавливает адрес назначения для сообщения. Возвращаемое значение – количество отправленных байтов невспомогательных данных.

Следующая функция отправляет список файловых дескрипторов fds через сокет AF_UNIX в системах, поддерживающих механизм SCM_RIGHTS. См. также recvmsg().

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

Доступность: Unix, не WASI.

Большинство Unix-платформ.

Возбуждает событие аудита socket.sendmsg с аргументами self, address.

Новое в версии 3.3.

Изменено в версии 3.5: Если системный вызов прерван и обработчик сигнала не вызывает исключение, метод теперь повторяет системный вызов вместо того, чтобы вызывать исключение InterruptedError (см. PEP 475 с обоснованием).

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])¶

Специализированная версия sendmsg() для сокета AF_ALG. Устанавливает режим, IV, длину связанных данных AEAD и флаги для сокета AF_ALG.

Доступность: Linux >= 2.6.38.

Новое в версии 3.6.

socket.sendfile(file, offset=0, count=None)¶

Отправляет файл до достижения EOF, используя высокопроизводительный os.sendfile, и возвращает общее количество отправленных байтов. file должен быть обычным файловым объектом, открытым в двоичном режиме. Если os.sendfile недоступен (например, в Windows) или file не является обычным файлом, вместо него будет использован send(). offset указывает, откуда начинать чтение файла. Если указан, count – это общее количество байтов для передачи, в отличие от отправки файла до EOF. Позиция файла обновляется при возврате, а также в случае ошибки, и тогда file.tell() можно использовать для определения количества отправленных байтов. Сокет должен быть типа SOCK_STREAM. Неблокирующие сокеты не поддерживаются.

Новое в версии 3.5.

socket.set_inheritable(inheritable)¶

Устанавливает флаг наследования файлового дескриптора сокета или дескриптора сокета.

Новое в версии 3.4.

socket.setblocking(flag)¶

Устанавливает блокирующий или неблокирующий режим сокета: если flag равен false, сокет переводится в неблокирующий режим, иначе в блокирующий.

Этот метод является сокращённой записью для определённых вызовов settimeout():

• sock.setblocking(True) эквивалентен sock.settimeout(None)

• sock.setblocking(False) эквивалентен sock.settimeout(0.0)

Изменено в версии 3.7: Метод больше не применяет флаг SOCK_NONBLOCK на socket.type.

socket.settimeout(value)¶

Устанавливает тайм-аут для блокирующих операций с сокетом. Аргумент value может быть неотрицательным числом с плавающей запятой, задающим секунды, или None. Если задано ненулевое значение, последующие операции с сокетом будут вызывать исключение timeout, если время тайм-аута value истекло до завершения операции. Если задан ноль, сокет переводится в неблокирующий режим. Если задан None, сокет переводится в блокирующий режим.

Для получения дополнительной информации обратитесь к заметкам о тайм-аутах сокетов.

Изменено в версии 3.7: Метод больше не переключает флаг SOCK_NONBLOCK на socket.type.

socket.setsockopt(level, optname, value: int)¶

socket.setsockopt(level, optname, value: buffer)

socket.setsockopt(level, optname, None, optlen: int)

Устанавливает значение заданной опции сокета (см. страницу руководства Unix setsockopt(2)). Необходимые символические константы определены в этом модуле (SO_* и др. <socket-unix-constants>). Значение может быть целым числом, None или bytes-like object, представляющим буфер. В последнем случае вызывающий должен убедиться, что последовательность байтов содержит правильные биты (см. опциональный встроенный модуль struct для способа кодирования структур C в виде последовательностей байтов). Когда value установлено в None, требуется аргумент optlen. Это эквивалентно вызову функции C setsockopt() с optval=NULL и optlen=optlen.

Изменено в версии 3.5: Теперь принимается записываемый байтоподобный объект.

Изменено в версии 3.6: Добавлена форма setsockopt(level, optname, None, optlen: int).

Доступность: не WASI.

socket.shutdown(how)¶

Завершает одну или обе половины соединения. Если how равен SHUT_RD, дальнейшие приёмы запрещены. Если how равен SHUT_WR, дальнейшие отправки запрещены. Если how равен SHUT_RDWR, дальнейшие отправки и приёмы запрещены.

Доступность: не WASI.

socket.share(process_id)¶

Дублирует сокет и подготавливает его для совместного использования с целевым процессом. Целевому процессу должен быть предоставлен идентификатор process_id. Полученный bytes-объект затем может быть передан целевому процессу с помощью какой-либо формы межпроцессного взаимодействия, и сокет может быть воссоздан там с помощью fromshare(). После вызова этого метода сокет можно безопасно закрыть, так как операционная система уже продублировала его для целевого процесса.

Доступность: Windows.

Новое в версии 3.3.

Обратите внимание, что методы read() и write() отсутствуют; вместо них используйте recv() и send() без аргумента flags.

Объекты сокетов также имеют следующие (только для чтения) атрибуты, соответствующие значениям, переданным конструктору socket.

socket.family¶

Семейство сокета.

socket.type¶

Тип сокета.

socket.proto¶

Протокол сокета.

Примечания о тайм-аутах сокетов¶Notes on socket timeouts

Объект сокета может находиться в одном из трех режимов: блокирующем, неблокирующем или режиме тайм-аута. По умолчанию сокеты всегда создаются в блокирующем режиме, но это можно изменить, вызвав setdefaulttimeout().

• В блокирующем режиме операции блокируются до завершения или пока система не вернет ошибку (например, истекло время соединения).

• В неблокирующем режиме операции завершаются ошибкой (к сожалению, зависящей от системы), если их нельзя выполнить немедленно: функции из модуля select можно использовать, чтобы узнать, когда и готов ли сокет для чтения или записи.

• В режиме тайм-аута операции завершаются ошибкой, если их нельзя выполнить в течение заданного для сокета тайм-аута (возникает исключение timeout) или если система возвращает ошибку.

Пример¶Example

Вот четыре минимальных примера программ, использующих протокол TCP/IP: сервер, который отправляет обратно все полученные данные (обслуживая только одного клиента), и использующий его клиент. Обратите внимание, что сервер должен выполнить последовательность socket(), bind(), listen(), accept() (возможно, повторяя accept() для обслуживания более одного клиента), в то время как клиенту нужна только последовательность socket(), connect(). Также обратите внимание, что сервер не вызывает sendall()/recv() на сокете, который слушает, а на новом сокете, возвращённом accept().

Первые два примера поддерживают только IPv4.

# Программа эхо-сервера
import socket

HOST = ''                 # Символическое имя, обозначающее все доступные интерфейсы
PORT = 50007              # Произвольный непривилегированный порт
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)

# Программа эхо-клиента
import socket

HOST = 'daring.cwi.nl'    # Удалённый хост
PORT = 50007              # Тот же порт, что и у сервера
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

Следующие два примера идентичны двум предыдущим, но поддерживают как IPv4, так и IPv6. Серверная сторона будет слушать первое доступное семейство адресов (вместо этого следует слушать оба). В большинстве систем, поддерживающих IPv6, IPv6 будет иметь приоритет, и сервер может не принимать IPv4-трафик. Клиентская сторона попытается подключиться ко всем адресам, возвращённым в результате разрешения имён, и отправляет трафик на первый успешно подключённый.

# Программа эхо-сервера
import socket
import sys

HOST = None               # Символическое имя, обозначающее все доступные интерфейсы
PORT = 50007              # Произвольный непривилегированный порт
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)

# Программа эхо-клиента
import socket
import sys

HOST = 'daring.cwi.nl'    # Удалённый хост
PORT = 50007              # Тот же порт, что и у сервера
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

Следующий пример показывает, как написать очень простой снифер сети с помощью сырых сокетов в Windows. Для изменения интерфейса пример требует прав администратора:

import socket

# общедоступный сетевой интерфейс
HOST = socket.gethostbyname(socket.gethostname())

# создать сырой сокет и привязать его к общедоступному интерфейсу
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Включать IP-заголовки
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# принимать все пакеты
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# принять пакет
print(s.recvfrom(65565))

# неразборчивый режим отключён
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

Следующий пример показывает, как использовать интерфейс сокетов для связи с сетью CAN по протоколу сырых сокетов. Чтобы вместо этого использовать CAN с протоколом broadcast manager, откройте сокет с помощью:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

После привязки (CAN_RAW) или подключения (CAN_BCM) сокета вы можете использовать операции socket.send() и socket.recv() (и их аналоги) с объектом сокета как обычно.

Этот последний пример может требовать особых привилегий:

import socket
import struct


# Упаковка/распаковка CAN-фреймов (см. 'struct can_frame' в <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# создать сырой сокет и привязать его к интерфейсу 'vcan0'
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')

Запуск примера несколько раз со слишком маленькой задержкой между выполнениями может привести к этой ошибке:

OSError: [Errno 98] Address already in use

Это связано с тем, что предыдущее выполнение оставило сокет в состоянии TIME_WAIT, и его нельзя сразу использовать повторно.

Существует флаг socket, который можно установить, чтобы предотвратить это, socket.SO_REUSEADDR:

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))

Флаг SO_REUSEADDR указывает ядру переиспользовать локальный сокет в состоянии TIME_WAIT, не дожидаясь истечения его естественного тайм-аута.