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

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

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

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

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

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

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

• Пара (host, port) используется для семейства адресов AF_INET, где host — строка, представляющая либо имя хоста в обозначении интернет-домена, например, 'daring.cwi.nl', либо IPv4-адрес, например, '100.50.200.5', а port — целое число.

  • Для IPv4-адресов принимаются две специальные формы вместо адреса хоста: '' представляет INADDR_ANY, что используется для привязки ко всем интерфейсам, а строка '<broadcast>' представляет INADDR_BROADCAST. Это поведение несовместимо с IPv6, поэтому, если вы планируете поддержку IPv6 в своих программах Python, следует избегать этих форм.

• Для семейства адресов AF_INET6 используется четвёрка (host, port, flowinfo, scope_id), где flowinfo и scope_id представляют члены sin6_flowinfo и sin6_scope_id в struct sockaddr_in6 в C. Для методов модуля socket flowinfo и scope_id могут быть опущены для обратной совместимости. Однако следует отметить, что опускание scope_id может вызвать проблемы при манипулировании адресами IPv6 с областью действия.

  Изменено в версии 3.7: Для адресов мультивещания (с имеющим значением scope_id) часть address может не содержать %scope_id (или zone id). Эта информация избыточна и может быть безопасно опущена (рекомендуется).

• AF_NETLINK сокеты представляются как пары (pid, groups).

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

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

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

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

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

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

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

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

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

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

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

  • BTPROTO_HCI принимает (device_id,), где device_id — либо целое число, либо строка с адресом Bluetooth интерфейса. (Это зависит от вашей ОС; NetBSD и DragonFlyBSD ожидают адрес Bluetooth, а всё остальное — целое число.)

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

  • BTPROTO_SCO принимает bdaddr, где bdaddr — объект bytes, содержащий адрес Bluetooth в формате строки. (например, b'12:23:34:45:56:67'). Этот протокол не поддерживается в FreeBSD.

• AF_ALG — интерфейс сокетов (только для Linux) для доступа к криптографии ядра. Сокет алгоритма настраивается с кортежем из двух до четырёх элементов (type, name [, feat [, mask]]), где:

  • type — тип алгоритма как строка, например, aead, hash, skcipher или rng.
  • name — имя алгоритма и режим работы как строка, например, sha256, hmac(sha256), cbc(aes) или drbg_nopr_ctr_aes256.
  • feat и mask — 32-битные целые числа без знака.

  Доступность: Linux 2.6.38, некоторые типы алгоритмов требуют более новых ядер.

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

• AF_VSOCK позволяет осуществлять взаимодействие между виртуальными машинами и их хостами. Сокеты представляются как кортеж (CID, port), где идентификатор контекста или CID и порт — целые числа.

  Доступность: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.

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

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

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

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

    • PACKET_HOST (по умолчанию) — пакет, адресованный локальному хосту.
    • PACKET_BROADCAST — пакет широковещательной передачи физического уровня.
    • PACKET_MULTIHOST — пакет, отправленный на физический многоадресную группу.
    • PACKET_OTHERHOST — пакет, отправленный другому хосту, пойманный драйвером устройства в режиме прослушивания.
    • PACKET_OUTGOING — пакет, исходящий от локального хоста, который циклически возвращается в сокет пакета.
  • hatype — необязательное целое число, определяющее тип адреса аппаратного ARP.
  • addr — необязательный объект типа bytes-like, определяющий физический адрес аппаратного обеспечения, чья интерпретация зависит от устройства.

  Доступность: 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-RELEASE

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

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

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

Поддерживается режим без блокировки через setblocking(). Обобщение этого, основанное на тайм-аутах, поддерживается через settimeout().

Содержание модуля

Модуль socket экспортирует следующие элементы.

Объекты сокетов

Объекты сокетов имеют следующие методы. За исключением makefile(), они соответствуют системным вызовам Unix, применимым к сокетам.

socket.accept()

Принять подключение. Сокет должен быть привязан к адресу и ожидать подключений. Возвращаемое значение — пара (conn, address) , где conn — новый объект сокета, используемый для отправки и получения данных по подключению, а address — адрес, привязанный к сокету на другом конце подключения.

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

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

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

socket.bind(address)

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

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

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

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

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

socket.connect_ex(address)

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

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

socket.detach()

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

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

socket.dup()

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

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

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

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 man getsockopt(2)). Необходимые символические константы (SO_* и т.д.) определены в этом модуле. Если buflen отсутствует, предполагается целочисленный параметр, и его целочисленное значение возвращается функцией. Если buflen присутствует, он задаёт максимальную длину буфера, используемого для получения параметра, и этот буфер возвращается как объект bytes. От вызывающей стороны требуется декодирование содержимого буфера (см. необязательный встроенный модуль struct для способа декодирования C-структур, закодированных как строки байтов).

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

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

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

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

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

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

Примечание

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

socket.recv(bufsize[, flags])

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

Примечание

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

Новое в версии 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, возможно, и другие.

Введено в версии 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, возможно, и другие.

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

Изменено в версии 3.5: Теперь принимается объект типа bytes-like object, поддерживающий запись.

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

socket.shutdown(how)

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

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