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

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

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

Примечание

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

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

Этот модуль не работает или недоступен на WebAssembly. См. платформы WebAssembly для получения дополнительной информации.

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

Смотрите также

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

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

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

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

Адрес сокета 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, 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.
Кортеж (interface, ) используется для семейства адресов AF_CAN, где interface – это строка, представляющая имя сетевого интерфейса, например 'can0'. Имя сетевого интерфейса '' может использоваться для получения пакетов от всех сетевых интерфейсов этого семейства.
- Протокол CAN_ISOTP требует кортеж (interface, rx_addr, tx_addr), где оба дополнительных параметра – это беззнаковые длинные целые, представляющие идентификатор CAN (стандартный или расширенный).
- Протокол CAN_J1939 требует кортеж (interface, name, pgn, addr), где дополнительные параметры – это 64-битное беззнаковое целое, представляющее имя ЭБУ, 32-битное беззнаковое целое, представляющее номер группы параметров (PGN), и 8-битное целое, представляющее адрес.
Строка или кортеж (id, unit) используются для протокола SYSPROTO_CONTROL семейства PF_SYSTEM. Строка – это имя элемента управления ядра с динамически назначаемым идентификатором. Кортеж может использоваться, если известны идентификатор и номер устройства элемента управления ядра или используется зарегистрированный идентификатор.

Добавлено в версии 3.3.
AF_BLUETOOTH поддерживает следующие протоколы и форматы адресов:
- BTPROTO_L2CAP принимает кортеж (bdaddr, psm[, cid[, bdaddr_type]]), где:
  - bdaddr – это строка, задающая Bluetooth-адрес.
  - psm – это целое число, задающее мультиплексор протокола/сервиса.
  - cid – это необязательное целое число, задающее идентификатор канала. Если не указано, по умолчанию равно нулю.
  - bdaddr_type – это необязательное целое число, задающее тип адреса; одно из BDADDR_BREDR (по умолчанию), BDADDR_LE_PUBLIC, BDADDR_LE_RANDOM.
  Изменено в версии 3.14: Добавлены поля cid и bdaddr_type.
- BTPROTO_RFCOMM принимает (bdaddr, channel), где bdaddr – это Bluetooth-адрес в виде строки, а channel – целое число.
- BTPROTO_HCI принимает формат, зависящий от операционной системы.
  - В Linux он принимает целое число device_id или кортеж (device_id, [channel]), где device_id задаёт номер Bluetooth-устройства, а channel – необязательное целое число, задающее канал HCI (по умолчанию HCI_CHANNEL_RAW).
  - В FreeBSD, NetBSD и DragonFly BSD он принимает bdaddr, где bdaddr – это Bluetooth-адрес в виде строки.
  Изменено в версии 3.2: Добавлена поддержка NetBSD и DragonFlyBSD.
  
  Изменено в версии 3.13.3: Добавлена поддержка FreeBSD.
  
  Изменено в версии 3.14: Добавлено поле channel. Теперь принимается device_id, не упакованный в кортеж.
- BTPROTO_SCO принимает bdaddr, где bdaddr – это Bluetooth-адрес в виде строки или объект bytes. (например, '12:23:34:45:56:67' или b'12:23:34:45:56:67')
  
  Изменено в версии 3.14: Добавлена поддержка FreeBSD.
AF_ALG – это интерфейс на основе сокетов для криптографии ядра, доступный только в Linux. Сокет алгоритма настраивается с помощью кортежа из двух-четырех элементов (type, name [, feat [, mask]]), где:
- type – это тип алгоритма в виде строки, например aead, hash, skcipher или rng.
- name – это имя алгоритма и режим работы в виде строки, например sha256, hmac(sha256), cbc(aes) или drbg_nopr_ctr_aes256.
- feat и mask – это беззнаковые 32-битные целые числа.
Доступность: Linux >= 2.6.38.

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

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

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

См. vsock(7)

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

Поддержка: Linux >= 4.7.

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

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

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

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

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

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

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

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

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

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

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

ExceptionsИсключения

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, возвращаемое функцией 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¶

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

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

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

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

ConstantsКонстанты

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

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

Смотрите также

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

Доступность: 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: Добавлена поддержка TCP_FASTOPEN, TCP_KEEPCNT на платформах Windows при наличии.

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

Добавлена поддержка 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, но с индексом сетевого интерфейса вместо его имени.

Изменено в версии 3.14: добавлены отсутствовавшие IP_FREEBIND, IP_RECVERR, IPV6_RECVERR, IP_RECVTTL и IP_RECVORIGDSTADDR на Linux.

Изменено в версии 3.14: добавлена поддержка TCP_QUICKACK на платформах Windows при наличии.

Изменено в версии 3.15: добавлен IPV6_HDRINCL.

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

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

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

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

Изменено в версии 3.14: восстановлен отсутствовавший CAN_RAW_ERR_FILTER на Linux.

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-кадры; однако при чтении из сокета необходимо принимать оба типа кадров.

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

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

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

socket.CAN_RAW_JOIN_FILTERS¶

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

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

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

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

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

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

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

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

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

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

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

Доступность: FreeBSD >= 14.0.

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

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

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

socket.ETH_P_ALL¶

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

Дополнительную информацию см. на странице руководства packet(7).

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

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

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_*: Константы для WSAIoctl() в Windows. Эти константы используются в качестве аргументов метода 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, macOS.

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

socket.has_ipv6¶: Эта константа содержит булево значение, которое указывает, поддерживается ли IPv6 на этой платформе.

socket.AF_BLUETOOTH¶
socket.BTPROTO_L2CAP¶
socket.BTPROTO_RFCOMM¶
socket.BTPROTO_HCI¶
socket.BTPROTO_SCO¶: Целочисленные константы для использования с Bluetooth-адресами.

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

socket.BDADDR_BREDR¶
socket.BDADDR_LE_PUBLIC¶
socket.BDADDR_LE_RANDOM¶: Эти константы описывают тип адреса Bluetooth при привязке или подключении сокета BTPROTO_L2CAP.

Доступность: Linux, FreeBSD

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

socket.SOL_RFCOMM¶

socket.SOL_L2CAP¶

socket.SOL_HCI¶

socket.SOL_SCO¶

socket.SOL_BLUETOOTH¶

Используется в аргументе level методов setsockopt() и getsockopt() объектов Bluetooth-сокетов.

SOL_BLUETOOTH доступен только в Linux. Другие константы доступны, если поддерживается соответствующий протокол.

SO_L2CAP_*

socket.L2CAP_LM¶

L2CAP_LM_*

SO_RFCOMM_*

RFCOMM_LM_*

SO_SCO_*

SO_BTH_*

BT_*

Используется в аргументах имени опции и значения методов setsockopt() и getsockopt() объектов Bluetooth-сокетов.

BT_* и L2CAP_LM доступны только в Linux. SO_BTH_* доступны только в Windows. Другие константы могут быть доступны в Linux и на различных BSD-платформах.

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

socket.HCI_FILTER¶
socket.HCI_TIME_STAMP¶
socket.HCI_DATA_DIR¶
socket.SO_HCI_EVT_FILTER¶
socket.SO_HCI_PKT_FILTER¶: Имена опций для использования с BTPROTO_HCI. Доступность и формат значений опций зависят от платформы.

Изменено в версии 3.14: Добавлены SO_HCI_EVT_FILTER и SO_HCI_PKT_FILTER в NetBSD и DragonFly BSD. Добавлен HCI_DATA_DIR в FreeBSD, NetBSD и DragonFly BSD.

socket.HCI_DEV_NONE¶: Значение device_id, используемое для создания HCI-сокета, который не привязан к конкретному Bluetooth-адаптеру.

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

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

socket.HCI_CHANNEL_RAW¶
socket.HCI_CHANNEL_USER¶
socket.HCI_CHANNEL_MONITOR¶
socket.HCI_CHANNEL_CONTROL¶
socket.HCI_CHANNEL_LOGGING¶: Возможные значения для поля channel в адресе BTPROTO_HCI.

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

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

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

Поддержка: Linux >= 4.7.

socket.SCM_CREDS2¶
socket.LOCAL_CREDS¶
socket.LOCAL_CREDS_PERSISTENT¶: LOCAL_CREDS и LOCAL_CREDS_PERSISTENT можно использовать с сокетами SOCK_DGRAM и SOCK_STREAM, что эквивалентно SO_PASSCRED в Linux/DragonFlyBSD. LOCAL_CREDS отправляет учётные данные при первом чтении, а LOCAL_CREDS_PERSISTENT – при каждом чтении. Для последнего в качестве типа сообщения необходимо использовать SCM_CREDS2.

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

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

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

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

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

socket.SO_REUSEPORT_LB¶: Константа, позволяющая выполнять привязки к дублирующимся адресам и портам с балансировкой нагрузки.

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

Доступность: FreeBSD >= 12.0

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 для связи между хостом и гостевой системой.

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

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

socket.ETHERTYPE_ARP¶
socket.ETHERTYPE_IP¶
socket.ETHERTYPE_IPV6¶
socket.ETHERTYPE_VLAN¶: Номер протокола IEEE 802.3. константы.

Доступность: Linux, FreeBSD, macOS.

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

socket.SHUT_RD¶
socket.SHUT_WR¶
socket.SHUT_RDWR¶: Эти константы используются методом shutdown() объектов сокетов.

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

FunctionsФункции

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

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

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

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

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

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

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

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

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

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

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

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

python

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.

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

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

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

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

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

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

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

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

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

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

Изменено в версии 3.11: добавлен параметр all_errors.

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

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

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

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

python

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

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

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

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

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

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

Эта функция является обёрткой C-функции getaddrinfo базовой системы.

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

Аргументы family, type и proto можно необязательно указать, чтобы задать параметры и ограничить список возвращаемых адресов. Передайте их значения по умолчанию (соответственно AF_UNSPEC, 0 и 0), чтобы не ограничивать результаты. Подробнее см. примечание ниже.

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

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

(family, type, proto, canonname, sockaddr)

В этих кортежах family, type, proto – целые числа, предназначенные для передачи в функцию socket(). canonname будет строкой, представляющей каноническое имя хоста, если AI_CANONNAME является частью аргумента flags; в противном случае canonname будет пустой строкой. sockaddr – это кортеж, описывающий адрес сокета, формат которого зависит от возвращённых family и флагов, с которыми был скомпилирован Python, и предназначен для передачи методу socket.connect().

sockaddr может быть одним из следующих:

(address, port) 2-кортеж для AF_INET
(address, port, flowinfo, scope_id) 4-кортеж для AF_INET6, если Python был скомпилирован с --enable-ipv6 (по умолчанию)
2-кортеж, содержащий сырые данные для AF_INET6, если Python был скомпилирован с --disable-ipv6

Примечание

Если предполагается использовать результаты из getaddrinfo() для создания сокета (а не, например, для получения canonname), стоит ограничить результаты по type (например, SOCK_STREAM или SOCK_DGRAM) и/или proto (например, IPPROTO_TCP или IPPROTO_UDP), которые может обработать приложение.

Поведение со значениями по умолчанию для family, type, proto и flags зависит от системы.

Многие системы (например, большинство конфигураций Linux) возвращают отсортированный список всех подходящих адресов. Эти адреса обычно следует перебирать по порядку, пока соединение не установится (возможна параллельная проверка, например, с использованием алгоритма Happy Eyeballs). В таких случаях ограничение по type и/или proto может помочь исключить неудачные или непригодные попытки соединения.

Однако некоторые системы возвращают только один адрес. (Например, это наблюдалось в конфигурациях Solaris и AIX.) В таких системах ограничение по type и/или proto помогает гарантировать, что этот адрес будет пригоден для использования.

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

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

python

>>> 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, и для поддержки двойного стека IPv4/v6 следует использовать getaddrinfo().

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

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

socket.gethostbyname_ex(hostname)¶

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

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

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

socket.gethostname()¶

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

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

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

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

socket.gethostbyaddr(ip_address)¶

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

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

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

socket.getnameinfo(sockaddr, flags)¶

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

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

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

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

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

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

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

socket.getservbyname(servicename[, protocolname])¶

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

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

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

socket.getservbyport(port[, protocolname])¶

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

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

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

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

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

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

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

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

Изменено в версии 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. Обратите внимание, что точное определение допустимости зависит от базовой реализации C функции inet_aton().

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

socket.inet_ntoa(packed_ip)¶

Преобразует 32-битный упакованный IPv4-адрес (байтоподобный объект длиной четыре байта) в его стандартное строковое представление в точечно-десятичной записи (например, ‘123.45.67.89’). Это полезно при взаимодействии с программой, использующей стандартную библиотеку C и требующей объекты типа 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() полезен, когда библиотека или сетевой протокол требует объект типа in_addr (похожий на inet_aton()) или 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() полезен, когда библиотека или сетевой протокол возвращает объект типа in_addr (похожий на inet_ntoa()) или 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)¶: Return the total length, without trailing padding, of an ancillary data item with associated data of the given length. This value can often be used as the buffer size for recvmsg() to receive a single item of ancillary data, but RFC 3542 requires portable applications to use CMSG_SPACE() and thus include space for padding, even when the item will be the last in the buffer. Raises OverflowError if length is outside the permissible range of values.

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

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

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

socket.CMSG_SPACE(length)¶

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

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

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

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

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

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

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

Изменено в версии 3.15: Принимает любое вещественное число, а не только целое или число с плавающей точкой.

socket.sethostname(name)¶

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

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

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

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

socket.if_nameindex()¶

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

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

Добавлено в версии 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, не WASI.

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

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

Смотрите также

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

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

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

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

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

Смотрите также

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

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

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

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

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

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

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

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

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

Примечание

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

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

Объекты сокетов имеют следующие методы. За исключением 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.

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

socket.close()¶

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

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

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

Примечание

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

socket.connect(address)¶

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

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

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

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

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

socket.connect_ex(address)¶

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

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

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

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

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

socket.dup()¶

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

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

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

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

socket.fileno()¶

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

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

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

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

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

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

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

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

socket.getblocking()¶

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

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

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

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

socket.ioctl(control, option)¶

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Изменено в версии 3.7: Для многоадресного IPv6-адреса первый элемент address больше не содержит часть %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().

python

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Массив целых чисел
    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.

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

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

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

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

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

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

Пример:

python

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

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

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

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

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

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

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

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

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

python

import socket, array

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

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

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

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

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

Changed in version 3.5: If the system call is interrupted and the signal handler does not raise an exception, the method now retries the system call instead of raising an InterruptedError exception (see PEP 475 for the rationale).

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

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

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

Изменено в версии 3.15: Принимает любое вещественное число, а не только целое или с плавающей запятой.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Notes on socket timeoutsПримечания по тайм-аутам сокетов

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

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

Примечание

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

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

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

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

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

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

ExampleПример

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

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

python

# Программа эхо-сервера
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)

python

# Программа эхо-клиента
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. Клиентская сторона попытается подключиться ко всем адресам, возвращённым в результате разрешения имён, и отправит трафик на первый успешно подключённый.

python

# Программа эхо-сервера
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)

python

# Программа эхо-клиента
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. Для изменения интерфейса пример требует прав администратора:

python

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 с протоколом менеджера широковещательной рассылки, откройте сокет с помощью:

python

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

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

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

python

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

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

python

OSError: [Errno 98] Address already in use

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

Существует флаг socket, который можно установить, чтобы предотвратить это, socket.SO_REUSEADDR:

python

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, автор Stuart Sechrest
Продвинутое руководство по межпроцессному взаимодействию в 4.3BSD, авторы Samuel J. Leffler и др.

оба в UNIX Programmer’s Manual, Supplementary Documents 1 (разделы PS1:7 и PS1:8). Платформозависимые справочные материалы для различных системных вызовов, связанных с сокетами, также являются ценным источником информации о деталях семантики сокетов. Для Unix обратитесь к man-страницам; для Windows – к спецификации WinSock (или Winsock 2). Для API, поддерживающих IPv6, читатели могут обратиться к RFC 3493, озаглавленному «Basic Socket Interface Extensions for IPv6».

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

Socket familiesСемейства сокетов​

Module contentsСодержимое модуля​

ExceptionsИсключения​

ConstantsКонстанты​

FunctionsФункции​

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

Other functionsДругие функции​

Socket ObjectsОбъекты сокетов​

Notes on socket timeoutsПримечания по тайм-аутам сокетов​

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

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

ExampleПример​

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

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

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

ExceptionsИсключения

ConstantsКонстанты

FunctionsФункции

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

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

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

Notes on socket timeoutsПримечания по тайм-аутам сокетов

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

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

ExampleПример