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

Исходный код: Lib/socket.py

Модуль обеспечивает доступ к интерфейсу socket BSD. Он доступен на всех современных Unix-системах, Windows, MacOS и, вероятно, дополнительных платформах.

Примечание

Некоторое поведение может зависеть от платформы, так как обращаются к сокетному API операционной системы.

Интерфейс Python - прямая транслитерация системного вызова Unix и интерфейса библиотеки для сокеты к объектно-ориентированному стилю Python’а: socket() функционируют возвращает объект socket, методы которого осуществляют различные системные вызовы socket. Типы параметров несколько выше, чем в интерфейсе C: как и при read() и write() операциях с файлами Python, выделение буфера при операциях получения происходит автоматически, а длина буфера неявно отражается при операциях отправки.

См.также

Module socketserver
Классы, упрощающие запись на сетевые серверы.
Модуль ssl
Обертка TLS/SSL для socket объектов.

Семейства 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, 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).

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

  • Строка или кортеж (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-битными целыми числами.

    Availability: Linux 2.6.38, some algorithm types require more recent Kernels.

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

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

    Availability: 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 - Необязательный байтоподобный объект, указывающий физическое оборудование адрес, интерпретация которого зависит от устройства.

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

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

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

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

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

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

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

Исключения

exception socket.error

Устаревший алиас OSError.

Изменено в версии 3.3: После PEP 3151 этот класс был сделан алиас OSError.

exception socket.herror

В подкласс OSError это исключение возникает для ошибок, связанных с адресом, т.е. для функций, использующих h_errno в POSIX C API, включая gethostbyname_ex() и gethostbyaddr(). Сопутствующий значение представляет собой пару (h_errno, string), представляющих ошибку, возвращенный вызовом библиотеки. h_errno является числовым значение, в то время как string представляет описание h_errno, как возвращенный функцией hstrerror() C.

Изменено в версии 3.3: Этот класс был сделан подклассом OSError.

exception socket.gaierror

В подклассе OSError это исключение возникает для ошибок, связанных с адресом, по getaddrinfo() и getnameinfo(). Сопутствующий значение представляет собой пару (error, string), представляющих ошибку, возвращенный вызовом библиотеки. string представляет описание error, возвращенный функцией gai_strerror() C. Числовая error значение будет соответствовать одной из констант EAI_*, определенных в этом модуле.

Изменено в версии 3.3: Этот класс был сделан подклассом OSError.

exception socket.timeout

В подкласс OSError это исключение возникает, когда тайм-аут возникает в сокет, у которого тайм-ауты активизированы посредством предыдущего вызова settimeout() (или неявно через setdefaulttimeout()). Сопроводительный значение - это строка, значение которого в настоящее время всегда «тайм-аут».

Изменено в версии 3.3: Этот класс был сделан подкласс OSError.

Константы

Константы AF_* and SOCK_* теперь являются коллекциями AddressFamily и SocketKind IntEnum.

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

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

Эти константы представляют семейства адресов (и протоколов), используемый для первого аргумента socket(). Если константа AF_UNIX не определена, этот протокол не поддерживается. В зависимости от системы может быть доступно больше констант.

socket.SOCK_STREAM
socket.SOCK_DGRAM
socket.SOCK_RAW
socket.SOCK_RDM
socket.SOCK_SEQPACKET

Эти константы представляют типы сокет, используемый для второго аргумента socket(). В зависимости от системы может быть доступно больше констант. (В целом полезны только SOCK_STREAM и SOCK_DGRAM.

socket.SOCK_CLOEXEC
socket.SOCK_NONBLOCK

Эти две константы, если они определены, могут быть объединены с типами сокет и позволяют устанавливать некоторые флаги атомарно (таким образом избегая возможных условий гонки и необходимости отдельных вызовов).

См.также

Безопасная обработка дескриптора файла для более подробного объяснения.

Availability: Linux >= 2.6.27.

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

SO_*
socket.SOMAXCONN
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*

Многие константы этих форм, задокументированные в документации Unix по сокеты и/или протоколу IP, также определены в модуле socket. Они обычно используемый в аргументах к setsockopt() и getsockopt() методам сокет объектов. В большинстве случаев определяются только те символы, которые определены в файлах заголовков Unix; для нескольких символов предусмотрены значения по умолчанию.

Изменено в версии 3.6: Были добавлены SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION.

Изменено в версии 3.6.5: В Windows TCP_FASTOPEN, TCP_KEEPCNT появляются, если Windows во время выполнения поддерживает.

Изменено в версии 3.7: TCP_NOTSENT_LOWAT было добавлено.

В Windows TCP_KEEPIDLE, TCP_KEEPINTVL появляются, если Windows во время выполнения поддерживает.

socket.AF_CAN
socket.PF_CAN
SOL_CAN_*
CAN_*

Многие константы этих форм, задокументированные в документации по Linux, также определены в модуле socket.

Availability: Linux >= 2.6.25.

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

socket.CAN_BCM
CAN_BCM_*

CAN_BCM, в семействе протоколов CAN, является протоколом менеджера широковещательной передачи (BCM). Константы широковещательного менеджера, задокументированные в документации по Linux, также определены в модуле socket.

Availability: Linux >= 2.6.25.

Примечание

Флаг CAN_BCM_CAN_FD_FRAME доступен только в Linux > = 4.8.

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

socket.CAN_RAW_FD_FRAMES

Включает поддержку CAN FD в CAN_RAW сокет. По умолчанию этот параметр отключен. Это позволяет приложению отправлять кадры CAN и CAN FD; однако при чтении из сокет необходимо принимать кадры CAN и CAN FD.

Эта константа задокументирована в документации по Linux.

Availability: Linux >= 3.6.

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

socket.CAN_ISOTP

CAN_ISOTP, в семействе протоколов CAN, является протоколом ISO-TP (ISO 15765-2). Константы ISO-TP, задокументированные в документации по Linux.

Availability: Linux >= 2.6.25.

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

socket.AF_PACKET
socket.PF_PACKET
PACKET_*

Многие константы этих форм, задокументированные в документации по Linux, также определены в модуле socket.

Availability: Linux >= 2.2.

socket.AF_RDS
socket.PF_RDS
socket.SOL_RDS
RDS_*

Многие константы этих форм, задокументированные в документации по Linux, также определены в модуле socket.

Availability: Linux >= 2.6.30.

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

socket.SIO_RCVALL
socket.SIO_KEEPALIVE_VALS
socket.SIO_LOOPBACK_FAST_PATH
RCVALL_*

Константы для WSAIoctl() Windows. Константы используемый в качестве аргументов метода ioctl() объектов socket.

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

TIPC_*

Связанные с TIPC константы, соответствующие константам, экспортированным C сокет API. Дополнительные сведения см. в документации TIPC.

socket.AF_ALG
socket.SOL_ALG
ALG_*

Константы для криптографии ядра Linux.

Availability: Linux >= 2.6.38.

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

socket.AF_VSOCK
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID
VMADDR*
SO_VM*

Константы для связи между хостом и гостем Linux.

Availability: Linux >= 4.8.

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

Availability: BSD, OSX.

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

socket.has_ipv6

Эта константа содержит логическое значение, указывающее, поддерживается ли IPv6 на данной платформе.

socket.BDADDR_ANY
socket.BDADDR_LOCAL

Это строка константы, содержащие адреса Bluetooth со специальными значениями. Например, BDADDR_ANY можно используемый для указания любого адреса при указании биндинга сокета с BTPROTO_RFCOMM.

socket.HCI_FILTER
socket.HCI_TIME_STAMP
socket.HCI_DATA_DIR

Для использования с BTPROTO_HCI. HCI_FILTER недоступна для NetBSD или DragonFlyBSD. HCI_TIME_STAMP и HCI_DATA_DIR недоступны для FreeBSD, NetBSD или DragonFlyBSD.

socket.AF_QIPCRTR

Константа для протокола IPC-маршрутизатора Qualcomm, используемый для связи с удаленными процессорами, предоставляющими услуги.

Availability: Linux >= 4.7.

Функции

Создание сокетов

Следующие функции создают объекты сокетов.

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.

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

Вновь созданный сокет является без наследования.

Raises an auditing event socket.__new__ with arguments 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.

socket.socketpair([family[, type[, proto]]])

Создать пару подключенных объектов сокет, используя заданное семейство адресов, тип сокет и номер протокола. Семейство адресов, тип сокет и номер протокола соответствуют функции socket(), описанной выше. Семейство по умолчанию AF_UNIX, если определено на платформе; в противном случае значение по умолчанию равно AF_INET.

Вновь созданные сокеты будут без наследования.

Изменено в версии 3.2: Теперь объекты возвращенный сокет поддерживают весь API сокета, а не подмножество.

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

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

socket.create_connection(address[, timeout[, source_address]])

Подключитесь к службе TCP, прослушивающей интернет - address (2-кортеж (host, port)), и возвращает объект сокет. Это функция более высокого уровня, чем socket.connect(): если host является нечисловым именем хоста, она попытается разрешить его как для AF_INET, так и для AF_INET6, а затем попытается подключиться ко всем возможным адресам по очереди, пока подключение не завершится успешно. Это упрощает запись клиентов, совместимых как с IPv4, так и с IPv6.

Передача необязательного параметра timeout установит тайм-аут на сокет сущность перед попыткой подключения. Если timeout не указан, возвращенный по getdefaulttimeout() значение глобального тайм-аута по умолчанию равно используемый.

Если этот параметр задан, source_address должен быть 2-кортежным (host, port), с которым сокет будет связываться как адрес источника перед подключением. Если хост или порт равны «или 0 соответственно, поведение ОС по умолчанию будет используемый.

Изменено в версии 3.2: source_address было добавлено.

socket.create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)

Функция удобства, которая создает TCP сокет, привязанный к address (2-кортежный (host, port)) и возвращает объект сокет.

family должны быть либо AF_INET, либо AF_INET6. backlog - размер очереди, передаваемый socket.listen(); при 0 выбран разумный значение по умолчанию. reuse_port определяет необходимость установки параметра SO_REUSEPORT сокет.

Если dualstack_ipv6 верно и платформа поддерживает его, сокет сможет принимать как IPv4, так и IPv6 соединения, в противном случае это вызовет ValueError. Предполагается, что большинство платформ POSIX и Windows поддерживают эту функциональность. Если эта функция включена, то адрес, возвращенный socket.getpeername() при подключении IPv4, будет IPv6 адресом, представленным как IPv4-mapped IPv6 адрес. Если dualstack_ipv6 имеет значение false, то эта функция будет явно отключена на платформах, которые включают ее по умолчанию (например, Linux). Этот параметр можно используемый совместно с has_dualstack_ipv6():

import socket

addr = ("", 8080)  # все интерфейсы, порт 8080
if socket.has_dualstack_ipv6():
    s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
    s = socket.create_server(addr)

Примечание

На платформах POSIX установлен параметр SO_REUSEADDR сокет для немедленного повторного использования предыдущих сокеты, которые были связаны на том же address и остались в TIME_WAIT состояние.

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

socket.has_dualstack_ipv6()

Возвращает True, поддерживает ли платформа создание TCP- сокет, который может обрабатывать как IPv4, так и IPv6 соединения.

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

socket.fromfd(fd, family, type, proto=0)

Скопировать дескриптор fd файла (целое число, возвращенный методом fileno() объекта файла) и создайте объект сокет из результата. Семейство адреса, тип сокет и число протокола что касается функции socket() выше. Файл дескриптор должен ссылаться на сокет, но это не проверяется, — последующие операции над объектом могут завершиться аварийно, если дескриптор файла недействителен. Эта функция редко требуется, но может быть используемый для получения или установки сокет параметров на сокет, переданном программе в качестве стандартного ввода или вывода (например, сервер, запущенный демоном Unix inet). Предполагается, что сокет находится в режиме блокировки.

Вновь созданный сокет является без наследуемого.

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

socket.fromshare(data)

Создание экземпляра сокет из данных, полученных с помощью метода socket.share(). Предполагается, что сокет находится в режиме блокировки.

Availability: Windows.

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

socket.SocketType

Объект типа Python, представляющий тип объекта socket. Это то же самое, что и type(socket(...)).

Другие функции

Модуль socket также предлагает различные услуги, связанные с сетью:

socket.close(fd)

Закрыть сокет файлового дескриптора. Это как os.close(), но для сокетов. На некоторых платформах (наиболее заметная Windows) os.close() не работает для сокет файловых дескрипторы.

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

socket.getaddrinfo(host, port, family=0, type=0, proto=0, flags=0)

Преобразование аргумента host/port в последовательность из 5 кортежей, содержащих все необходимые аргументы для создания сокет, связанных с этой службой. host - доменное имя, строка представление IPv4/v6 адреса или None. port - это строка имя службы, например 'http', числовой номер порта или None. Передавая None как значение host и port, можно передать NULL в базовый C API.

Аргументы family, type и proto можно указать дополнительно, чтобы сузить список возвращенный адресов. Передача нуля в качестве значение для каждого из этих аргументов выбирает полный диапазон результатов. Аргумент flags может быть одной или несколькими константами AI_* и будет влиять на вычисление и возвращенный результатов. Например, AI_NUMERICHOST отключит разрешение доменных имен и вызовет ошибку, если host является доменным именем.

Функция возвращает список 5-кортежей со следующей структурой:

(family, type, proto, canonname, sockaddr)

В этих кортежах, family, type, proto все целые числа и предназначены для передачи socket() функции. canonname будет строка, представляющим каноническое имя host, если AI_CANONNAME является частью аргумента flags; иначе canonname будет пустой. sockaddr представляет собой кортеж, описывающий сокет адрес, формат которого зависит от возвращенный family ((address, port) 2-кортеж для AF_INET, (address, port, flow info, scope id) 4-кортеж для AF_INET6), и предназначен для передачи в метод socket.connect().

Raises an auditing event socket.getaddrinfo with arguments host, port, family, type, protocol.

В следующем примере извлекается адресная информация для гипотетического TCP- соединения с example.org на порту 80 (результаты могут отличаться в системе, если IPv6 не включено):

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(<AddressFamily.AF_INET6: 10>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (<AddressFamily.AF_INET: 2>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('93.184.216.34', 80))]

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

Изменено в версии 3.7: для IPv6 многоадресных адресов строка, представляющие адрес, не будут содержать %scope часть.

socket.getfqdn([name])

Возвращает полное доменное имя для name. Если name пропущен или пуст, он интерпретируется как локальная хост. Чтобы найти полное имя, проверяется имя хоста, возвращенный gethostbyaddr(), а также псевдонимы хоста, если они доступны. Выбирается имя, включающее точку. Если полное доменное имя недоступно, имя узла, возвращенный gethostname(), будет возвращенный.

socket.gethostbyname(hostname)

Преобразование имени узла в формат IPv4 адреса. Адрес IPv4 возвращенный как строка, например '100.50.200.5'. Если имя хоста является IPv4 адресом, оно возвращенный остается неизменным. Более полный интерфейс см. в разделе gethostbyname_ex(). gethostbyname() не поддерживает разрешение IPv6 имен, и getaddrinfo() следует используемый вместо IPv4/v6 поддержки двойного стека.

Raises an auditing event socket.gethostbyname with argument hostname.

socket.gethostbyname_ex(hostname)

Преобразование имени хоста IPv4 формат адреса, расширенный интерфейс. Возвращает тройном (hostname, aliaslist, ipaddrlist), где hostname - основное имя хоста, отвечающее на заданный ip_address, aliaslist - (возможно, пустой) список альтернативных имен хостов для одного и того же адреса, а ipaddrlist - список IPv4 адресов для одного и того же интерфейса на одном и том же хосте (часто, но не всегда один адрес). gethostbyname_ex() не поддерживает разрешение IPv6 имен, и getaddrinfo() следует используемый вместо IPv4/v6 поддержки двойного стека.

Raises an auditing event socket.gethostbyname with argument hostname.

socket.gethostname()

Возвращает строку, содержащее имя хоста компьютера, на котором выполняется Python интерпретатор.

Raises an auditing event socket.gethostname with no arguments.

Примечание: gethostname() не всегда возвращает полное доменное имя; использовать для этого getfqdn().

socket.gethostbyaddr(ip_address)

Возвращает тройном (hostname, aliaslist, ipaddrlist), где hostname - основное имя хоста, отвечающее на заданный ip_address, aliaslist - (возможно, пустой) список альтернативных имен хостов для того же адреса, а ipaddrlist - список IPv4/v6 адресов для того же интерфейса на том же хосте (скорее всего, содержащий только один адрес). Чтобы найти полное доменное имя, используйте функцию getfqdn(). gethostbyaddr() поддерживает как IPv4, так и IPv6.

Raises an auditing event socket.gethostbyaddr with argument ip_address.

socket.getnameinfo(sockaddr, flags)

Перевести сокетный адрес sockaddr в 2-кортежный (host, port). В зависимости от настроек flags, результат может содержать полное доменное имя или числовое представление адреса в host. Аналогично, port может содержать строка имя порта или числовой номер порта.

Для IPv6 адресов %scope добавляется к части узла, если sockaddr содержит значимые scopeid. Обычно это происходит для многоадресных адресов.

Для получения дополнительной информации о flags можно обратиться к getnameinfo(3).

Raises an auditing event socket.getnameinfo with argument sockaddr.

socket.getprotobyname(protocolname)

Перевести имя протокола интернета (например, 'icmp') в константу, подходящую для передачи функции socket() в качестве третьего (необязательного) аргумента. Обычно это необходимо только для сокеты, открытых в «сыром» режиме (SOCK_RAW); для обычных режимов сокет правильный протокол выбирается автоматически, если протокол пропущен или равен нулю.

socket.getservbyname(servicename[, protocolname])

Преобразование имени службы интернета и имени протокола в номер порта для этой службы. Имя дополнительного протокола, если оно указано, должно быть 'tcp' или 'udp', в противном случае любой протокол будет совпадать.

Raises an auditing event socket.getservbyname with arguments servicename, protocolname.

socket.getservbyport(port[, protocolname])

Преобразование номера порта интернета и имени протокола в имя службы для этой службы. Имя дополнительного протокола, если оно указано, должно быть 'tcp' или 'udp', в противном случае любой протокол будет совпадать.

Raises an auditing event socket.getservbyport with arguments port, protocolname.

socket.ntohl(x)

Преобразование 32-разрядных положительных целых чисел из сети в порядок байтов узла. На машинах, где порядок байтов хоста совпадает с порядком байтов сети, это no-op; в противном случае он выполняет операцию 4-байтового свопинга.

socket.ntohs(x)

Преобразование 16-разрядных положительных целых чисел из сети в порядок байтов узла. На машинах, где порядок байтов хоста совпадает с порядком байтов сети, это no-op; в противном случае он выполняет двухбайтовую операцию подкачки.

Не рекомендуется, начиная с версии 3.7: В случае, если x не помещается в 16-битное беззнаковое целое число, но помещается в положительное C int, оно молча усекается до 16-битного беззнакового целого числа. Эта функция автоматического усечения устарела и вызовет исключение в будущих версиях Python.

socket.htonl(x)

Преобразование 32-разрядных положительных целых чисел с хоста в сетевой порядок байтов. На машинах, где порядок байтов хоста совпадает с порядком байтов сети, это no-op; в противном случае он выполняет операцию 4-байтового свопинга.

socket.htons(x)

Преобразование 16-разрядных положительных целых чисел с хоста в сетевой порядок байтов. На машинах, где порядок байтов хоста совпадает с порядком байтов сети, это no-op; в противном случае он выполняет двухбайтовую операцию подкачки.

Не рекомендуется, начиная с версии 3.7: В случае, если x не помещается в 16-битное беззнаковое целое число, но помещается в положительное C int, оно молча усекается до 16-битного беззнакового целого числа. Эта функция автоматического усечения устарела и вызовет исключение в будущих версиях Python.

socket.inet_aton(ip_string)

Преобразовать IPv4 адрес из четырехпозиционного формата строка (например, „123.45.67.89“) в 32-битный упакованный двоичный формат в виде байтового объекта длиной четыре символа. Это полезно при разговоре с программой, которая использует стандартную библиотеку C и нуждается в объектах тип struct in_addr, который является типом C для 32-битного упакованного двоичного возвращает этой функции.

inet_aton() также принимает строки с менее чем тремя точками; для получения более подробной информации см. inet(3) страницы руководства Unix.

Если IPv4 адрес строка, переданный этой функции, недействителен, OSError будет поднят. Обратите внимание, что именно то, что действительно, зависит от базовой реализации C inet_aton().

inet_aton() не поддерживает IPv6, и inet_pton() должен быть используемый вместо этого для двойной поддержки стека IPv4/v6.

socket.inet_ntoa(packed_ip)

Преобразовать упакованный адрес IPv4 32 битов (четыре байта байтоподобного объекта в длине) к ее стандартному пунктирно-квадрофоническому представлению строка (например, „123.45.67.89“). Это полезно при разговоре с программой, которая использует стандартную библиотеку C и нуждается в объектах типах struct in_addr, который является типом C для 32-битных упакованных двоичных данных, которые эта функция принимает в качестве аргумента.

Если байтовая последовательность, переданная этой функции, имеет длину не 4 байта, OSError будет увеличена. inet_ntoa() не поддерживает IPv6, и inet_ntop() должен быть используемый вместо этого для двойной поддержки стека IPv4/v6.

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

socket.inet_pton(address_family, ip_string)

Преобразование IP-адреса из формата строка семейства в упакованный двоичный формат. inet_pton() полезно, когда библиотека или сетевой протокол вызывает объект типа struct in_addr (аналогично inet_aton()) или struct in6_addr.

Поддерживаемые значения для address_family в настоящее время AF_INET и AF_INET6. Если IP-адрес строка ip_string недействителен, OSError будет поднят. Обратите внимание, что именно то, что действительно, зависит как от значение address_family, так и от базовой реализации inet_pton().

Availability: Unix (maybe not all platforms), Windows.

Изменено в версии 3.4: Добавлена поддержка Windows

socket.inet_ntop(address_family, packed_ip)

Преобразование упакованного IP-адреса (байтоподобный объект некоторого количества байтов) в стандартное, зависящее от семейства представление строка (например, '7.10.0.5' или '5aef:2b::8'). inet_ntop() полезно, когда библиотека или сетевой протокол возвращает объект типа struct in_addr (аналогично inet_ntoa()) или struct in6_addr.

Поддерживаемые значения для address_family в настоящее время AF_INET и AF_INET6. Если packed_ip объекта bytes имеет неправильную длину для указанного семейства адресов, ValueError будет увеличена. OSError возникает при возникновении ошибок при вызове inet_ntop().

Availability: Unix (maybe not all platforms), Windows.

Изменено в версии 3.4: Добавлена поддержка Windows

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

socket.CMSG_LEN(length)

Возвращает общую длину, без завершающего заполнения, вспомогательного элемента данных с соответствующими данными данного length. Этот значение часто может быть используемый как размер буфера для recvmsg(), чтобы принимать один элемент вспомогательных данных, но RFC 3542 требует, чтобы портативные приложения использовали CMSG_SPACE() и, таким образом, включают пространство для заполнения, даже когда элемент будет последним в буфере. Поднимает OverflowError, если length находится вне допустимого диапазона значения.

Availability: большинство платформ Unix, возможно, другие.

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

socket.CMSG_SPACE(length)

Возвращает размер буфера, необходимый recvmsg() для приема вспомогательного элемента данных с соответствующими данными данного length, вместе с любым завершающим дополнением. Буферное пространство, необходимое для приема нескольких элементов, представляет собой сумму CMSG_SPACE(), значения для связанных с ними длин данных. Поднимает OverflowError, если length находится вне допустимого диапазона значения.

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

Availability: большинство платформ Unix, возможно, другие.

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

socket.getdefaulttimeout()

Возвращает время ожидания по умолчанию в секундах (float) для новых объектов сокет. значение None указывает на отсутствие тайм-аута для новых объектов сокет. При первом импорте модуля сокет значением по умолчанию является None.

socket.setdefaulttimeout(timeout)

Установить время ожидания по умолчанию в секундах (float) для новых объектов сокет. При первом импорте модуля сокет значением по умолчанию является None. Возможные settimeout() и их значения см. в значения.

socket.sethostname(name)

Установить для имени хоста компьютера значение name. Это вызовет OSError, если у вас недостаточно прав.

Raises an auditing event socket.sethostname with argument name.

Availability: Unix.

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

socket.if_nameindex()

Возвращает список информации о сетевом интерфейсе (index int, name строка). OSError, если системный вызов завершается неуспешно.

Availability: Unix, Windows.

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

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

Примечание

В Windows сетевые интерфейсы имеют разные имена в разных контекстах (все имена являются примерами) :

  • UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}
  • имя: ethernet_32770
  • дружелюбное имя: vEthernet (nat)
  • описание: Hyper-V Virtual Ethernet Adapter

Эта функция возвращает имена второй формы из списка, в данном примере ethernet_32770.

socket.if_nametoindex(if_name)

Возвращает индексный номер сетевого интерфейса, соответствующий имени интерфейса. OSError, если интерфейс с указанным именем не существует.

Availability: Unix, Windows.

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

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

См.также

«Имя интерфейса» — имя, задокументированное в if_nameindex().

socket.if_indextoname(if_index)

Возвращает имя сетевого интерфейса, соответствующее индексному номеру интерфейса. OSError, если интерфейс с заданным индексом не существует.

Availability: Unix, Windows.

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

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

Объекты Socket

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

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

socket.accept()

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

Вновь созданный сокет является без наследуемого.

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

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

socket.bind(address)

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

Raises an auditing event socket.bind with arguments self, address.

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

Raises an auditing event socket.connect with arguments self, address.

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

socket.connect_ex(address)

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

Raises an auditing event socket.connect with arguments 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 присутствует, он указывает максимальную длину буфера, используемый для получения опции в, и этот буфер возвращенный как байтовый объект. Именно вызывающий абонент должен декодировать содержимое буфера (способ декодирования структур C, кодированный как байт строки, см. в дополнительном встроенном модуле struct).

socket.getblocking()

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

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

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

socket.gettimeout()

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

socket.ioctl(control, option)
Platform: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])

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

Примечание

Для наилучшего соответствия аппаратным и сетевым реалиям значение bufsize должна быть относительно небольшой мощностью 2, например 4096.

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

socket.recvfrom(bufsize[, flags])

Получение данных из сокета. Возвращает значение является парой (bytes, address) где bytes является байтовым объектом, представляющим полученные данные, и address является адресом сокет, посылающего данные. Значение необязательного аргумента recv(2) см. на странице flags руководства Unix; значение по умолчанию равно нулю. (Формат 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, представляющим новый файл дескрипторы как двоичный массив собственного типа C int. Если recvmsg() вызывает исключение после возвращает системного вызова, сначала будет предпринята попытка закрыть любой дескрипторы файла, полученный с помощью этого механизма.

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

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

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Массив int
    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:
            # Добавление данных, игнорирование усеченных целых чисел в конце.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Availability: большинство платформ Unix, возможно, другие.

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

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

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

Получить нормальные данные и вспомогательные данные от сокет, ведя себя так, как recvmsg() бы, но разбрасывайте не вспомогательные данные в ряд буферов вместо того, чтобы возвращать новый объект байтов. Аргумент 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---')]

Availability: большинство платформ Unix, возможно, другие.

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

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

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

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

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

socket.send(bytes[, flags])

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

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

socket.sendall(bytes[, flags])

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

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

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

socket.sendto(bytes, address)
socket.sendto(bytes, flags, address)

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

Raises an auditing event socket.sendto with arguments 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))])

Availability: большинство платформ Unix, возможно, другие.

Raises an auditing event socket.sendmsg with arguments self, address.

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

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

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

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

Availability: 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 сокет переводится в режим блокировки.

Дополнительную информацию можно получить в notes on socket timeouts.

Изменено в версии 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 или байтоподобный объект, представляющим буфер. В более позднем случае вызывающий абонент должен убедиться, что bytestring содержит соответствующие биты (способ кодирования структур C как bytestrings см. в дополнительном встроенном модуле struct). Если для 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(). После вызова этого метода безопасно закрыть сокет, поскольку операционная система уже дублировала его для целевого процесса.

Availability: Windows.

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

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

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

socket.family

Семья сокетов.

socket.type

Тип сокета.

socket.proto

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

Заметки о тайм-аутах сокета

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

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

Примечание

На уровне операционной системы сокеты в режим тайм-аута устанавливаются в неблокирующем режиме. Кроме того, режимы блокировки и тайм-аута совместно используются файловыми дескрипторы и сокет объектами, которые относятся к одной и той же конечной точке сети. Эта подробная информация о внедрении может иметь видимые последствия, если, например, вы решите использовать fileno() сокет.

Тайм-ауты и метод connect

Операция connect() также зависит от установки тайм-аута, и, как правило, рекомендуется вызывать settimeout() перед вызовом connect() или передавать create_connection() параметр тайм-аута. Однако системная стек сети может также возвращает собственная ошибка перерыва связи независимо от любой настройки таймаута Python сокета.

Тайм-ауты и метод accept

Если getdefaulttimeout() не None, сокеты возвращенный методом accept() наследуют тот перерыв. В противном случае поведение зависит от настроек сокет: прослушивания

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

Пример

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

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

# Программа эхо-сервера
import socket

HOST = ''                 # Символическое имя, означающее все доступные интерфейсы
PORT = 50007              # Произвольный непривилегированный порт
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)

# Программа эхо-клиента
import socket

HOST = 'daring.cwi.nl'    # Удаленный узел
PORT = 50007              # Тот же порт, что и используемый сервером
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-ready систем IPv6 будет иметь приоритет, и сервер может не принимать IPv4 трафик. Клиентская сторона попытается подключиться ко всем адресам, возвращенный в результате разрешения имен, и отправит трафик на первый успешно подключенный.:

# Программа эхо-сервера
import socket
import sys

HOST = None               # Символическое имя, означающее все доступные интерфейсы
PORT = 50007              # Произвольный непривилегированный порт
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)

# Программа эхо-клиента
import socket
import sys

HOST = 'daring.cwi.nl'    # Удаленный узел
PORT = 50007              # Тот же порт, что и используемый сервером
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

# публичный сетевой интерфейс
HOST = socket.gethostbyname(socket.gethostname())

# создайте необработанный сокет и свяжите его с публичным интерфейсом
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Включить заголовки IP
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# получать все пакеты
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# получить пакет
print(s.recvfrom(65565))

# отключение неразборчивого режима
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 (см. «struct can_frame» в <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])


# создать необработанный сокет и привязать его к интерфейсу 'vcan0'
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 состояние, не дожидаясь истечения его естественного тайм-аута.

См.также

Введение в socket программирование (на языке C) см. в следующих документах:

  • Вводное учебное пособие по межпроцессному взаимодействию 4.3BSD, Stuart Sechrest
  • Расширенное руководство по межпроцессному взаимодействию 4.3BSD, Samuel J. Leffler и другие,

оба в руководстве программиста UNIX, дополнительные документы 1 (разделы PS1:7 и PS1: 8). Специфичный для платформы справочный материал для различных вызовов системы сокет-связанные также является ценным источником информации о деталях семантики сокет. Для Unix см. страницы руководства; для Windows см. спецификацию WinSock (или Winsock 2). Для IPv6-готовых API читатели могут хотеть обратиться к названным основным расширениям интерфейса сокета RFC 3493 для IPv6.