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 принимается (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, если целевая система не является конкретной виртуальной машиной. На socket определены следующие константы известных значений VMID:

  • 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/IPv6. (Формат возвращаемого адреса зависит от семейства адресов — см. выше.) В некоторых системах эта функция не поддерживается.

socket.getsockname()

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

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

Некоторые системы не сообщают длину усечённых вспомогательных данных, полученных лишь частично. Если кажется, что элемент выходит за пределы буфера, recvmsg() выдаст предупреждение RuntimeWarning и вернёт ту часть элемента, которая помещается в буфер, если она не была усечена до начала связанных с ней данных.

В системах, поддерживающих механизм SCM_RIGHTS, следующая функция получит до maxfds файловых дескрипторов и вернёт данные сообщения и список с дескрипторами (игнорируя при этом неожиданные ситуации, например получение несвязанных управляющих сообщений). См. также sendmsg().

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

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

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

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

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

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

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

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

Пример:

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

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

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

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

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

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

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

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

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 (например, объектов bytes); операционная система может установить ограничение (sysconf() со значением SC_IOV_MAX) на количество используемых буферов. Аргумент ancdata задаёт вспомогательные данные (управляющие сообщения) как итерируемый объект из нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), где cmsg_level и cmsg_type — целые числа, задающие соответственно уровень протокола и тип, специфичный для протокола, а cmsg_data — объект, подобный bytes, содержащий связанные данные. Обратите внимание, что некоторые системы (в частности, системы без 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. Если задан ноль, сокет переводится в неблокирующий режим. Если задано 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 или объект, подобный bytes, представляющий буфер. В последнем случае вызывающий код должен убедиться, что байтовая строка содержит нужные биты (способ кодирования структур C в байтовые строки см. в необязательном встроенном модуле struct). Если для value задано None, требуется аргумент optlen. Это эквивалентно вызову функции C setsockopt() с optval=NULL и optlen=optlen.

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

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