socket — Интерфейс низкоуровневого сетевого программирования

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

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

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

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

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

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

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

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

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

• Для семейства адресов AF_INET используется пара (host, port), где хост — это строка, представляющая либо имя хоста в формате доменных имен Интернета, например '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 с областями действия.

  Изменено в версии 3.7: Для адресов мультикаста (с scopeid имеющим значение) address может не содержать %scope (или zone id) части. Эта информация излишняя и может быть безопасно опущена (рекомендуется).

• AF_NETLINK сокеты представляются парами (pid, groups).

• Только для Linux, поддержка TIPC доступна с использованием семейства адресов AF_TIPC. TIPC — это открытый, не основанный на IP сетевой протокол, предназначенный для использования в кластерных компьютерных средах. Адреса представляются кортежем, а поля зависят от типа адреса. Общий формат кортежа (addr_type, v1, v2, v3 [, scope]), где:

  • addr_type — это один из TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, или TIPC_ADDR_ID.
  • scope — один из TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, и TIPC_NODE_SCOPE.

  • Если addr_type — TIPC_ADDR_NAME, то v1 — тип сервера, v2 — идентификатор порта, а v3 должен быть 0.

    Если addr_type — TIPC_ADDR_NAMESEQ, то v1 — тип сервера, v2 — меньший номер порта, а v3 — больший номер порта.

    Если addr_type — TIPC_ADDR_ID, то v1 — узел, v2 — ссылка, а v3 должен быть установлен в 0.

• Кортеж (interface, ) используется для семейства адресов AF_CAN, где interface — строка, представляющая имя сетевого интерфейса, например 'can0'. Имя сетевого интерфейса '' может использоваться для приема пакетов со всех сетевых интерфейсов этого семейства.

  • Протокол CAN_ISOTP требует кортеж (interface, rx_addr, tx_addr), где оба дополнительных параметра являются беззнаковыми 32-разрядными целыми числами, представляющими идентификатор CAN (стандартный или расширенный).

• Строка или кортеж (id, unit) используется для протокола SYSPROTO_CONTROL семейства PF_SYSTEM. Строка — имя ядра управления с динамически назначенным ID. Кортеж может быть использован, если известны ID и номер устройства ядра управления или используется зарегистрированный ID.

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

• AF_BLUETOOTH поддерживает следующие протоколы и форматы адресов:

  • BTPROTO_L2CAP принимает (bdaddr, psm), где bdaddr — Bluetooth-адрес в виде строки, а psm — целое число.
  • BTPROTO_RFCOMM принимает (bdaddr, channel), где bdaddr — Bluetooth-адрес в виде строки, а channel — целое число.

  • BTPROTO_HCI принимает (device_id,), где device_id — либо целое число, либо строка с Bluetooth-адресом интерфейса. (Это зависит от вашей ОС; NetBSD и DragonFlyBSD ожидают Bluetooth-адрес, а все остальные — целое число.)

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

  • BTPROTO_SCO принимает bdaddr, где bdaddr — bytes объект, содержащий Bluetooth-адрес в строчном формате. (например, b'12:23:34:45:56:67'). Этот протокол не поддерживается в FreeBSD.

• AF_ALG — интерфейс сокета для криптографии ядра, только для Linux. Алгоритмический сокет настраивается кортежем из двух-четырёх элементов (type, name [, feat [, mask]]), где:

  • type — тип алгоритма в виде строки, например aead, hash, skcipher или rng.
  • name — имя алгоритма и режим операции в виде строки, например sha256, hmac(sha256), cbc(aes) или drbg_nopr_ctr_aes256.
  • feat и mask — 32-битные беззнаковые целые числа.

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

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

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

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

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

• AF_PACKET — низкоуровневый интерфейс к сетевым устройствам напрямую. Пакеты представлены кортежем (ifname, proto[, pkttype[, hatype[, addr]]]), где:

  • ifname — строка, определяющая имя устройства.
  • proto — целое число в сетевом порядке байтов, определяющее номер протокола Ethernet.

  • pkttype — необязательное целое число, определяющее тип пакета:

    • PACKET_HOST (по умолчанию) — пакет, адресованный локальному хосту.
    • PACKET_BROADCAST — пакет физического уровня, отправленный в широковещательный режим.
    • PACKET_MULTIHOST — пакет, отправленный в физический многоадресную адресацию.
    • PACKET_OTHERHOST — пакет другому хосту, перехваченному драйвером устройства в режиме прослушивания всех пакетов.
    • PACKET_OUTGOING — пакет, отправленный с локального хоста, который возвращается обратно в сокет пакета.
  • hatype — необязательное целое число, определяющее тип аппаратного адреса ARP.
  • addr — необязательный объект, подобный байтам, определяющий физический аппаратный адрес, чья интерпретация зависит от устройства.

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

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

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

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

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

Исключения

exception socket.error

Устаревшее псевдоним для OSError.

Изменено в версии 3.3: Следуя PEP 3151, этот класс был переименован в псевдоним для OSError.

exception socket.herror

Подкласс OSError, это исключение генерируется для ошибок, связанных с адресом, т.е. для функций, которые используют h_errno в API POSIX C, включая gethostbyname_ex() и gethostbyaddr(). Сопутствующее значение является парой (h_errno, string) представляющей ошибку, возвращённую вызовом библиотеки. h_errno — это числовое значение, а string представляет описание h_errno, как возвращённое функцией 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

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

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

Константы

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

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, также определены в модуле сокетов. Они обычно используются в аргументах методов setsockopt() и getsockopt() объектов сокетов. В большинстве случаев определяются только те символы, которые определены в заголовочных файлах Unix; для некоторых символов предоставляются значения по умолчанию.

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

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

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

В Windows, TCP_KEEPIDLE, TCP_KEEPINTVL появляются, если в момент выполнения Windows поддерживает.

socket.AF_CAN

socket.PF_CAN

SOL_CAN_*

CAN_*

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

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

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

socket.CAN_BCM

CAN_BCM_*

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

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

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

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

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

socket.AF_PACKET

socket.PF_PACKET

PACKET_*

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

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

socket.AF_RDS

socket.PF_RDS

socket.SOL_RDS

RDS_*

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

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

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

socket.SIO_RCVALL

socket.SIO_KEEPALIVE_VALS

socket.SIO_LOOPBACK_FAST_PATH

RCVALL_*

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

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

TIPC_*

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

socket.AF_ALG

socket.SOL_ALG

ALG_*

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

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

Новая в версии 3.6.

socket.AF_VSOCK

socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID

VMADDR*

SO_VM*

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

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

Новая в версии 3.7.

socket.AF_LINK

Доступность: BSD, OSX.

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

socket.has_ipv6

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

socket.BDADDR_ANY

socket.BDADDR_LOCAL

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

socket.HCI_FILTER

socket.HCI_TIME_STAMP

socket.HCI_DATA_DIR

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

Функции

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

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

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

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

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

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

Изменено в версии 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.

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

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

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

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

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

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

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

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

socket.fromshare(data)

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

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

Введено в версии 3.3.

socket.SocketType

Это объект типа Python, представляющий тип объекта сокета. Он такой же, как type(socket(...)).

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

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

socket.close(fd)

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

Введено в версии 3.7.

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

Преобразует аргумент host/port в последовательность 5-кортежей, содержащих все необходимые аргументы для создания сокета, подключённого к этой службе. host — это доменное имя, строковое представление IPv4/v6-адреса или None. port — это стровое имя службы, например, 'http', числовой номер порта или None. Передав None в качестве значения для host и port, вы можете передать NULL в базовый 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 (кортеж из 2 элементов для AF_INET, кортеж из 4 элементов для AF_INET6), и он предназначен для передачи методу socket.connect().

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

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

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

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

socket.getfqdn([name])

Возвращает полное доменное имя для name. Если name опущено или пусто, оно интерпретируется как локальный хост. Для поиска полного имени проверяется имя хоста, возвращаемое функцией gethostbyaddr(), а затем псевдонимы хоста, если они доступны. Выбирается первое имя, которое включает точку. В случае отсутствия полного доменного имени возвращается имя хоста, возвращаемое функцией gethostname().

socket.gethostbyname(hostname)

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

socket.gethostbyname_ex(hostname)

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

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 в 2-кортеж (host, port). В зависимости от настроек flags, результат может содержать полное доменное имя или числовое представление адреса в host. Аналогично, port может содержать имя порта в виде строки или числовой номер порта.

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

socket.getprotobyname(protocolname)

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

socket.getservbyname(servicename[, protocolname])

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

socket.getservbyport(port[, protocolname])

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

socket.ntohl(x)

Преобразует 32-битные целые числа из сетевого порядка байтов в порядок байтов хоста. На машинах, где порядок байтов хоста совпадает с сетевым порядком байтов, это — ничто; в противном случае выполняется операция перестановки 4 байтов.

socket.ntohs(x)

Преобразует 16-битные целые числа из сетевого порядка байтов в порядок байтов хоста. На машинах, где порядок байтов хоста совпадает с сетевым порядком байтов, это — ничто; в противном случае выполняется операция перестановки 2 байтов.

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

socket.htonl(x)

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

socket.htons(x)

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

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

socket.inet_aton(ip_string)

Преобразует IPv4-адрес из строчного формата с точками (например, '123.45.67.89') в 32-битный упакованный двоичный формат в виде объекта bytes длиной в четыре символа. Это полезно при взаимодействии с программой, использующей стандартную библиотеку 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-адрес (объект bytes-подобный объект длиной в четыре байта) в его стандартное строковое представление с точками (например, '123.45.67.89'). Это полезно при взаимодействии с программой, использующей стандартную библиотеку C и требующей объекты типа struct in_addr, который является типом C для 32-битных упакованных двоичных данных, которые принимает эта функция.

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

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

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-адрес (объект bytes-подобный объект некоторой длины в байтах) в его стандартное семейно-специфическое строковое представление (например, '7.10.0.5' или '5aef:2b::8'). inet_ntop() полезна, когда библиотека или сетевой протокол возвращают объект типа struct in_addr (аналогично inet_ntoa()) или struct in6_addr.

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

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

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

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

socket.CMSG_LEN(length)

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

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

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

socket.CMSG_SPACE(length)

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

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

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

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

socket.getdefaulttimeout()

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

socket.setdefaulttimeout(timeout)

Устанавливает значение таймаута по умолчанию в секундах (float) для новых сокетов. При первом импорте модуля socket значение по умолчанию равно None. См. settimeout() для возможных значений и их значений.

socket.sethostname(name)

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

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

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

socket.if_nameindex()

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

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

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

socket.if_nametoindex(if_name)

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

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

Введено в версии 3.3.

socket.if_indextoname(if_index)

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

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

Введено в версии 3.3.

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

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

socket.accept()

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

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

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

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

socket.bind(address)

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

socket.close()

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

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

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

Примечание

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

socket.connect(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/v6, например. (Формат возвращаемого адреса зависит от семейства адресов — см. выше.) На некоторых системах эта функция не поддерживается.

socket.getsockname()

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

socket.getsockopt(level, optname[, buflen])

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

socket.getblocking()

Возвращает True если сокет в режиме блокировки, False если в режиме без блокировки.

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

Введено в версии 3.7.

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.

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

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

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

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

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

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

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

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # 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)

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

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

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

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

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

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

Пример:

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

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

Введено в версии 3.3.

socket.recvfrom_into(buffer[, nbytes[, flags]])

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

socket.recv_into(buffer[, nbytes[, flags]])

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

socket.send(bytes[, flags])

Отправка данных в сокет. Сокет должен быть подключен к удалённому сокету. Необязательный аргумент flags имеет такое же значение, как и для recv() выше. Возвращает количество отправленных байтов. Приложения отвечают за проверку того, что все данные были отправлены; если была передана только часть данных, приложению нужно попытаться доставить оставшиеся данные. Для дополнительной информации по этой теме, обратитесь к Руководству по программированию сокетов.

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

socket.sendall(bytes[, flags])

Отправка данных в сокет. Сокет должен быть подключен к удалённому сокету. Необязательный аргумент flags имеет такое же значение, как и для recv() выше. В отличие от send(), этот метод продолжает отправлять данные из bytes, пока все данные не будут отправлены или не произойдёт ошибка. None возвращается при успехе. При ошибке генерируется исключение, и нет способа определить, сколько данных, если таковые имеются, было успешно отправлено.

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

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

socket.sendto(bytes, address)

socket.sendto(bytes, flags, address)

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

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

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

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

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

import socket, array

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

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

Введено в версии 3.3.

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

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

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

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

Введено в версии 3.6.

socket.sendfile(file, offset=0, count=None)

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

Введено в версии 3.5.

socket.set_inheritable(inheritable)

Установить флаг наследуемости для дескриптора файла сокета или для дескриптора сокета.

Введено в версии 3.4.

socket.setblocking(flag)

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

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

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

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

socket.settimeout(value)

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

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

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

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

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

socket.setsockopt(level, optname, None, optlen: int)

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

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

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

socket.shutdown(how)

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

socket.share(process_id)

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

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

Введено в версии 3.3.

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

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

socket.family

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

socket.type

Тип сокета.

socket.proto

Протокол сокета.

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

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

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

Таймауты и метод 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 packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

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

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

Следующий пример показывает, как использовать интерфейс сокета для связи с сетью CAN, используя протокол сырых сокетов. Чтобы использовать CAN с протоколом управляющей шины вместо этого, откройте сокет с:

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

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

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

import socket
import struct


# CAN 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, без ожидания истечения его естественного таймаута.