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), где оба дополнительных параметра — целые числа без знака типа unsigned long, представляющие идентификатор 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 >= 3.9

  См. vsock(7)

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

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

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

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

    • PACKET_HOST (по умолчанию) — пакет, адресованный локальному хосту.
    • PACKET_BROADCAST — пакет широковещательной рассылки физического уровня.
    • PACKET_MULTICAST — пакет, отправленный на физический мультивещательный адрес.
    • PACKET_OTHERHOST — пакет, отправленный другому хосту, перехваченный драйвером устройства в режиме прослушивания.
    • 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

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

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

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

Режим без блокировки поддерживается с помощью 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.

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

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

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

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

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

socket.connect_ex(address)

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

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

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

socket.detach()

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

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

socket.dup()

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

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

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

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

socket.fileno()

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

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

socket.get_inheritable()

Получает флаг наследования дескриптора файла сокета или дескриптор сокета: 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-структур, закодированных как строки байтов).

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

socket.getblocking()

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

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

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

socket.gettimeout()

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

socket.ioctl(control, option)

Платформа

Windows

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

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

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

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

socket.listen([backlog])

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

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

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

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

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

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

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

Примечание

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

socket.recv(bufsize[, flags])

Получает данные из сокета. Значение возврата — это объект bytes, представляющий полученные данные. Максимальное количество данных, которое может быть получено за один раз, задаётся параметром bufsize. Обратитесь к странице руководства 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)

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

Принимает данные с сокета, записывая их в buffer вместо создания новой строки байтов. Возвращаемое значение — пара (nbytes, address), где nbytes — количество принятых байтов, а address — адрес сокета, отправляющего данные. См. страницу руководства 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(), этот метод продолжает отправлять данные из bytes, пока не будут отправлены все данные или не произойдёт ошибка. 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 — это bytes-like object, содержащий связанные данные. Обратите внимание, что некоторые системы (в частности, системы без CMSG_SPACE()) могут поддерживать отправку только одного управляющего сообщения за вызов. Аргумент flags по умолчанию равен 0 и имеет такое же значение, как для send(). Если address указан и не None, он устанавливает адрес назначения для сообщения. Возвращаемое значение — количество отправленных байтов не-дополнительных данных.

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

import socket, array

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

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

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

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

Доступность: 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 ложь, сокет устанавливается в неблокирующий режим, иначе в блокирующий.

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

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

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

socket.settimeout(value)

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

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

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

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

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

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

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

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

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

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

socket.shutdown(how)

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

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

socket.share(process_id)

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

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

Введено в версии 3.3.

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

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

socket.family

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

socket.type

Тип сокета.

socket.proto

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

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

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

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