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

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

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

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

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

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

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

• Для семейства адресов AF_INET используется пара (host, port), где 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.

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

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

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

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

• AF_BLUETOOTH поддерживает следующие протоколы и форматы адресов:

  • BTPROTO_L2CAP принимает (bdaddr, psm), где bdaddr — Bluetooth-адрес в виде строки, а psm — целое число.
  • BTPROTO_RFCOMM принимает (bdaddr, channel), где bdaddr — Bluetooth-адрес в виде строки, а channel — целое число.

  • BTPROTO_HCI принимает формат, зависящий от вашей ОС.

    • В Linux принимается кортеж (device_id,), где device_id — целое число, указывающее номер устройства Bluetooth.
    • В FreeBSD, NetBSD и DragonFly BSD принимается bdaddr, где bdaddr — Bluetooth-адрес в виде строки.

    Изменено в версии 3.2: Добавлена поддержка NetBSD и DragonFlyBSD.

    Изменено в версии 3.13.3: Добавлена поддержка FreeBSD.

  • BTPROTO_SCO принимает bdaddr, где bdaddr — Bluetooth-адрес в виде строки или объект bytes (например, '12:23:34:45:56:67' или 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/IPv6 указать имя узла, программа может вести себя недетерминированно, поскольку Python использует первый адрес, возвращённый при разрешении DNS-имени. В фактический адрес IPv4/IPv6 адрес сокета будет преобразован по-разному в зависимости от результатов разрешения 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: Если при выполнении нижележащего вызова close() возникает ошибка, теперь возбуждается OSError.

Примечание

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. Вызывающая сторона должна декодировать содержимое буфера (способ декодирования структур C, закодированных в виде байтовых строк, описан в необязательном встроенном модуле struct).

Доступность: кроме 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 указывает на то, что клиент отключился. Значение необязательного аргумента flags описано на странице руководства Unix recv(2); по умолчанию оно равно нулю.

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

socket.recvfrom(bufsize[, flags])

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

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

Изменено в версии 3.7: Для многоадресного IPv6-адреса первый элемент 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, не создавая новую байтовую строку. Возвращаемое значение — пара (nbytes, address), где nbytes — количество полученных байтов, а address — адрес сокета, отправившего данные. Значение необязательного аргумента flags описано на странице руководства Unix recv(2); по умолчанию оно равно нулю. (Формат address зависит от семейства адресов — см. выше.)

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

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

socket.send(bytes[, flags])

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

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

socket.sendall(bytes[, flags])

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

Изменено в версии 3.5: Время ожидания сокета больше не сбрасывается после каждой успешной отправки данных. Теперь оно задаёт максимальную общую длительность отправки всех данных.

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

socket.sendto(bytes, address)

socket.sendto(bytes, flags, address)

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

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

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

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

socket.settimeout(value)

Установить время ожидания для блокирующих операций с сокетом. Аргумент value может быть неотрицательным числом с плавающей точкой, задающим секунды, или None. Если задано ненулевое значение, последующие операции с сокетом вызовут исключение timeout, если до завершения операции истечёт период ожидания value. Если задан 0, сокет переходит в неблокирующий режим. Если задано 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 или байтоподобный объект, представляющий буфер. В последнем случае вызывающий код должен самостоятельно убедиться, что байтовая строка содержит нужные биты (способ кодирования структур C в байтовые строки см. в необязательном встроенном модуле struct). Если для 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))

В следующем примере показано, как написать очень простой сетевой анализатор пакетов с помощью raw-сокетов в 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 через протокол raw-сокетов. Чтобы использовать CAN с протоколом broadcast manager, откройте сокет следующим образом:

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