socket — Низкоуровневый интерфейс сетевого взаимодействия

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

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

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

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

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

  Изменено в версии 3.5: Теперь принимается объект типа writable bytes-like.

• Пара (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 >= 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), но возвращает индикатор ошибки вместо генерирования исключения для ошибок, возвращаемых вызовом C-уровня 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. Возвращаемый пустой объект 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(), но разбросать данные, не относящиеся к дополнительным, по ряду буферов вместо возврата нового объекта байтов. Аргумент 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 зависит от семейства адресов — см. выше.)

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

Отправляет файл до достижения EOF, используя высокопроизводительный метод os.sendfile, и возвращает общее количество отправленных байтов. file должен быть объектом файла, открытым в двоичном режиме. Если os.sendfile недоступен (например, Windows) или file не является обычным файлом, будет использоваться send(). offset указывает с какой позиции начать чтение файла. Если указан, count — общее количество байтов для передачи вместо отправки файла до достижения EOF. Положение файла обновляется при возврате, а также в случае ошибки, в этом случае можно использовать 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, не дожидаясь истечения его естественного таймаута.