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

Источник: Lib/socket.py

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

Примечание

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

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

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

См.также

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

Семейства розеток¶

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

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

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

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

Изменено в версии 3.5: Записываемый bytes-like object теперь принимается.

Пара (host, port) используется для семейства адресов AF_INET, где host - это строка, представляющая либо имя хоста в нотации интернет-домена, например 'daring.cwi.nl', либо адрес IPv4, например '100.50.200.5', а port - целое число.
- Для адресов IPv4 вместо адреса хоста принимаются две специальные формы: '' представляет собой INADDR_ANY, который используется для привязки ко всем интерфейсам, а строка '<broadcast>' представляет собой INADDR_BROADCAST. Такое поведение несовместимо с IPv6, поэтому, если вы собираетесь поддерживать IPv6 в своих программах на Python, лучше отказаться от их использования.
Для семейства адресов AF_INET6 используется четыре кортежа (host, port, flowinfo, scope_id), где flowinfo и scope_id представляют собой члены sin6_flowinfo и sin6_scope_id в struct sockaddr_in6 на C. Для методов модуля socket flowinfo и scope_id могут быть опущены просто для обратной совместимости. Однако, обратите внимание, что отсутствие scope_id может привести к проблемам при манипулировании скопированными IPv6-адресами.

Изменено в версии 3.7: Для многоадресных адресов (со значением scope_id) address может не содержать части %scope_id (или zone id). Эта информация является излишней и может быть опущена (рекомендуется).
Сокеты AF_NETLINK представлены в виде пар (pid, groups).
Поддержка TIPC только в Linux осуществляется с помощью семейства адресов AF_TIPC. TIPC - это открытый сетевой протокол, не основанный на IP, разработанный для использования в кластерных компьютерных средах. Адреса представляются в виде кортежа, поля которого зависят от типа адреса. Общая форма кортежа - (addr_type, v1, v2, v3 [, scope]), где:
- addr_type - одно из TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME или TIPC_ADDR_ID.
- scope - это одно из TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE и TIPC_NODE_SCOPE.
- Если addr_type равен TIPC_ADDR_NAME, то v1 - это тип сервера, v2 - идентификатор порта, а v3 должен быть равен 0.
  
  Если addr_type равен TIPC_ADDR_NAMESEQ, то v1 - это тип сервера, v2 - номер нижнего порта, а v3 - номер верхнего порта.
  
  Если addr_type равен TIPC_ADDR_ID, то v1 - это узел, v2 - ссылка, а v3 должно быть установлено в 0.
Для семейства адресов AF_CAN используется кортеж (interface, ), где interface - это строка, представляющая имя сетевого интерфейса, например 'can0'. Имя сетевого интерфейса '' может использоваться для приема пакетов от всех сетевых интерфейсов этого семейства.
- Протокол CAN_ISOTP требует кортеж (interface, rx_addr, tx_addr), где оба дополнительных параметра - длинные беззнаковые целые числа, представляющие идентификатор CAN (стандартный или расширенный).
- Протокол CAN_J1939 требует кортеж (interface, name, pgn, addr), где дополнительными параметрами являются 64-битное целое беззнаковое число, представляющее имя ECU, 32-битное целое беззнаковое число, представляющее номер группы параметров (PGN), и 8-битное целое число, представляющее адрес.
Строка или кортеж (id, unit) используется для протокола SYSPROTO_CONTROL семейства PF_SYSTEM. Строка - это имя элемента управления ядром, использующее динамически назначаемый идентификатор. Кортеж может использоваться, если известны ID и номер блока управления ядром или если используется зарегистрированный ID.

Added in version 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.

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

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

Availability: Linux >= 3.9

Смотрите vsock(7)

Added in version 3.7.
AF_PACKET - это низкоуровневый интерфейс непосредственно к сетевым устройствам. Адреса представлены кортежем (ifname, proto[, pkttype[, hatype[, addr]]]), где:
- ifname - Строка, указывающая имя устройства.
- proto - Номер протокола Ethernet. Может быть ETH_P_ALL для захвата всех протоколов, один из ETHERTYPE_* constants или любой другой номер протокола Ethernet.
- pkttype - необязательное целое число, указывающее тип пакета:
  - PACKET_HOST (по умолчанию) - Пакет, адресованный локальному хосту.
  - PACKET_BROADCAST - Широковещательный пакет физического уровня.
  - PACKET_MULTICAST - Пакет, отправленный на многоадресный адрес физического уровня.
  - PACKET_OTHERHOST - Пакет на другой хост, который был пойман драйвером устройства в режиме promiscuous.
  - PACKET_OUTGOING - Пакет, исходящий от локального хоста, который возвращается в пакетный сокет.
- hatype - необязательное целое число, указывающее тип аппаратного адреса ARP.
- addr - Необязательный байтоподобный объект, указывающий физический адрес оборудования, интерпретация которого зависит от устройства.
Availability: Linux >= 2.2.
AF_QIPCRTR - это интерфейс на базе сокетов только для Linux, предназначенный для взаимодействия с сервисами, работающими на сопроцессорах в платформах Qualcomm. Семейство адресов представлено в виде кортежа (node, port), где узел и порт - неотрицательные целые числа.

Availability: Linux >= 4.7.

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

Такой сокет должен быть создан с socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv4 или socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv6.

Availability: Linux >= 2.6.20, FreeBSD >= 10.1

Added in version 3.9.
AF_HYPERV - это интерфейс на основе сокетов только для Windows для связи с хостами и гостями Hyper-V. Семейство адресов представлено в виде кортежа (vm_id, service_id), где vm_id и service_id являются строками UUID.

vm_id - это идентификатор виртуальной машины или набор известных значений VMID, если цель не является конкретной виртуальной машиной. Известные константы VMID, определенные на socket, это:
- HV_GUID_ZERO
- HV_GUID_BROADCAST
- HV_GUID_WILDCARD - Используется для привязки к себе и приема соединений от всех разделов.
- HV_GUID_CHILDREN - Используется для привязки к себе и приема соединений от дочерних разделов.
- HV_GUID_LOOPBACK - Используется как цель для себя.
- HV_GUID_PARENT - При использовании в качестве привязки принимает соединение с родительским разделом. При использовании в качестве целевого адреса будет установлено соединение с родительским разделом.
service_id - это идентификатор зарегистрированной службы.

Added in version 3.12.

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

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

Неблокирующий режим поддерживается через 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¶

Утративший силу псевдоним TimeoutError.

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

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

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

Константы¶

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

Added in version 3.4.

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

socket.AF_UNSPEC¶: AF_UNSPEC означает, что getaddrinfo() должен возвращать адреса сокетов для любого семейства адресов (IPv4, IPv6 или любого другого), которое может быть использовано.

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

См.также

Secure File Descriptor Handling для более подробного объяснения.

Availability: Linux >= 2.6.27.

Added in version 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.

Изменено в версии 3.10: Добавлена IP_RECVTOS. Добавлена константа TCP_KEEPALIVE. В MacOS эта константа может использоваться так же, как TCP_KEEPIDLE в Linux.

Изменено в версии 3.11: Добавлена константа TCP_CONNECTION_INFO. В MacOS эта константа может использоваться так же, как TCP_INFO в Linux и BSD.

Изменено в версии 3.12: Добавлены константы SO_RTABLE и SO_USER_COOKIE. В OpenBSD и FreeBSD соответственно эти константы могут быть использованы так же, как SO_MARK в Linux. Также добавлены недостающие опции TCP-сокета из Linux: TCP_MD5SIG, TCP_THIN_LINEAR_TIMEOUTS, TCP_THIN_DUPACK, TCP_REPAIR, TCP_REPAIR_QUEUE, TCP_QUEUE_SEQ, TCP_REPAIR_OPTIONS, TCP_TIMESTAMP, TCP_CC_INFO, TCP_SAVE_SYN, TCP_SAVED_SYN, TCP_REPAIR_WINDOW, TCP_FASTOPEN_CONNECT, TCP_ULP, TCP_MD5SIG_EXT, TCP_FASTOPEN_KEY, TCP_FASTOPEN_NO_COOKIE, TCP_ZEROCOPY_RECEIVE, TCP_INQ, TCP_TX_DELAY. Добавлены IP_PKTINFO, IP_UNBLOCK_SOURCE, IP_BLOCK_SOURCE, IP_ADD_SOURCE_MEMBERSHIP, IP_DROP_SOURCE_MEMBERSHIP.

Изменено в версии 3.13: Добавлена константа SO_BINDTOIFINDEX. В Linux эта константа может использоваться так же, как и SO_BINDTODEVICE, но с индексом сетевого интерфейса вместо его имени.

socket.AF_CAN¶
socket.PF_CAN¶
SOL_CAN_*
CAN_*: Многие константы этих форм, описанные в документации Linux, также определены в модуле socket.

Availability: Linux >= 2.6.25, NetBSD >= 8.

Added in version 3.3.

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

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

Availability: Linux >= 2.6.25.

Примечание

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

Added in version 3.4.

socket.CAN_RAW_FD_FRAMES¶

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

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

Availability: Linux >= 3.6.

Added in version 3.5.

socket.CAN_RAW_JOIN_FILTERS¶

Объединяет примененные CAN-фильтры таким образом, что в пространство пользователя передаются только те CAN-кадры, которые соответствуют всем заданным CAN-фильтрам.

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

Availability: Linux >= 4.1.

Added in version 3.9.

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

Availability: Linux >= 2.6.25.

Added in version 3.7.

socket.CAN_J1939¶: CAN_J1939, в семействе протоколов CAN, - это протокол SAE J1939. Константы J1939 описаны в документации по Linux.

Availability: Linux >= 5.4.

Added in version 3.9.

socket.AF_DIVERT¶
socket.PF_DIVERT¶: Эти две константы, задокументированные на странице руководства FreeBSD divert(4), также определены в модуле socket.

Availability: FreeBSD >= 14.0.

Added in version 3.12.

socket.AF_PACKET¶
socket.PF_PACKET¶
PACKET_*: Многие константы этих форм, описанные в документации Linux, также определены в модуле socket.

Availability: Linux >= 2.2.

socket.ETH_P_ALL¶

ETH_P_ALL можно использовать в конструкторе socket в качестве proto для семейства AF_PACKET, чтобы перехватить каждый пакет, независимо от протокола.

Дополнительные сведения см. в руководстве packet(7).

Availability: Linux.

Added in version 3.12.

socket.AF_RDS¶
socket.PF_RDS¶
socket.SOL_RDS¶
RDS_*: Многие константы этих форм, описанные в документации Linux, также определены в модуле socket.

Availability: Linux >= 2.6.30.

Added in version 3.3.

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

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

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

socket.AF_ALG¶
socket.SOL_ALG¶
ALG_*: Константы для криптографии ядра Linux.

Availability: Linux >= 2.6.38.

Added in version 3.6.

socket.AF_VSOCK¶
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID¶
VMADDR*
SO_VM*: Константы для взаимодействия хоста и гостя в Linux.

Availability: Linux >= 4.8.

Added in version 3.7.

socket.AF_LINK¶: Availability: BSD, macOS.

Added in version 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.SCM_CREDS2¶
socket.LOCAL_CREDS¶
socket.LOCAL_CREDS_PERSISTENT¶: LOCAL_CREDS и LOCAL_CREDS_PERSISTENT могут использоваться с сокетами SOCK_DGRAM, SOCK_STREAM, эквивалентными Linux/DragonFlyBSD SO_PASSCRED, в то время как LOCAL_CREDS отправляет учетные данные при первом чтении, LOCAL_CREDS_PERSISTENT отправляет для каждого чтения, SCM_CREDS2 должен затем использоваться для последнего для типа сообщения.

Added in version 3.11.

Availability: FreeBSD.

socket.SO_INCOMING_CPU¶: Константа для оптимизации локальности процессора, используется в сочетании с SO_REUSEPORT.

Added in version 3.11.

Availability: Linux >= 3.9

socket.AF_HYPERV¶
socket.HV_PROTOCOL_RAW¶
socket.HVSOCKET_CONNECT_TIMEOUT¶
socket.HVSOCKET_CONNECT_TIMEOUT_MAX¶
socket.HVSOCKET_CONNECTED_SUSPEND¶
socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU¶
socket.HV_GUID_ZERO¶
socket.HV_GUID_WILDCARD¶
socket.HV_GUID_BROADCAST¶
socket.HV_GUID_CHILDREN¶
socket.HV_GUID_LOOPBACK¶
socket.HV_GUID_PARENT¶: Константы для сокетов Windows Hyper-V для связи между хостом и гостем.

Availability: Windows.

Added in version 3.12.

socket.ETHERTYPE_ARP¶
socket.ETHERTYPE_IP¶
socket.ETHERTYPE_IPV6¶
socket.ETHERTYPE_VLAN¶: IEEE 802.3 protocol number. константы.

Availability: Linux, FreeBSD, macOS.

Added in version 3.12.

Функции¶

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

Все следующие функции создают socket objects.

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

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

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

Вновь созданный сокет имеет номер non-inheritable.

Поднимает auditing event socket.__new__ с аргументами self, family, type, protocol.

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

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

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

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

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

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

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

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

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

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

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

Вновь созданные сокеты становятся non-inheritable.

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

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

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

socket.create_connection(address, timeout=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)¶

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

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

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

Когда соединение не может быть создано, возникает исключение. По умолчанию это исключение из последнего адреса в списке. Если all_errors имеет значение True, то это будет ExceptionGroup, содержащий ошибки всех попыток.

Изменено в версии 3.2: Был добавлен адрес_источника.

Изменено в версии 3.11: Была добавлена функция all_errors.

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

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

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

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

import socket

addr = ("", 8080)  # all interfaces, port 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 сокета устанавливается для того, чтобы немедленно повторно использовать предыдущие сокеты, которые были привязаны к тому же адресу и оставались в состоянии TIME_WAIT.

Added in version 3.8.

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

Added in version 3.8.

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

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

Вновь созданный сокет имеет номер non-inheritable.

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

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

Availability: Windows.

Added in version 3.3.

socket.SocketType¶: Это объект типа Python, который представляет тип объекта сокета. Это то же самое, что и type(socket(...)).

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

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

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

Added in version 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 будет строкой, представляющей каноническое имя хоста, если AI_CANONNAME является частью аргумента flags; в противном случае canonname будет пустым. sockaddr - кортеж, описывающий адрес сокета, формат которого зависит от возвращаемого семейства ((address, port) 2-кортеж для AF_INET, (address, port, flowinfo, scope_id) 4-кортеж для AF_INET6) и предназначенный для передачи в метод socket.connect().

Поднимает auditing event socket.getaddrinfo с аргументами host, port, family, type, protocol.

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

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

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

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

socket.getfqdn([name])¶: Возвращает полное доменное имя для name. Если name опущено или пусто, оно интерпретируется как локальный хост. Чтобы найти полностью квалифицированное имя, проверяется имя хоста, возвращенное командой gethostbyaddr(), а затем псевдонимы хоста, если они доступны. Выбирается первое имя, содержащее точку. Если полное доменное имя недоступно, а было указано name, оно возвращается без изменений. Если name было пустым или равным '0.0.0.0', возвращается имя хоста из gethostname().

socket.gethostbyname(hostname)¶

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

Поднимает auditing event socket.gethostbyname с аргументом hostname.

Availability: не WASI.

socket.gethostbyname_ex(hostname)¶

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

Поднимает auditing event socket.gethostbyname с аргументом hostname.

Availability: не WASI.

socket.gethostname()¶

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

Поднимает auditing event socket.gethostname без аргументов.

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

Availability: не WASI.

socket.gethostbyaddr(ip_address)¶

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

Поднимает auditing event socket.gethostbyaddr с аргументом ip_address.

Availability: не WASI.

socket.getnameinfo(sockaddr, flags)¶

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

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

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

Поднимает auditing event socket.getnameinfo с аргументом sockaddr.

Availability: не WASI.

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

Availability: не WASI.

socket.getservbyname(servicename[, protocolname])¶

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

Поднимает auditing event socket.getservbyname с аргументами servicename, protocolname.

Availability: не WASI.

socket.getservbyport(port[, protocolname])¶

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

Поднимает auditing event socket.getservbyport с аргументами port, protocolname.

Availability: не WASI.

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

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

Изменено в версии 3.10: Вызывает OverflowError, если x не помещается в 16-битное беззнаковое целое число.

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

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

Изменено в версии 3.10: Вызывает OverflowError, если x не помещается в 16-битное беззнаковое целое число.

socket.inet_aton(ip_string)¶

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

inet_aton() также принимает строки, содержащие менее трех точек; подробности см. на странице руководства по Unix inet(3).

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

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

socket.inet_ntoa(packed_ip)¶

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

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

Изменено в версии 3.5: Записываемый bytes-like object теперь принимается.

socket.inet_pton(address_family, ip_string)¶

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

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

Availability: Unix, Windows.

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

socket.inet_ntop(address_family, packed_ip)¶

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

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

Availability: Unix, Windows.

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

Изменено в версии 3.5: Записываемый bytes-like object теперь принимается.

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

Availability: Unix, не WASI.

Большинство платформ Unix.

Added in version 3.3.

socket.CMSG_SPACE(length)¶

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

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

Availability: Unix, не WASI.

большинство платформ Unix.

Added in version 3.3.

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

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

socket.sethostname(name)¶

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

Поднимает auditing event socket.sethostname с аргументом name.

Availability: Unix.

Added in version 3.3.

socket.if_nameindex()¶

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

Availability: Unix, Windows, не WASI.

Added in version 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, не WASI.

Added in version 3.3.

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

См.также

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

socket.if_indextoname(if_index)¶: Возвращает имя сетевого интерфейса, соответствующее номеру индекса интерфейса. OSError, если интерфейса с заданным индексом не существует.

Availability: Unix, Windows, не WASI.

Added in version 3.3.

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

См.также

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

socket.send_fds(sock, buffers, fds[, flags[, address]])¶: Передача списка файловых дескрипторов fds через AF_UNIX сокет sock. Параметр fds представляет собой последовательность дескрипторов файлов. Документация по этим параметрам приведена в sendmsg().

Availability: Unix, Windows, не WASI.

Платформы Unix, поддерживающие механизм sendmsg() и SCM_RIGHTS.

Added in version 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])¶: Получение до maxfds файловых дескрипторов с AF_UNIX сокета sock. Возвращает (msg, list(fds), flags, addr). Документация по этим параметрам приведена в recvmsg().

Availability: Unix, Windows, не WASI.

Платформы Unix, поддерживающие механизм sendmsg() и SCM_RIGHTS.

Added in version 3.9.

Примечание

Любые усеченные целые числа в конце списка дескрипторов файлов.

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

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

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

socket.accept()¶

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

Вновь созданный сокет имеет номер non-inheritable.

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

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

socket.bind(address)¶

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

Поднимает auditing event socket.bind с аргументами self, address.

Availability: не WASI.

socket.close()¶

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

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

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

Примечание

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

socket.connect(address)¶

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

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

Поднимает auditing event socket.connect с аргументами self, address.

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

Availability: не WASI.

socket.connect_ex(address)¶

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

Поднимает auditing event socket.connect с аргументами self, address.

Availability: не WASI.

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

Added in version 3.2.

socket.dup()¶

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

Вновь созданный сокет имеет номер non-inheritable.

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

Availability: не WASI.

socket.fileno()¶

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

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

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

Added in version 3.4.

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

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

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

Availability: не WASI.

socket.getblocking()¶

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

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

Added in version 3.7.

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

socket.ioctl(control, option)¶

платформа:: Windows

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

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

Availability: не WASI.

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

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

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

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

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

Примечание

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

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

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Availability: Unix.

Большинство платформ Unix.

Added in version 3.3.

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

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

Получает обычные и вспомогательные данные из сокета, ведя себя так же, как и recvmsg(), но вместо возврата нового объекта bytes распределяет неанциллярные данные по ряду буферов. Аргумент buffers должен быть итерацией объектов, экспортирующих буферы для записи (например, объектов bytearray); они будут заполняться последовательными фрагментами неанциллярных данных, пока все они не будут записаны или пока не кончатся буферы. Операционная система может установить ограничение (sysconf() значение SC_IOV_MAX) на количество буферов, которые могут быть использованы. Аргументы ancbufsize и flags имеют то же значение, что и для recvmsg().

Возвращаемое значение представляет собой 4 кортежа: (nbytes, ancdata, msg_flags, address), где nbytes - общее количество байт неанциллярных данных, записанных в буферы, а ancdata, msg_flags и address - те же, что и для recvmsg().

Пример:

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

Availability: Unix.

Большинство платформ Unix.

Added in version 3.3.

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

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

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)

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

Поднимает auditing event socket.sendto с аргументами self, address.

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

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

Отправляет обычные и вспомогательные данные в сокет, собирая неанциллярные данные из ряда буферов и конкатенируя их в одно сообщение. Аргумент buffers задает неанцилярные данные в виде итерабельного набора bytes-like objects (например, 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, не WASI.

Большинство платформ Unix.

Поднимает auditing event socket.sendmsg с аргументами self, address.

Added in version 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.

Added in version 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. Неблокирующие сокеты не поддерживаются.

Added in version 3.5.

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

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

Изменено в версии 3.5: Записываемый bytes-like object теперь принимается.

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

Availability: не WASI.

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

Availability: не WASI.

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

Availability: Windows.

Added in version 3.3.

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

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

socket.family¶: Семейство сокетов.

socket.type¶: Тип сокета.

socket.proto¶: Протокол сокетов.

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

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

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

Примечание

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

# Echo server program
import socket

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

# Echo client program
import socket

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

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

# Echo server program
import socket
import sys

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

# Echo client program
import socket
import sys

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

Следующий пример показывает, как написать очень простой сетевой сниффер с сырыми сокетами под Windows. Пример требует привилегий администратора для изменения интерфейса:

import socket

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

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

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

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

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

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

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

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

После связывания (CAN_RAW) или подключения (CAN_BCM) сокета вы можете использовать операции socket.send() и socket.recv() (и их аналоги) над объектом сокета как обычно.

Последний пример может потребовать особых привилегий:

import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')

Запуск примера несколько раз со слишком маленькой задержкой между выполнениями может привести к такой ошибке:

OSError: [Errno 98] Address already in use

Это происходит потому, что в результате предыдущего выполнения сокет перешел в состояние TIME_WAIT и не может быть немедленно использован повторно.

Чтобы предотвратить это, необходимо установить флаг socket, socket.SO_REUSEADDR:

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))

Флаг SO_REUSEADDR указывает ядру повторно использовать локальный сокет в состоянии TIME_WAIT, не дожидаясь истечения его естественного таймаута.

См.также

Введение в программирование сокетов (на языке 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¶

Пример¶

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

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

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