socket — Низкоуровневый сетевой интерфейс¶

Модуль¶

Модуль

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

• AF_UNIX`Формат `“surrogateescape“`` адреса, PEP 383 требуемый bytes-like object для конкретного объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

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

  Изменено в версии 3.5: :term:`bytes-like object`Формат адреса, требуемый для конкретного объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

• (host, port)``Формат :const:`AF_INET`  адреса, ``'daring.cwi.nl' требуемый '100.50.200.5' для конкретного объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

  • ''``Формат :const:`INADDR_ANY`  адреса, ``'<broadcast>' требуемый INADDR_BROADCAST для конкретного объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

• AF_INET6`Формат ``(host, port, flowinfo, scope_id)` адреса, sin6_flowinfo требуемый sin6_scope_id для struct sockaddr_in6 конкретного socket объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

  Изменено в версии 3.7: %scope_id``Формат ``zone id адреса, требуемый для конкретного объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

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

• AF_TIPC сокеты представлены в виде пар (addr_type, v1, v2, v3 [, scope]).

  • TIPC_ADDR_NAMESEQ сокеты представлены в виде пар TIPC_ADDR_NAME TIPC_ADDR_ID .

  • TIPC_ZONE_SCOPE сокеты представлены в виде пар TIPC_CLUSTER_SCOPE TIPC_NODE_SCOPE .

  • TIPC_ADDR_NAME сокеты представлены в виде пар .

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

    Если значение addr_type равно TIPC_ADDR_ID, то v1 - это тип сервера, v2 - нижний номер порта, а v3 - верхний номер порта.

• Кортеж (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. Строка - это имя элемента управления ядра, использующего динамически назначаемый идентификатор. Кортеж можно использовать, если известны идентификатор и номер модуля элемента управления ядром или если используется зарегистрированный идентификатор.

  Добавлено в версии 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 в виде строки, а - целое число.

    Изменено в версии 3.2: NetBSD and DragonFlyBSD support added.

  • BTPROTO_SCO принимает bdaddr, где bdaddr - это адрес Bluetooth в виде строки, а bytes - целое b'12:23:34:45:56:67' число.

• AF_ALG принимает (type, name [, feat [, mask]]), где - это адрес Bluetooth в виде строки, а - целое число.

  • aead принимает hash, где skcipher - это адрес Bluetooth в виде строки, а rng - целое число.

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

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

  :ref:`Availability <availability>`*feat* и mask - это 32-разрядные целые числа без знака.

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

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

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

  Availability обеспечивает обмен данными между виртуальными машинами и их хостами. Сокеты представлены в виде кортежа, где идентификатор контекста или CID и порт являются целыми числами.

  Смотрите vsock(7)

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

• Смотрите <<<0>> (ifname, proto[, pkttype[, hatype[, addr]]]) >

  • Смотрите

  • Смотрите

  • Смотрите

    • Смотрите PACKET_HOST

    • Смотрите PACKET_BROADCAST

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

    • PACKET_OTHERHOST - Пакет на какой-либо другой хост, который был перехвачен драйвером устройства в случайном режиме.

    • PACKET_OUTGOING - Пакет, исходящий от локального хоста, который передается обратно в пакетный сокет.

  • hatype - Необязательное целое число, указывающее тип аппаратного адреса ARP.

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

  Availability: Linux >= 2.2.

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

  Availability: 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.

  Availability: Linux >= 2.6.20, FreeBSD >= 10.1

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

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

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

Неблокирующий режим поддерживается с помощью setblocking(). Обобщение этого параметра, основанное на тайм-аутах, поддерживается с помощью settimeout().

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

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

Объекты сокета¶

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

socket.accept()¶

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

Вновь созданный сокет имеет значение non-inheritable.

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

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

socket.bind(address)¶

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

Создает auditing event socket.bind с аргументами self, address.

Availability: это был не я.

socket.close()¶

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

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

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

Примечание

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

socket.connect(address)¶

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

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

Создает auditing event socket.connect с аргументами self, address.

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

Availability: это был не я.

socket.connect_ex(address)¶

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

Создает auditing event socket.connect с аргументами self, address.

Availability: это был не я.

socket.detach()¶

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

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

socket.dup()¶

Продублируйте гнездо.

Вновь созданный сокет имеет значение non-inheritable.

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

Availability: это был не я.

socket.fileno()¶

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

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

socket.get_inheritable()¶

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

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

socket.getpeername()¶

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

socket.getsockname()¶

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

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

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

Availability: это был не я.

socket.getblocking()¶

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

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

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

socket.gettimeout()¶

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

socket.ioctl(control, option)¶

платформа:

Окна

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

На других платформах могут использоваться универсальные функции 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); оно указывает количество недопустимых подключений, которое система разрешит, прежде чем отказать в новых подключениях. Если не указано, то выбирается разумное значение по умолчанию.

Availability: это был не я.

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

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

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

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

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

Примечание

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

socket.recv(bufsize[, flags])¶

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

Примечание

Для наилучшего соответствия аппаратным и сетевым реалиям значение параметра bufsize должно быть относительно небольшим в степени 2, например, 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")   # Array of ints
    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:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Availability: 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---')]

Availability: Unix.

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

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

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

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

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

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

socket.send(bytes[, flags])¶

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

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

socket.sendall(bytes[, flags])¶

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

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

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

socket.sendto(bytes, address)¶

socket.sendto(bytes, flags, address)

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

Создает auditing event socket.sendto с аргументами self, address.

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

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

Отправляйте обычные и вспомогательные данные в сокет, собирая несвязанные данные из серии буферов и объединяя их в одно сообщение. Аргумент buffers определяет несвязанные данные как повторяемые из bytes-like objects (например, bytes объектов); операционная система может установить ограничение (sysconf() значение SC_IOV_MAX) для количество буферов, которые могут быть использованы. Аргумент ancdata определяет вспомогательные данные (управляющие сообщения) как повторяемый набор из нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), где cmsg_level и cmsg_type являются целыми числами, определяющими уровень протокола и специфичный для протокола тип соответственно, а cmsg_data является байтоподобным объектом хранящий связанные с ними данные. Обратите внимание, что некоторые системы (в частности, системы без 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))])

Availability: Unix, как и я.

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

Создает auditing event socket.sendmsg с аргументами self, address.

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

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

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

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

:ref:`Availability <availability>`*feat* и mask - это 32-разрядные целые числа без знака.

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

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

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

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

socket.set_inheritable(inheritable)¶

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

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

socket.setblocking(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, если время ожидания значение истекло до завершения операции. Если задано значение, отличное от нуля, сокет переводится в неблокирующий режим. Если задано значение None, сокет переводится в режим блокировки.

Для получения дополнительной информации, пожалуйста, обратитесь к notes on socket timeouts.

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

Изменено в версии 3.5: :term:`bytes-like object`Формат адреса, требуемый для конкретного объекта socket, выбирается автоматически на основе семейства адресов, указанного при создании объекта socket. Адреса сокетов представлены следующим образом:

Изменено в версии 3.6: добавлена форма setsockopt(уровень, optname, Нет, optlen: int).

Availability: это был не я.

socket.shutdown(how)¶

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

Availability: это был не я.

socket.share(process_id)¶

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

Availability: Окна.

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

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

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

socket.family¶

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

socket.type¶

Тип розетки.

socket.proto¶

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

Примечания по тайм-аутам сокетов¶

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

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

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

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

Пример¶

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

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

# Echo server program
import socket

HOST = ''                 # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
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)

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
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. Клиентская сторона попытается подключиться ко всем адресам, возвращенным в результате разрешения имен, и отправит трафик на первый успешно подключенный адрес.

# Echo server program
import socket
import sys

HOST = None               # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
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)

# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
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

# the public network interface
HOST = socket.gethostbyname(socket.gethostname())

# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# receive all packets
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a packet
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

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

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

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

Для этого последнего примера могут потребоваться особые привилегии:

import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <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])


# create a raw socket and bind it to the 'vcan0' interface
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, не дожидаясь истечения его естественного таймаута.