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).

• Поддержка 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.

• Для семейства адресов 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[, cid[, bdaddr_type]]), где:

    • bdaddr — строка, задающая адрес Bluetooth.
    • psm — целое число, задающее мультиплексор протокола/службы.
    • cid — необязательное целое число, задающее идентификатор канала. Если оно не указано, по умолчанию используется ноль.
    • bdaddr_type — необязательное целое число, задающее тип адреса; одно из значений BDADDR_BREDR (по умолчанию), BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM.

    Изменено в версии 3.14: Добавлены поля cid и bdaddr_type.

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

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

    • В Linux принимается целое число device_id или кортеж (device_id, [channel]), где device_id задаёт номер устройства Bluetooth, а channel — необязательное целое число, задающее канал HCI (по умолчанию — HCI_CHANNEL_RAW).
    • В FreeBSD, NetBSD и DragonFly BSD принимается bdaddr, где bdaddr — адрес Bluetooth в виде строки.

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

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

    Изменено в версии 3.14: Добавлено поле channel. Теперь принимается device_id, не упакованное в кортеж.

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

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

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

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

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

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

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

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

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

  См. vsock(7)

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

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

  • ifname — строка с именем устройства.
  • proto — номер протокола Ethernet. Для перехвата всех протоколов можно указать ETH_P_ALL, одну из констант ETHERTYPE_* или любой другой номер протокола Ethernet.

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

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

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

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

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

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

• IPPROTO_UDPLITE — это вариант UDP, позволяющий указать, какая часть пакета включается в контрольную сумму. Он добавляет два параметра сокета, которые можно изменять. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) меняет часть исходящих пакетов, включаемую в контрольную сумму, а self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) отфильтровывает пакеты, в которых в контрольную сумму включена слишком малая часть данных. В обоих случаях length должен находиться в диапазоне range(8, 2**16, 8).

  Такой сокет следует создавать с помощью socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv4 или socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv6.

  Доступность: Linux >= 2.6.20, FreeBSD >= 10.1

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

• AF_HYPERV — доступный только в Windows интерфейс на основе сокетов для связи с хостами и гостевыми системами Hyper-V. Семейство адресов представлено кортежем (vm_id, service_id), где vm_id и service_id — строки UUID.

  vm_id — это идентификатор виртуальной машины или одно из известных значений VMID, если целевая система не является конкретной виртуальной машиной. Известные константы VMID, определённые в socket:

  • HV_GUID_ZERO
  • HV_GUID_BROADCAST
  • HV_GUID_WILDCARD — используется для привязки к себе и принятия подключений от всех разделов.
  • HV_GUID_CHILDREN — используется для привязки к себе и принятия подключений от дочерних разделов.
  • HV_GUID_LOOPBACK — используется как цель для подключения к себе.
  • HV_GUID_PARENT — при использовании для привязки принимает подключение от родительского раздела. При использовании в качестве адреса назначения подключается к родительскому разделу.

  service_id — это идентификатор зарегистрированной службы.

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

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

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

Неблокирующий режим поддерживается с помощью setblocking(). Более общий вариант на основе тайм-аутов поддерживается с помощью settimeout().

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

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

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

class socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

Создаёт новый сокет, используя заданные семейство адресов, тип сокета и номер протокола. Семейство адресов должно быть AF_INET (по умолчанию), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET или AF_RDS. Тип сокета должен быть SOCK_STREAM (по умолчанию), SOCK_DGRAM, SOCK_RAW или, возможно, одной из других констант SOCK_. Номер протокола обычно равен нулю, поэтому его можно не указывать; в случае, когда семейство адресов — AF_CAN, протоколом должен быть один из CAN_RAW, CAN_BCM, CAN_ISOTP или CAN_J1939.

Если указан fileno, значения family, type и proto автоматически определяются по указанному файловому дескриптору. Автоматическое определение можно переопределить, вызвав функцию с явными аргументами family, type или proto. Это влияет только на представление данных в Python, например на возвращаемое значение socket.getpeername(), но не на сам ресурс ОС. В отличие от socket.fromfd(), fileno возвращает тот же сокет, а не его дубликат. Это может помочь закрыть отсоединённый сокет с помощью socket.close().

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

Вызывает событие аудита socket.__new__ с аргументами self, family, type, protocol.

Изменено в версии 3.3: Добавлено семейство AF_CAN. Добавлено семейство AF_RDS.

Изменено в версии 3.4: Добавлен протокол CAN_BCM.

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

Изменено в версии 3.7: Добавлен протокол CAN_ISOTP.

Изменено в версии 3.7: Если к type применяются битовые флаги SOCK_NONBLOCK или SOCK_CLOEXEC, они сбрасываются, и socket.type их не отражает. При этом они по-прежнему передаются нижележащему системному вызову socket(). Поэтому

sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

по-прежнему создаст неблокирующий сокет в ОС, поддерживающих SOCK_NONBLOCK, но sock.type будет установлено в socket.SOCK_STREAM.

Изменено в версии 3.9: Добавлен протокол CAN_J1939.

Изменено в версии 3.10: Добавлен протокол IPPROTO_MPTCP.

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

Изменено в версии 3.2: Добавлена поддержка протокола менеджера контекста. Выход из менеджера контекста равносилен вызову close().

accept()

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

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

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

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

bind(address)

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

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

Доступность: недоступно в WASI.

close()

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

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

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

Примечание

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

connect(address)

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

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

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

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

Доступность: недоступно в WASI.

connect_ex(address)

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

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

Доступность: недоступно в WASI.

detach()

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

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

dup()

Создаёт копию сокета.

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

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

Доступность: недоступно в WASI.

fileno()

Возвращает файловый дескриптор сокета (небольшое целое число) или -1 в случае сбоя. Это полезно при использовании с select.select().

В Windows небольшое целое число, возвращаемое этим методом, нельзя использовать там, где допустим файловый дескриптор (например, в os.fdopen()). В Unix такого ограничения нет.

get_inheritable()

Возвращает флаг наследования файлового дескриптора или дескриптора сокета: True, если сокет может наследоваться дочерними процессами, и False, если не может.

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

getpeername()

Возвращает удалённый адрес, к которому подключён сокет. Например, это полезно, чтобы узнать номер порта удалённого сокета IPv4/v6. Формат возвращаемого адреса зависит от семейства адресов — см. Семейства сокетов. В некоторых системах эта функция не поддерживается.

getsockname()

Возвращает собственный адрес сокета. Например, это полезно, чтобы узнать номер порта сокета IPv4/v6. Формат возвращаемого адреса зависит от семейства адресов — см. Семейства сокетов.

getsockopt(level, optname[, buflen])

Возвращает значение заданной опции сокета (см. страницу руководства Unix getsockopt(2)). Необходимые символьные константы (SO_* и т. д.) определены в этом модуле. Если buflen не задан, предполагается, что опция целочисленная, и функция возвращает её целочисленное значение. Если buflen задан, он указывает максимальную длину буфера, используемого для получения опции; этот буфер возвращается как объект bytes. Вызывающий код должен самостоятельно декодировать содержимое буфера (способ декодирования структур C, закодированных в виде байтовых строк, см. в необязательном встроенном модуле struct).

Доступность: недоступно в WASI.

getblocking()

Возвращает True, если сокет работает в блокирующем режиме, и False, если в неблокирующем.

Это эквивалентно проверке socket.gettimeout() != 0.

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

gettimeout()

Возвращает тайм-аут в секундах (число с плавающей точкой), установленный для операций с сокетом, или None, если тайм-аут не задан. Значение соответствует последнему вызову setblocking() или settimeout().

ioctl(control, option)

Метод ioctl() предоставляет ограниченный интерфейс к системному интерфейсу WSAIoctl. Дополнительную информацию см. в документации Win32.

На других платформах можно использовать универсальные функции fcntl.fcntl() и fcntl.ioctl(); они принимают объект сокета в качестве первого аргумента.

В настоящее время поддерживаются только следующие управляющие коды: SIO_RCVALL, SIO_KEEPALIVE_VALS и SIO_LOOPBACK_FAST_PATH.

Доступность: Windows

Изменено в версии 3.6: Добавлен SIO_LOOPBACK_FAST_PATH.

listen([backlog])

Позволяет серверу принимать соединения. Если указан backlog, он должен быть не меньше 0 (если значение меньше, оно устанавливается равным 0); он задаёт количество непринятых соединений, которое система допускает до отказа принимать новые соединения. Если значение не указано, выбирается разумное значение по умолчанию.

Доступность: недоступно в WASI.

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

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

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

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

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

Примечание

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

recv(bufsize[, flags])

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

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

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().

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).

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.

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

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

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

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

send(bytes[, flags])

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

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

sendall(bytes[, flags])

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

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

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

sendto(bytes, address)

sendto(bytes, flags, address)

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

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

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

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).

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

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

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

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

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

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

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

set_inheritable(inheritable)

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

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

setblocking(flag)

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

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

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

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

settimeout(value)

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

Дополнительные сведения см. в примечаниях о тайм-аутах сокетов.

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

setsockopt(level, optname, value: int | Buffer)

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.

shutdown(how)

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

Доступность: кроме WASI.

share(process_id)

Создаёт копию сокета и подготавливает её для совместного использования с целевым процессом. Необходимо указать process_id целевого процесса. Полученный объект bytes можно передать целевому процессу с помощью какого-либо механизма межпроцессного взаимодействия, а затем воссоздать там сокет с помощью fromshare(). После вызова этого метода сокет можно безопасно закрыть, поскольку операционная система уже создала его копию для целевого процесса.

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

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

Обратите внимание, что методов read() и write() нет; вместо них используйте recv() и send() без аргумента flags.

У объектов socket также есть следующие атрибуты (только для чтения), соответствующие значениям, переданным конструктору socket.

family

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

type

Тип сокета.

proto

Протокол сокета.

class socket.SocketType

Базовый класс типа socket, повторно экспортируемый из _socket. Проверка экземпляра, например isinstance(socket(...), SocketType), возвращает true, но SocketType — не то же самое, что type(socket(...)), которым является сам socket.

Примечания о тайм-аутах сокетов

Объект socket может находиться в одном из трёх режимов: блокирующем, неблокирующем или с тайм-аутом. По умолчанию сокеты всегда создаются в блокирующем режиме, но это можно изменить, вызвав setdefaulttimeout().

• В блокирующем режиме операции блокируются до завершения или до возврата системой ошибки (например, тайм-аута соединения).
• В неблокирующем режиме операции завершаются с ошибкой (которая, к сожалению, зависит от системы), если их нельзя выполнить немедленно: функции модуля select можно использовать, чтобы узнать, доступен ли сокет для чтения или записи и когда именно.
• В режиме с тайм-аутом операции завершаются с ошибкой, если их нельзя выполнить в течение указанного для сокета тайм-аута (вызывается исключение timeout) или если система возвращает ошибку.

Пример

Ниже приведены четыре минимальных примера программ, использующих протокол TCP/IP: сервер, который возвращает все полученные данные (обслуживая только одного клиента), и клиент, использующий этот сервер. Обратите внимание: сервер должен выполнить последовательность socket(), bind(), listen(), accept() (возможно, повторяя accept() для обслуживания нескольких клиентов), тогда как клиенту достаточно последовательности socket(), connect(). Также обратите внимание: сервер вызывает sendall()/recv() не для слушающего сокета, а для нового сокета, возвращённого accept().

Первые два примера поддерживают только IPv4.

# Echo server program
import socket

HOST = ''                 # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

Следующие два примера идентичны предыдущим, но поддерживают как IPv4, так и IPv6. Сервер будет слушать адрес первого доступного семейства адресов (вместо этого ему следовало бы слушать оба). В большинстве систем с поддержкой IPv6 приоритет будет у IPv6, поэтому сервер может не принимать трафик IPv4. Клиент попытается подключиться ко всем адресам, полученным в результате разрешения имени, и отправит трафик по первому адресу, с которым удалось установить соединение.

# Echo server program
import socket
import sys

HOST = None               # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)

# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

В следующем примере показано, как написать очень простой сетевой анализатор с использованием raw-сокетов в Windows. Для изменения интерфейса примеру требуются права администратора:

import socket

# the public network interface
HOST = socket.gethostbyname(socket.gethostname())

# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# receive all packets
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a packet
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

В следующем примере показано, как использовать интерфейс сокетов для взаимодействия с сетью CAN с помощью протокола raw-сокетов. Чтобы вместо этого использовать CAN с протоколом диспетчера широковещательной рассылки, откройте сокет следующим образом:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

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