socket — Интерфейс низкого уровня для сетевых соединений

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

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

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

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

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

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

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

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

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

• Пара (host, port) используется для семейства адресов AF_INET, где host — строка, представляющая имя хоста в обозначении интернет-домена, например, 'daring.cwi.nl', или IPv4-адрес, например, '100.50.200.5', а port — целое число.

  • Для IPv4-адресов принимаются две специальные формы вместо адреса хоста: '' представляет INADDR_ANY, что используется для привязки ко всем интерфейсам, и строка '<broadcast>' представляет INADDR_BROADCAST. Это поведение несовместимо с IPv6, поэтому следует избегать его, если вы планируете поддерживать IPv6 в своих программах Python.
• Для семейства адресов AF_INET6 используется четвёрка (host, port, flowinfo, scopeid), где flowinfo и scopeid представляют члены sin6_flowinfo и sin6_scope_id в struct sockaddr_in6 на C. Для методов модуля socket члены flowinfo и scopeid могут быть опущены исключительно для совместимости со старыми версиями. Тем не менее, пропуск scopeid может вызвать проблемы при манипулировании скопированными IPv6-адресами.
• 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'. Имя сетевого интерфейса '' может использоваться для приема пакетов со всех сетевых интерфейсов этого семейства.

• Строка или кортеж (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. Исключения

exception socket.error

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

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

exception socket.herror

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

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

exception socket.gaierror

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

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

exception socket.timeout

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

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

18.1.2.2. Константы

Константы 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.

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

socket.PF_PACKET

PACKET_*

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

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

socket.AF_RDS

socket.PF_RDS

socket.SOL_RDS

RDS_*

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

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

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

Если указан source_address, он должен быть кортежем из 2 элементов (host, port) для привязки сокета к нему в качестве адреса источника перед подключением. Если host или порт равны '' или 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(...)).

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 (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: параметры теперь можно передавать с помощью именованных аргументов.

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 может содержать имя порта в виде строки или числовой номер порта.

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 байтов.

socket.htonl(x)

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

socket.htons(x)

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

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

socket.inet_ntoa(packed_ip)

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

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

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

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

socket.setdefaulttimeout(timeout)

Устанавливает значение таймаута по умолчанию в секундах (вещественное число) для новых сокетов. При первом импорте модуля 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.

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

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

socket.accept()

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

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

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

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

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() (другие проблемы, такие как «хост не найден», всё ещё могут вызывать исключения). Индикатор ошибки — 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.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 для обоснования).

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.fromstring(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 вместо создания новой строки bytes. Возвращаемое значение — пара (nbytes, address), где nbytes — количество полученных байт, а address — адрес сокета, отправившего данные. Значение необязательного аргумента flags см. в странице руководства Unix recv(2); по умолчанию он равен нулю. (Формат address зависит от семейства адресов — см. выше.)

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

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

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-подобных объектов (например, объектов bytes); операционная система может установить ограничение (sysconf() значение SC_IOV_MAX) на количество используемых буферов. Аргумент ancdata указывает дополнительные данные (управляющие сообщения) как итерируемый объект нуля или более кортежей (cmsg_level, cmsg_type, cmsg_data), где cmsg_level и cmsg_type — целые числа, определяющие уровень протокола и тип, специфичный для протокола соответственно, а cmsg_data — bytes-подобный объект, содержащий связанные данные. Обратите внимание, что некоторые системы (в частности, системы без 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)

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

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

socket.set_inheritable(inheritable)

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

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

socket.setblocking(flag)

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

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

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

socket.settimeout(value)

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

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

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-структур в строки байтов). Когда значение устанавливается в 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

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

18.1.4. Замечания о тайм-аутах сокета

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

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

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.

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