17.2. socket – Низкоуровневый сетевой интерфейс¶socket – Low-level networking interface

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

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

Адреса сокетов представляются следующим образом:

• Для семейства адресов AF_UNIX используется одна строка.

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

• Для семейства адресов AF_INET6 используется четырехэлементный кортеж (host, port, flowinfo, scopeid), где flowinfo и scopeid представляют собой поля sin6_flowinfo и sin6_scope_id в структуре struct sockaddr_in6 на языке C. Для методов модуля socket, flowinfo и scopeid могут быть опущены только для обратной совместимости. Однако обратите внимание, что пропуск scopeid может вызвать проблемы при работе с адресами IPv6 с областью действия (scoped).

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

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

  • addr_type – одно из значений TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME или TIPC_ADDR_ID.

  • scope – одно из значений TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE и TIPC_NODE_SCOPE.

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

    Если addr_type равно TIPC_ADDR_NAMESEQ, то v1 – это тип сервера, v2 – нижний номер порта, а v3 – верхний номер порта.

    Если addr_type равно TIPC_ADDR_ID, то v1 – это узел, v2 – ссылка (reference), а v3 должно быть установлено в 0.

    Если addr_type равно TIPC_ADDR_ID, то v1 – это узел, v2 – ссылка (reference), а v3 должно быть установлено в 0.

• Некоторые другие семейства адресов (AF_BLUETOOTH, AF_PACKET) поддерживают особые представления.

Для IPv4-адресов вместо адреса хоста принимаются две специальные формы: пустая строка обозначает INADDR_ANY, а строка '<broadcast>' обозначает INADDR_BROADCAST. Такое поведение несовместимо с IPv6, поэтому от этих форм лучше отказаться, если планируется поддержка IPv6 в программах на Python.

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

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

Неподдерживаемый режим поддерживается через setblocking(). Более общий подход на основе тайм-аутов поддерживается через settimeout().

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

Модуль socket экспортирует следующие константы и функции:

exception socket.error¶

Это исключение возникает при ошибках, связанных с сокетами. Сопутствующее значение – либо строка с описанием ошибки, либо пара (errno, string), представляющая ошибку, возвращенную системным вызовом, аналогично значению, сопутствующему os.error. См. модуль errno, который содержит имена для кодов ошибок, определенных базовой операционной системой.

exception socket.herror¶

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

Сопутствующее значение – это пара (h_errno, string), представляющая ошибку, возвращенную библиотечным вызовом. string представляет описание h_errno, как возвращено функцией hstrerror() языка C.

exception socket.gaierror¶

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

exception socket.timeout¶

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

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

SO_*

socket.SOMAXCONN¶

MSG_*

SOL_*

IPPROTO_*

IPPORT_*

INADDR_*

IP_*

IPV6_*

EAI_*

AI_*

NI_*

TCP_*

Многие константы этих форм, описанные в документации Unix по сокетам и/или протоколу IP, также определены в модуле socket. Они обычно используются в аргументах методов setsockopt() и getsockopt() объектов сокетов. В большинстве случаев определены только те символы, которые есть в заголовочных файлах Unix; для некоторых символов заданы значения по умолчанию.

SIO_*

RCVALL_*

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

TIPC_*

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

socket.has_ipv6¶

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

socket.create_connection(address[, timeout])¶

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

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

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

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

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

(family, socktype, proto, canonname, sockaddr)

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

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

>>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP)
[(2, 1, 6, '', ('82.94.164.162', 80)),
 (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]

socket.getfqdn([name])¶

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

socket.gethostbyname(hostname)¶

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

socket.gethostbyname_ex(hostname)¶

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

socket.gethostname()¶

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

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

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

socket.gethostbyaddr(ip_address)¶

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

socket.getnameinfo(sockaddr, flags)¶

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

socket.getprotobyname(protocolname)¶

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

socket.getservbyname(servicename[, protocolname])¶

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

socket.getservbyport(port[, protocolname])¶

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

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

Создаёт новый сокет с заданным семейством адресов, типом сокета и номером протокола. Семейство адресов должно быть AF_INET (по умолчанию), AF_INET6 или AF_UNIX. Тип сокета должен быть SOCK_STREAM (по умолчанию), SOCK_DGRAM или, возможно, одна из констант SOCK_. Номер протокола обычно равен нулю и в этом случае может быть опущен.

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

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

socket.fromfd(fd, family, type[, proto])¶

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

socket.ntohl(x)¶

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

socket.ntohs(x)¶

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

socket.htonl(x)¶

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

socket.htons(x)¶

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

socket.inet_aton(ip_string)¶

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

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

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

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

socket.inet_ntoa(packed_ip)¶

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

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

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 недействительна, возбуждается socket.error. Имейте в виду, что точное определение допустимости зависит как от значения address_family, так и от реализации inet_pton().

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

socket.inet_ntop(address_family, packed_ip)¶

Convert a packed IP address (a bytes object of some number of characters) to its standard, family-specific string representation (for example, '7.10.0.5' or '5aef:2b::8'). inet_ntop() is useful when a library or network protocol returns an object of type struct in_addr (similar to inet_ntoa()) or struct in6_addr.

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

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

socket.getdefaulttimeout()¶

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

socket.setdefaulttimeout(timeout)¶

Устанавливает таймаут по умолчанию в секундах с плавающей запятой для новых объектов сокета. При первом импорте модуля socket значение по умолчанию – None. Информацию о возможных значениях и их смысле см. в settimeout().

socket.SocketType¶

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

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

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

socket.accept()¶

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

socket.bind(address)¶

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

socket.close()¶

Закрывает сокет. Все последующие операции с объектом сокета будут завершаться ошибкой. Удаленная сторона не получит больше данных (после сброса находящихся в очереди данных). Сокеты автоматически закрываются при сборке мусора.

Примечание

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

socket.connect(address)¶

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

socket.connect_ex(address)¶

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

socket.fileno()¶

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

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

socket.getpeername()¶

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

socket.getsockname()¶

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

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

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

socket.gettimeout()¶

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

socket.ioctl(control, option)¶

Платформа:	Windows

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

On other platforms, the generic fcntl.fcntl() and fcntl.ioctl() functions may be used; they accept a socket object as their first argument.

socket.listen(backlog)¶

Ожидает подключения к сокету. Аргумент backlog задаёт максимальное количество ожидающих соединений в очереди и должен быть не менее 1; максимальное значение зависит от системы (обычно 5).

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

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

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

Примечание

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

socket.recv(bufsize[, flags])¶

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

Примечание

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

socket.recvfrom(bufsize[, flags])¶

Receive data from the socket. The return value is a pair (bytes, address) where bytes is a bytes object representing the data received and address is the address of the socket sending the data. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero. (The format of address depends on the address family – see above.)

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

Receive data from the socket, writing it into buffer instead of creating a new bytestring. The return value is a pair (nbytes, address) where nbytes is the number of bytes received and address is the address of the socket sending the data. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero. (The format of address depends on the address family – see above.)

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

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

socket.send(bytes[, flags])¶

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

socket.sendall(bytes[, flags])¶

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

socket.sendto(bytes[, flags], address)¶

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

socket.setblocking(flag)¶

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

Этот метод является сокращением для некоторых вызовов 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)¶

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

socket.shutdown(how)¶

Завершает одну или обе половины соединения. Если how равно SHUT_RD, дальнейший приём данных запрещён. Если how равно SHUT_WR, дальнейшая отправка данных запрещена. Если how равно SHUT_RDWR, дальнейшие отправка и приём данных запрещены. В зависимости от платформы завершение одной половины соединения может также закрыть противоположную половину (например, на Mac OS X shutdown(SHUT_WR) не позволяет выполнять чтение на другом конце соединения).

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

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

socket.family¶

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

socket.type¶

Тип сокета.

socket.proto¶

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

17.2.4. Замечания о тайм-аутах сокетов¶Notes on socket timeouts

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

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

17.2.5. Пример¶Example

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

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

# Программа эхо-сервера
import socket

HOST = ''                 # Символическое имя, обозначающее все доступные интерфейсы
PORT = 50007              # Произвольный непривилегированный порт
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.bind((HOST, PORT))
s.listen(1)
conn, addr = s.accept()
print('Connected by', addr)
while True:
    data = conn.recv(1024)
    if not data: break
    conn.send(data)
conn.close()

# Программа эхо-клиента
import socket

HOST = 'daring.cwi.nl'    # Удалённый хост
PORT = 50007              # Тот же порт, что и у сервера
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
s.send(b'Hello, world')
data = s.recv(1024)
s.close()
print('Received', repr(data))

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

# Программа эхо-сервера
import socket
import sys

HOST = None               # Символическое имя, обозначающее все доступные интерфейсы
PORT = 50007              # Произвольный непривилегированный порт
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except socket.error as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except socket.error as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
print('Connected by', addr)
while True:
    data = conn.recv(1024)
    if not data: break
    conn.send(data)
conn.close()

# Программа эхо-клиента
import socket
import sys

HOST = 'daring.cwi.nl'    # Удалённый хост
PORT = 50007              # Тот же порт, что и у сервера
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except socket.error as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except socket.error as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
s.send(b'Hello, world')
data = s.recv(1024)
s.close()
print('Received', repr(data))

Последний пример показывает, как написать очень простой сетевой сниффер с помощью сырых сокетов в Windows. Для выполнения примера требуются права администратора для изменения интерфейса:

import socket

# общедоступный сетевой интерфейс
HOST = socket.gethostbyname(socket.gethostname())

# создать сырой сокет и привязать его к общедоступному интерфейсу
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Включать IP-заголовки
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# принять все пакеты
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# принять пакет
print(s.recvfrom(65565))

# неразборчивый режим отключён
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)