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

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

Примечание

Незначительное отличие в поведении может зависеть от платформы, поскольку выполняются вызовы API-интерфейсов сокетов ОС.

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

См.также

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

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

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

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

Адрес сокета 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. Строка — это имя элемента управления ядра с динамически назначаемым ID. Кортеж можно использовать, если известны ID и номер модуля элемента управления ядра или если используется зарегистрированный ID.

Добавлено в версии 3.3.
AF_BLUETOOTH поддерживает следующие протоколы и форматы адресов:
- BTPROTO_L2CAP принимает (bdaddr, psm), где bdaddr — это адрес Bluetooth в виде строки, а psm — целое число.
- BTPROTO_RFCOMM принимает (bdaddr, channel), где bdaddr — адрес Bluetooth в виде строки, а channel — целое число.
- BTPROTO_HCI принимает (device_id,), где device_id — целое число или строка с адресом Bluetooth интерфейса. (Это зависит от вашей ОС; NetBSD и DragonFlyBSD ожидают адрес Bluetooth, а все остальное — целое число.)
  
  Изменено в версии 3.2: Добавлена поддержка NetBSD и DragonFlyBSD.
- BTPROTO_SCO принимает bdaddr, где bdaddr — объект bytes, содержащий адрес Bluetooth в строковом формате. (Например, b'12:23:34:45:56:67') Данный протокол не поддерживается FreeBSD.
AF_ALG — интерфейс на основе сокетов только для Linux для криптографии ядра. Алгоритм сокета сконфигурирован с кортежем из двух-четырёх элементов (type, name [, feat [, mask]]), где:
- type — тип алгоритма в виде строки, например aead, hash, skcipher или rng.
- name — имя алгоритма и режим работы в виде строки, например sha256, hmac(sha256), cbc(aes) или drbg_nopr_ctr_aes256.
- feat и mask — 32-битные целые числа без знака.
Доступность: В Linux 2.6.38 для некоторых типов алгоритмов требуются более свежие ядра.

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

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

Добавлено в версии 3.7.
AF_PACKET — низкоуровневый интерфейс напрямую к сетевым устройствам. Пакеты представлены кортежем (ifname, proto[, pkttype[, hatype[, addr]]]), где:
- ifname — строка, определяющая имя устройства.
- proto — целое число в сетевом байтовом порядке, определяющее номер протокола Ethernet.
- pkttype — необязательное целое число, указывающее тип пакета:
  - PACKET_HOST (по умолчанию) — пакет адресован локальному хосту.
  - PACKET_BROADCAST — широковещательный пакет физического уровня.
  - PACKET_MULTIHOST — пакет отправлен на групповой адрес физического уровня.
  - PACKET_OTHERHOST — пакет для другого хоста, который был перехвачен драйвером устройства в неразборчивом режиме.
  - PACKET_OUTGOING — пакет, исходящий от локального хоста, возвращается в пакетный сокет.
- hatype — необязательное целое число, указывающее тип аппаратного адреса ARP.
- addr — необязательный байтовый объект, определяющий физическое устройство оборудования, интерпретация которого зависит от устройства.
AF_QIPCRTR — интерфейс на основе сокетов только для Linux для связи со службами, работающими на сопроцессорах на платформах Qualcomm. Семейство адресов представлено как кортеж (node, port), в котором node и port являются неотрицательными целыми числами.

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

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

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

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

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

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

Исключения

exception socket.error: Устаревший псевдоним OSError.

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

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

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

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

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

exception socket.timeout: Подкласс OSError, это исключение возникает, когда тайм-аут происходит в сокете, для которого были включены тайм-ауты посредством предыдущего вызова settimeout() (или неявно через setdefaulttimeout()). Сопутствующее значение представляет собой строку, значение которой в настоящее время всегда «истекло».

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

Константы

Константы AF_* и 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

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

См.также

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

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

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

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

socket.CAN_BCM

CAN_BCM_*

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

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

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

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

socket.CAN_ISOTP

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

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

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

socket.AF_PACKET

socket.PF_PACKET

PACKET_*

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

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

socket.AF_RDS

socket.PF_RDS

socket.SOL_RDS

RDS_*

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

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

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

socket.SIO_RCVALL
socket.SIO_KEEPALIVE_VALS
socket.SIO_LOOPBACK_FAST_PATH
RCVALL_*: Константы для Windows WSAIoctl(). Константы используются в качестве аргументов метода ioctl() для объектов сокета.

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

TIPC_*: Константы, связанные с TIPC, совпадающие с константами, экспортируемыми API- интерфейсом C. См. документацию TIPC для получения дополнительной информации.

socket.AF_ALG

socket.SOL_ALG

ALG_*

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

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

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

socket.AF_VSOCK

socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

VMADDR*

SO_VM*

Константы для связи хоста/гостя Linux.

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

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

socket.AF_LINK: Доступность: 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, используемая для связи с удаленными процессорами, предоставляющими услуги.

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

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

Вызывает событие аудита 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.

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 должен быть двухкортежным (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, представленным как IPv6-адрес с отображением IPv4. Если для dualstack_ipv6 установлено ложное значение, функция будет явно отключена на платформах, которые включают её по умолчанию (например, 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() выше. Дескриптор файла должен ссылаться на сокет, но это не проверяется — последующие операции над объектом могут завершиться неудачно, если дескриптор файла недействителен. Данная функция редко требуется, но может использоваться для получения или установки параметров сокета для сокета, передаваемого программе в качестве стандартного ввода или вывода (например, сервера, запущенного демоном inet Unix). Предполагается, что сокет находится в режиме блокировки.

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

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

socket.fromshare(data)

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

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

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

socket.SocketType: Объект типа Python, представляющий тип объекта сокета. То же самое, что и 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 базовому API C.

Аргументы 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 (2-кортеж (address, port) для AF_INET, 4-кортеж (address, port, flow info, scope id) для AF_INET6) и предназначен для передачи методу socket.connect().

Вызывает событие аудита socket.getaddrinfo с аргументами 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.

Вызывает событие аудита socket.gethostbyname с аргументом hostname.

socket.gethostbyname_ex(hostname)

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

Вызывает событие аудита socket.gethostbyname с аргументом hostname.

socket.gethostname()

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

Вызывает событие аудита socket.gethostname без аргументов.

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

socket.gethostbyaddr(ip_address)

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

Вызывает событие аудита socket.gethostbyaddr с аргументом ip_address.

socket.getnameinfo(sockaddr, flags)

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

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

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

Вызывает событие аудита socket.getnameinfo с аргументом sockaddr.

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

socket.getservbyname(servicename[, protocolname])

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

Вызывает событие аудита socket.getservbyname с аргументами servicename, protocolname.

socket.getservbyport(port[, protocolname])

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

Вызывает событие аудита socket.getservbyport с аргументами port, protocolname.

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

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

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

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

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

Не рекомендуется, начиная с версии 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() также принимает строки с менее чем тремя точками; подробности см. на странице руководства Unix inet(3).

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

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

socket.inet_ntoa(packed_ip)

Преобразовывает 32-битный упакованный IPv4-адрес (байтоподобный объект длиной четыре байта) в его стандартное строковое представление с разделением на четыре точки (например, «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().

Доступность: Unix (возможно, не все платформы), 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 неправильная длина для указанного семейства адресов, будет выдан код ValueError. OSError возникает при ошибках при обращении к inet_ntop().

Доступность: Unix (возможно, не все платформы), Windows.

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

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

socket.CMSG_LEN(length)

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

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

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

socket.CMSG_SPACE(length)

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

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

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

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

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

socket.setdefaulttimeout(timeout): Устанавливает тайм-аут по умолчанию в секундах (с плавающей запятой) для новых объектов сокета. При первом импорте модуля сокета значение по умолчанию — None. См. settimeout() для получения информации о возможных значениях и их соответствующих значениях.

socket.sethostname(name)

Устанавливает name хоста машины. Вызовет OSError, если у вас недостаточно прав.

Вызывает событие аудита socket.sethostname с аргументом name.

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

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

socket.if_nameindex()

Возвращает список кортежей с информацией о сетевом интерфейсе (индекс int, строка имени). OSError в случае сбоя системного вызова.

Доступность: 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, если интерфейс с данным именем не существует.

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

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

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

См.также

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

socket.if_indextoname(if_index)

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

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

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

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

См.также

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

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

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

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

socket.accept()

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

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

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

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

socket.bind(address)

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

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

socket.close()

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

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

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

Примечание

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

socket.connect(address)

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

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

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

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

socket.connect_ex(address)

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

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

socket.detach(): Переводит объект сокета в закрытое состояние, не закрывая дескриптор файла. Возвращается файловый дескриптор, который может повторно использоваться для других целей.

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

socket.dup()

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

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

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

socket.fileno()

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

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

socket.get_inheritable(): Получить наследуемый флаг дескриптора файла сокета или дескриптора сокета: True, если сокет может унаследоваться в дочерних процессах, False, если это невозможно.

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

socket.getpeername(): Возвращает удалённый адрес, к которому подключён сокет. Полезно, например, для определения номера порта удаленного сокета IPv4/v6. (Формат возвращаемого адреса зависит от семейства адресов, см. выше.) В некоторых системах функция не поддерживается.

socket.getsockname(): Возвращает собственный адрес сокета. Полезно, например, для определения номера порта сокета IPv4/v6. (Формат возвращаемого адреса зависит от семейства адресов, см. выше.)

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

socket.getblocking()

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

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

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

socket.gettimeout(): Возвращает тайм-аут в секундах (с плавающей запятой), связанный с операциями сокета, или 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. См. страницу руководства Unix recv(2) для получения информации о значениях необязательных аргументов flags; по умолчанию он равен нулю.

Примечание

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

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

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

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

Изменено в версии 3.7: Для многоадресного IPv6-адреса первый элемент address больше не содержит части %scope. Чтобы получить полный IPv6-адрес, используйте getnameinfo().

socket.recvmsg(bufsize[, ancbufsize[, flags]])

Получает обычные данные (до bufsize байтов) и вспомогательные данные из сокета. Аргумент ancbufsize устанавливает размер в байтах внутреннего буфера, используемого для приема вспомогательных данных; по умолчанию он равен 0, что означает, что никакие вспомогательные данные не будут получены. Соответствующие размеры буфера для вспомогательных данных могут быть рассчитаны с использованием CMSG_SPACE() или CMSG_LEN(), а элементы, которые не помещаются в буфер, могут быть усечены или отброшены. Аргумент flags по умолчанию равен 0 и содержит то же значение, что и для recv().

Возвращаемое значение — 4-кортеж: (data, ancdata, msg_flags, address). Элементом data является объект bytes, содержащий полученные не вспомогательные данные. Элемент ancdata представляет собой список из нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), представляющих полученные вспомогательные данные (управляющие сообщения): cmsg_level и cmsg_type — целые числа, определяющие уровень протокола и тип, зависящий от протокола, соответственно, а cmsg_data — объект bytes, содержащий связанные данные. Элемент msg_flags представляет собой поразрядное ИЛИ различных флагов, указывающих условия в полученном сообщении; подробности см. в документации к вашей системе. Если принимающий сокет не подключён, address является адресом отправляющего сокета, если он доступен; в противном случае его значение не указано.

В некоторых системах sendmsg() и recvmsg() можно использовать для передачи файловых дескрипторов между процессами через сокет AF_UNIX. Когда используется данная возможность (она часто ограничивается сокетами SOCK_STREAM), recvmsg() будет возвращать в своих вспомогательных данных элементы формы (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds), где fds — объект bytes, представляющий новые файловые дескрипторы в виде двоичного массива собственного 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)

Доступность: большинство платформ 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 и адрес такие же, как для recvmsg().

Пример:

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

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

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

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

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

socket.send(bytes[, flags]): Отправляет данные в сокет. Сокет должен быть подключен к удаленному сокету. У необязательного аргумента flags то же значение, что и для recv() выше. Возвращает количество отправленных байтов. Приложения несут ответственность за проверку того, что все данные были отправлены; если была передана только часть данных, приложению необходимо попытаться доставить оставшиеся данные. Для получения дополнительной информации по этой теме обратитесь к 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 зависит от семейства адресов, см. выше.)

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

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

socket.sendmsg(buffers[, ancdata[, flags[, address]]])

Отправлять обычные и вспомогательные данные в сокет, собирая не вспомогательные данные из ряда буферов и объединяя их в одно сообщение. Аргумент buffers определяет не вспомогательные данные как итерацию байтоподобного объекта (например, объекты bytes); ОС может установить ограничение (sysconf(), значение SC_IOV_MAX) на количество буферов, которые можно использовать. Аргумент ancdata определяет вспомогательные данные (управляющие сообщения) как итерацию из нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), где cmsg_level и cmsg_type — целые числа, определяющие уровень протокола и тип, зависящий от протокола, соответственно, а cmsg_data — байтовый объект, содержащий связанные данные. Обратите внимание, что некоторые системы (в частности, системы без CMSG_SPACE()) могут поддерживать отправку только одного управляющего сообщения за вызов. Аргумент flags по умолчанию равен 0 и содержит то же значение, что и для send(). Если указан address, а не None, он устанавливает адрес назначения для сообщения. Возвращаемое значение — количество отправленных несущественных байтов данных.

Следующая функция отправляет список файловых дескрипторов fds через сокет AF_UNIX в системах, поддерживающих механизм SCM_RIGHTS. См. также recvmsg().

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

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

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

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

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

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

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

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

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

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

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

socket.set_inheritable(inheritable): Устанавливает наследуемый флаг дескриптора файла сокета или дескриптора сокета.

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

socket.setblocking(flag)

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

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

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

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

socket.settimeout(value)

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

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

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

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

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

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

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

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

socket.shutdown(how): Отключает одну или обе половины соединения. Если how SHUT_RD, дальнейшие приемы запрещены. Если how SHUT_WR, дальнейшие отправки запрещены. Если how SHUT_RDWR, дальнейшая отправка и получение запрещены.

socket.share(process_id)

Дублировать сокет и подготовьте его для совместного использования с целевым процессом. Целевому процессу должен быть предоставлен process_id. Результирующий объект bytes затем может быть передан целевому процессу с использованием некоторой формы межпроцессного взаимодействия, и сокет может быть воссоздан там с помощью fromshare(). После вызова этого метода можно безопасно закрыть сокет, поскольку ОС уже продублировала его для целевого процесса.

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

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

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

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

См.также

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

Вводное руководство по межпроцессному взаимодействию 4.3BSD, написанное Стюартом Сечрестом
Расширенное руководство по межпроцессному взаимодействию 4.3BSD, написанное Сэмюэлем Дж. Леффлером и др.

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

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

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

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

Исключения

Константы

Функции

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

Прочие функции

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

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

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

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

Пример

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

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

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