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

Семейства розеток¶

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

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

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

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

  Изменено в версии 3.5: Теперь допускается запись bytes-like object.

• Пара (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 на языке С. Для методов модуля socket, flowinfo и scope_id могут быть опущены просто для обратной совместимости. Заметим, однако, что опущение scope_id может вызвать проблемы при манипулировании скопированными адресами IPv6.

  Изменено в версии 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-битное беззнаковое целое число, представляющее имя ЭБУ, 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-битные целые числа.

  Availability: Linux 2.6.38, some algorithm types require more recent Kernels.

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

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

  Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.

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

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

  • ifname - Строка, указывающая имя устройства.

  • proto - целое число порядка байта в сети, указывающее номер протокола Ethernet.

  • pkttype - Необязательное целое число, указывающее тип пакета:

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

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

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

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

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

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

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

  Availability: Linux >= 2.2.

• AF_QIPCRTR - это интерфейс на базе сокетов только для Linux для связи с сервисами, работающими на сопроцессорах в платформах Qualcomm. Семейство адресов представлено в виде кортежа (node, port), где 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-RELEASE

  Добавлено в версии 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)¶

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

Вызывает auditing event socket.bind с аргументами self, address.

socket.close()¶

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

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

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

Примечание

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

socket.connect(address)¶

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

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

Вызывает auditing event socket.connect с аргументами self, address.

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

socket.connect_ex(address)¶

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

Вызывает auditing event socket.connect с аргументами self, address.

socket.detach()¶

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

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

socket.dup()¶

Дублировать гнездо.

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

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

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 man page getsockopt(2)). Необходимые символьные константы (SO_* и т.д.) определены в этом модуле. Если buflen отсутствует, предполагается целочисленная опция, и ее целочисленное значение возвращается функцией. Если buflen присутствует, он определяет максимальную длину буфера, используемого для приема опции, и этот буфер возвращается как объект bytes. Декодирование содержимого буфера остается за вызывающей стороной (см. дополнительный встроенный модуль struct для способа декодирования структур языка Си, закодированных как байтовые строки).

socket.getblocking()¶

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

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

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

socket.gettimeout()¶

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

socket.ioctl(control, option)¶

платформа

Windows

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

Изменено в версии 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.close() на объекте сокета.

Примечание

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

socket.recv(bufsize[, flags])¶

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

Примечание

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

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

socket.recvfrom(bufsize[, flags])¶

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

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

Изменено в версии 3.7: Для многоадресного IPv6-адреса первый элемент адрес больше не содержит части %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, возможно и другие.

Добавлено в версии 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, возможно и другие.

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

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

Вызывает 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, длины ассоциированных данных AEAD и флагов для сокета AF_ALG.

Availability: 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)¶

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

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

Изменено в версии 3.5: Теперь допускается запись bytes-like object.

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

socket.shutdown(how)¶

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

socket.share(process_id)¶

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

Availability: Windows.

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

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

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

socket.family¶

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

socket.type¶

Тип сокета.

socket.proto¶

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

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

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

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

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

• В режиме timeout операции завершаются неудачно, если они не могут быть выполнены в течение тайм-аута, указанного для сокета (они вызывают исключение 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)

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

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

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

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

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, не дожидаясь истечения его естественного таймаута.