socket — Интерфейс низкого уровня для сетевых соединений

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

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

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

• Адрес сокета 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-адресами.

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

  Добавлен в версии 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 >= 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 — пакет, отправленный в адрес физического уровня multicast.
    • PACKET_OTHERHOST — пакет, отправленный другому хосту, перехваченный драйвером устройства в режиме promiscuous.
    • PACKET_OUTGOING — пакет, исходящий от локального хоста, который возвращен обратно сокету пакетов.
  • hatype — необязательное целое число, указывающее тип аппаратного адреса ARP.
  • addr — необязательный объект типа bytes, указывающий аппаратный физический адрес, чья интерпретация зависит от устройства.

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

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

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

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

Все ошибки генерируют исключения. Могут быть подняты стандартные исключения для неверных типов аргументов и условий недостатка памяти; начиная с Python 3.3, ошибки, связанные с семантикой сокетов или адресов, генерируют OSError или один из его подклассов (ранее они генерировали socket.error).

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

Содержание модуля

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

Объекты сокетов

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

socket.accept()

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

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

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

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

socket.bind(address)

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

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

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

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

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

socket.connect_ex(address)

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

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

socket.detach()

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

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

socket.dup()

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

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

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

socket.fileno()

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

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

socket.get_inheritable()

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

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

socket.getpeername()

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

socket.getsockname()

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

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

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

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

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

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

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

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

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

Примечание

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

socket.recv(bufsize[, flags])

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

Примечание

Для наилучшего соответствия аппаратным и сетевым реалиям, значение 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")   # 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)

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

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

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

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

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

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

socket.send(bytes[, flags])

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

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

Вызывает событие аудита аудита 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)

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

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

socket.set_inheritable(inheritable)

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

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

socket.setblocking(flag)

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

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

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

Новое в версии 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 packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a package
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, без ожидания истечения его естественного таймаута.