socket — Интерфейс низкого уровня для сетевых соединений

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

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

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

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

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

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

• Для семейства адресов 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, scopeid), где flowinfo и scopeid представляют члены sin6_flowinfo и sin6_scope_id в struct sockaddr_in6 на C. Для методов модуля socket, flowinfo и scopeid могут быть опущены только для обратной совместимости. Однако следует учитывать, что пропуск scopeid может привести к проблемам при манипулировании адресами IPv6 с областью действия.

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

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

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

  • addr_type — это одно из значений TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, или TIPC_ADDR_ID.
  • scope — это одно из значений TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, и TIPC_NODE_SCOPE.

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

    Если addr_type — это TIPC_ADDR_NAMESEQ, то v1 — тип сервера, v2 — нижний номер порта, а v3 — верхний номер порта.

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

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

  • Протокол CAN_ISOTP требует кортеж (interface, rx_addr, tx_addr), где оба дополнительных параметра — целые числа без знака, представляющие идентификатор CAN (стандартный или расширенный).

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

  Новое в версии 3.3.

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

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

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

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

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

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

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

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

  Новое в версии 3.6.

• AF_VSOCK позволяет обмениваться данными между виртуальными машинами и их хостами. Сокеты представлены кортежем (CID, port), где идентификатор контекста или 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, определяющий физический аппаратный адрес, чья интерпретация зависит от устройства.

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

  Новое в версии 3.8.

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

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

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

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

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

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

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

socket.accept()

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

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

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

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

socket.bind(address)

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

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

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

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

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

socket.connect_ex(address)

Как connect(address), но возвращает индикатор ошибки вместо повышения исключения для ошибок, возвращаемых вызовом C-уровня 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 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 первый элемент address больше не содержит %scope часть. Для получения полного адреса 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-платформ, возможно, и другие.

Новая в версии 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 — объект типа 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, возможно, и другие.

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

Введено в версии 3.3.

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

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

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

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

Введено в версии 3.6.

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

Отправить файл до достижения конца файла, используя высокопроизводительный метод os.sendfile, и вернуть общее количество отправленных байтов. file должен быть объектом файла, открытым в двоичном режиме. Если os.sendfile недоступен (например, в Windows) или file не является обычным файлом, будет использоваться send(). offset указывает, с какой позиции начать чтение файла. Если указано, count — это общее количество байтов для передачи вместо отправки файла до конца. Положение файла обновляется при возврате или в случае ошибки, в этом случае file.tell() можно использовать для определения количества отправленных байтов. Сокет должен быть типа SOCK_STREAM. Неблокирующие сокеты не поддерживаются.

Новая в версии 3.5.

socket.set_inheritable(inheritable)

Установить флаг наследуемости для дескриптора файла сокета или дескриптора сокета.

Новая в версии 3.4.

socket.setblocking(flag)

Установить режим блокировки или неблокирующего режима для сокета: если flag ложно, сокет устанавливается в неблокирующий режим, иначе в блокирующий режим.

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

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

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

socket.settimeout(value)

Установить таймаут для блокирующих операций с сокетом. Аргумент value может быть неотрицательным числом с плавающей точкой, представляющим секунды, или None. Если задано ненулевое значение, последующие операции с сокетом приведут к исключению timeout, если истечёт период таймаута value до завершения операции. Если задано ноль, сокет переводится в неблокирующий режим. Если задано None, сокет переводится в блокирующий режим.

Для получения дополнительной информации, пожалуйста, обратитесь к примечаниям по таймаутам сокетов.

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

socket.setsockopt(level, optname, value: int)

socket.setsockopt(level, optname, value: buffer)

socket.setsockopt(level, optname, None, optlen: int)

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

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

Изменено в версии 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. Полученный объект байтов может быть передан целевому процессу с помощью некоторого вида межпроцессного взаимодействия, и сокет может быть там воссоздан с помощью 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 packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

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