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.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.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: 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.
Дублирует сокет и подготавливает его для совместного использования с целевым процессом. Целевому процессу должен быть предоставлен 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».