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

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

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

Примечание

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

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

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

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

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

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

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

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

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

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

Пара (host, port) используется для семейства адресов AF_INET, где хост – это строка, представляющая либо имя хоста в нотации интернет-домена, например 'daring.cwi.nl', либо IPv4-адрес, например '100.50.200.5', а порт – целое число.
- Для IPv4-адресов вместо адреса хоста принимаются две специальные формы: '' представляет INADDR_ANY, который используется для привязки ко всем интерфейсам, а строка '<broadcast>' представляет INADDR_BROADCAST. Такое поведение несовместимо с IPv6, поэтому вам, возможно, стоит избегать их, если вы планируете поддерживать IPv6 в своих программах на Python.
Для семейства адресов AF_INET6 используется кортеж из четырёх элементов (host, port, flowinfo, scopeid), где flowinfo и scopeid представляют члены sin6_flowinfo и sin6_scope_id в структуре struct sockaddr_in6 в C. Для методов модуля socket flowinfo и scopeid могут опускаться только ради обратной совместимости. Однако опускание scopeid может вызвать проблемы при работе с адресами IPv6, имеющими область действия.
Сокеты 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'. Имя сетевого интерфейса '' может использоваться для получения пакетов от всех сетевых интерфейсов этого семейства.
Строка или кортеж (id, unit) используется для протокола SYSPROTO_CONTROL семейства PF_SYSTEM. Строка – это имя элемента управления ядра с динамически назначаемым идентификатором. Кортеж можно использовать, если известны ID и номер модуля элемента управления ядра или используется зарегистрированный ID.

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

Новое в версии 3.6.
AF_PACKET – это низкоуровневый интерфейс для прямого взаимодействия с сетевыми устройствами. Пакеты представляются кортежем (ifname, proto[, pkttype[, hatype[, addr]]]), где:
- ifname - строка, указывающая имя устройства.
- proto – целое число в сетевом порядке байт, задающее номер протокола Ethernet.
- pkttype - необязательное целое число, задающее тип пакета:
  - PACKET_HOST (по умолчанию) – пакет, адресованный локальному хосту.
  - PACKET_BROADCAST – широковещательный пакет физического уровня.
  - PACKET_MULTIHOST – пакет, отправленный на многоадресный адрес физического уровня.
  - PACKET_OTHERHOST – пакет для другого хоста, перехваченный драйвером устройства в неразборчивом режиме.
  - PACKET_OUTGOING – пакет, отправленный с локального хоста и возвращённый обратно на пакетный сокет.
- hatype - необязательное целое число, задающее тип аппаратного адреса ARP.
- addr - необязательный байтоподобный объект, задающий физический аппаратный адрес; его интерпретация зависит от устройства.

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

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

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

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

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

18.1.2.1. Исключения

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

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

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

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

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

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

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

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

18.1.2.2. Константы

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

Новое в версии 3.4.

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

socket.SOCK_STREAM¶
socket.SOCK_DGRAM¶
socket.SOCK_RAW¶
socket.SOCK_RDM¶
socket.SOCK_SEQPACKET¶: Эти константы представляют типы сокетов, используемые для второго аргумента socket(). В зависимости от системы могут быть доступны и другие константы. (Обычно полезны только SOCK_STREAM и SOCK_DGRAM.)

socket.SOCK_CLOEXEC¶

socket.SOCK_NONBLOCK¶

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

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

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

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

Новое в версии 3.2.

SO_*
socket.SOMAXCONN¶
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*: Многие константы этих форм, описанные в документации Unix по сокетам и/или протоколу IP, также определены в модуле socket. Они обычно используются в аргументах методов setsockopt() и getsockopt() объектов сокетов. В большинстве случаев определены только те символы, которые определены в заголовочных файлах Unix; для некоторых символов предоставлены значения по умолчанию.

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

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

socket.AF_CAN¶

socket.PF_CAN¶

SOL_CAN_*

CAN_*

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

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

Новое в версии 3.3.

socket.CAN_BCM¶

CAN_BCM_*

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

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

Новое в версии 3.4.

socket.CAN_RAW_FD_FRAMES¶

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

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

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

Новое в версии 3.5.

socket.AF_PACKET¶

socket.PF_PACKET¶

PACKET_*

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

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

socket.AF_RDS¶

socket.PF_RDS¶

socket.SOL_RDS¶

RDS_*

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

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

Новое в версии 3.3.

socket.SIO_RCVALL¶
socket.SIO_KEEPALIVE_VALS¶
socket.SIO_LOOPBACK_FAST_PATH¶
RCVALL_*: Константы для 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_LINK¶: Доступность: BSD, OSX.

Новое в версии 3.4.

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

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

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

18.1.2.3. Функции

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

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

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. Если указан fileno, остальные аргументы игнорируются, и возвращается сокет с заданным файловым дескриптором. В отличие от socket.fromfd(), fileno вернёт тот же самый сокет, а не дубликат. Это может помочь закрыть отсоединённый сокет с помощью socket.close().

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

(family, type, proto, canonname, sockaddr)

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

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

python

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

Изменено в версии 3.2: теперь параметры можно передавать в виде именованных аргументов.

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

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

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

socket.gethostname()¶

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

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

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

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

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

socket.getservbyname(servicename, protocolnameprotocolname])¶: Преобразует имя интернет-службы и имя протокола в номер порта для этой службы. Если указано необязательное имя протокола, оно должно быть 'tcp' или 'udp', в противном случае подойдет любой протокол.

socket.getservbyport(port, [, protocolname])¶: Преобразует номер интернет-порта и имя протокола в имя службы для этой службы. Если указано необязательное имя протокола, оно должно быть 'tcp' или 'udp', в противном случае подойдет любой протокол.

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

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

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

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

socket.inet_aton(ip_string)¶

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

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

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

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

socket.inet_ntoa(packed_ip)¶

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

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

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

socket.inet_pton(address_family, ip_string)¶

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

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

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

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

socket.inet_ntop(address_family, packed_ip)¶

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

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

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

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

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

socket.CMSG_LEN(length)¶

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, возможно, другие.

Новое в версии 3.3.

socket.CMSG_SPACE(length)¶

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

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

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

Новое в версии 3.3.

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

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

socket.sethostname(имя)¶

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

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

Новое в версии 3.3.

socket.if_nameindex()¶

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

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

Новое в версии 3.3.

socket.if_nametoindex(if_name)¶

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

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

Новое в версии 3.3.

socket.if_indextoname(if_index)¶

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

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

Новое в версии 3.3.

18.1.3. Объекты сокетов

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

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

socket.accept()¶

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

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

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

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.bind(address)¶: Привязывает сокет к address. Сокет не должен быть уже привязан. (Формат address зависит от семейства адресов – см. выше.)

socket.close()¶

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

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

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

Примечание

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

socket.connect(address)¶

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

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

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

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

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

Новое в версии 3.2.

socket.dup()¶

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

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

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

socket.fileno()¶

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

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

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

Новое в версии 3.4.

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

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

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

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

socket.ioctl(control, option)¶

Платформа: Windows

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

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

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

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

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

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

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

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

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

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

Примечание

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

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

Примечание

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

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.recvfrom(bufsize[, flags])¶: Получает данные из сокета. Возвращаемое значение – пара (bytes, address), где bytes – это объект bytes, представляющий полученные данные, а address – адрес сокета, отправляющего данные. Смысл необязательного аргумента flags описан на странице руководства Unix recv(2); по умолчанию он равен нулю. (Формат address зависит от семейства адресов – см. выше.)

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.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.fromstring(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

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

Новое в версии 3.3.

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, возможно, другие.

Новое в версии 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() выше. Возвращает количество отправленных байт. Приложения должны проверять, что все данные были отправлены; если была передана только часть данных, приложению необходимо попытаться доставить оставшиеся данные. Дополнительную информацию по этой теме можно найти в Socket Programming HOWTO.

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

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

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.sendto(bytes, address)¶
socket.sendto(bytes, flags, address): Отправляет данные в сокет. Сокет не должен быть подключён к удалённому сокету, поскольку целевой сокет задаётся параметром address. Необязательный аргумент flags имеет тот же смысл, что и для recv() выше. Возвращает количество отправленных байт. (Формат address зависит от семейства адресов – см. выше.)

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(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, возможно, другие.

Новое в версии 3.3.

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(наследуемый)¶: Устанавливает флаг наследования файлового дескриптора сокета или дескриптора сокета.

Новое в версии 3.4.

socket.setblocking(флаг)¶

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

Этот метод является сокращённой записью для определённых вызовов settimeout():

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

socket.settimeout(значение)¶

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

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

socket.setsockopt(уровень, имя опции, значение: int)¶

socket.setsockopt(уровень, имя опции, значение: buffer)

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

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

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

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

socket.share(идентификатор процесса)¶

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

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

Новое в версии 3.3.

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

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

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

18.1.5. Пример

Ниже приведены четыре минимальных примера программ, использующих протокол 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 через протокол raw socket. Чтобы вместо этого использовать CAN с протоколом broadcast manager, откройте сокет с помощью:

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».

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

18.1.1. Семейства сокетов​

18.1.2. Содержимое модуля​

18.1.2.1. Исключения​

18.1.2.2. Константы​

18.1.2.3. Функции​

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

18.1.2.3.2. Другие функции​

18.1.3. Объекты сокетов​

18.1.4. Заметки о тайм-аутах сокетов​

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

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

18.1.5. Пример​

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

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

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

18.1.2.1. Исключения

18.1.2.2. Константы

18.1.2.3. Функции

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

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

18.1.3. Объекты сокетов

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

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

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

18.1.5. Пример