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).

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

  • addr_type — одно из TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, или TIPC_ADDR_ID.
  • scope — одно из TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, и TIPC_NODE_SCOPE.

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

    Если addr_type — TIPC_ADDR_NAMESEQ, тогда v1 — тип сервера, v2 — меньший номер порта, а v3 — больший номер порта.

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

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

  • CAN_ISOTP протокол требует кортеж (interface, rx_addr, tx_addr), где оба дополнительных параметра — целые беззнаковые числа с плавающей запятой, представляющие идентификатор CAN (стандартный или расширенный).
  • CAN_J1939 протокол требует кортеж (interface, name, pgn, addr), где дополнительные параметры — 64-битное беззнаковое целое число, представляющее имя ECU, 32-битное беззнаковое целое число, представляющее номер группы параметров (PGN), и 8-битное целое число, представляющее адрес.

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

  Добавлена в версии 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) , где ID контекста или CID и порт — целые числа.

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

  См. vsock(7)

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

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

  • ifname — строка, определяющая имя устройства.
  • proto — номер Ethernet-протокола. Может быть ETH_P_ALL для захвата всех протоколов, одним из ETHERTYPE_* констант или любым другим номером 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.

• AF_HYPERV — это интерфейс сокетов, используемый только в Windows для связи с хостами и гостевыми системами Hyper-V. Семейство адресов представлено в виде кортежа (vm_id, service_id), где vm_id и service_id — UUID-строки.

  vm_id — это идентификатор виртуальной машины или набор известных значений VMID, если целевой объект не является конкретной виртуальной машиной. Известные константы VMID, определённые в socket, включают:

  • HV_GUID_ZERO
  • HV_GUID_BROADCAST
  • HV_GUID_WILDCARD — Используется для привязки к себе и для приема подключений со всех разделов.
  • HV_GUID_CHILDREN — Используется для привязки к себе и для приема подключений от дочерних разделов.
  • HV_GUID_LOOPBACK — Используется как целевой адрес для соединения с самим собой.
  • HV_GUID_PARENT — При использовании в качестве адреса привязки, принимает подключения от родительского раздела. При использовании в качестве целевого адреса подключается к родительскому разделу.

  service_id — это идентификатор зарегистрированной службы.

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

Если вы используете имя хоста в части 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)

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

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

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

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

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

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

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

socket.connect_ex(address)

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

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

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

socket.detach()

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

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

socket.dup()

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

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

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

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

socket.fileno()

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

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

socket.get_inheritable()

Получить флаг наследования дескриптора файла сокета или дескриптора сокета: 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()

Возвращает время ожидания в секундах (float), связанное с операциями сокета, или 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. Возвращаемый пустой объект bytes указывает на то, что клиент отключился. Обратитесь к странице руководства 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, представляющий новые дескрипторы файлов в виде двоичного массива типа int из C. Если 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 вместо создания нового объекта bytestring. Возвращаемое значение — пара (nbytes, address), где nbytes — количество полученных байтов, а address — адрес сокета, отправившего данные. См. страницу руководства Unix recv(2) для значения необязательного аргумента flags; он по умолчанию равен нулю. (Формат address зависит от семейства адресов — см. выше.)

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

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

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

import socket, array

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

socket.shutdown(how)

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

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

socket.share(process_id)

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

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

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

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

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

socket.family

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

socket.type

Тип сокета.

socket.proto

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

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

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