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

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

Для введения в программирование сокетов (на C) обратитесь к следующим документам: Вводный учебник по межпроцессной связи 4.3BSD, автором которого является Стюарт Сехрест, и Расширенный учебник по межпроцессной связи 4.3BSD, авторами которого являются Сэмюэл Дж. Леффлер и др., оба из справочника UNIX Programmer’s Manual, Дополнительные документы 1 (разделы PS1:7 и PS1:8). Платформенно-специфичные справочные материалы для различных системных вызовов, связанных с сокетами, также являются ценным источником информации о деталях семантики сокетов. Для Unix обратитесь к страницам руководства; для Windows см. спецификацию WinSock (или Winsock 2). Для IPv6-совместимых API пользователи могут обратиться к RFC 3493 с названием «Основные расширения интерфейса сокета для IPv6».

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

Адреса сокетов представлены следующим образом: для семейства адресов AF_UNIX используется одна строка. Для семейства адресов AF_INET используется пара (host, port), где host — строка, представляющая либо имя хоста в обозначении доменной системы Интернета, например, 'daring.cwi.nl', либо IPv4-адрес, например, '100.50.200.5', а port — целое число. Для семейства адресов AF_INET6 используется четвёрка (host, port, flowinfo, scopeid), где flowinfo и scopeid представляют sin6_flowinfo и sin6_scope_id в C. Для методов модуля socket, flowinfo и scopeid могут быть опущены только для обеспечения обратной совместимости. Однако следует учесть, что опущение scopeid может привести к проблемам при работе со scoped IPv6-адресами. Другие семейства адресов в настоящее время не поддерживаются. Формат адреса, требуемый конкретным объектом сокета, автоматически выбирается на основе семейства адресов, указанного при создании объекта сокета.

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

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

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

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

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

exception socket.error

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

Изменено в версии 2.6: socket.error теперь является дочерним классом IOError.

exception socket.herror

Это исключение возникает при ошибках, связанных с адресами, т.е. для функций, использующих h_errno в API C, включая 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”.

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

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_*

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

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

TIPC_*

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

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

socket.has_ipv6

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

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

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) для привязки сокета к его исходному адресу перед подключением. Если хост или порт равны ‘’ или 0 соответственно, будет использоваться поведение по умолчанию операционной системы.

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

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

socket.getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])

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

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

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

(family, socktype, proto, canonname, sockaddr)

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

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

>>> socket.getaddrinfo("example.org", 80, 0, 0, socket.IPPROTO_TCP)
[(10, 1, 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (2, 1, 6, '', ('93.184.216.34', 80))]

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

socket.getfqdn([name])

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

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

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.

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

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

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.

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

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

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

socket.ntohl(x)

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

socket.ntohs(x)

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

socket.htonl(x)

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

socket.htons(x)

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

socket.inet_aton(ip_string)

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

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

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

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

socket.inet_ntoa(packed_ip)

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

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

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 (возможно, не на всех платформах).

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

socket.inet_ntop(address_family, packed_ip)

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

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

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

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

socket.getdefaulttimeout()

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

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

socket.setdefaulttimeout(timeout)

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

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

socket.SocketType

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

1. Объекты сокета

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

socket.accept()

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

socket.bind(address)

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

Примечание

Этот метод исторически принимал пару параметров для адресов AF_INET вместо только кортежа. Это никогда не было намерением и больше недоступно в Python 2.0 и более поздних версиях.

socket.close()

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

Примечание

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

socket.connect(address)

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

Примечание

Этот метод исторически принимал пару параметров для адресов AF_INET вместо только кортежа. Это никогда не было намерением и больше недоступно в Python 2.0 и более поздних версиях.

socket.connect_ex(address)

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

Примечание

Этот метод исторически принимал пару параметров для адресов AF_INET вместо только кортежа. Это никогда не было намерением и больше недоступно в Python 2.0 и более поздних версиях.

socket.fileno()

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

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

socket.getpeername()

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

socket.getsockname()

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

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

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

socket.ioctl(control, option)

Платформа

Windows

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

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

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

socket.listen(backlog)

Прослушивать подключения, сделанные к сокету. Аргумент backlog указывает максимальное количество подключений в очереди и должен быть не меньше 0; максимальное значение зависит от системы (обычно 5), минимальное значение принудительно устанавливается в 0.

socket.makefile([mode[, bufsize]])

Возвращает объект файла file object, связанный с сокетом. (Объекты файлов описаны в Объекты файлов.) Объект файла не закрывает сокет явно при вызове его метода close(), а только удаляет свою ссылку на объект сокета, так что сокет будет закрыт, если он нигде больше не ссылается.

Сокет должен быть в режиме блокировки (у него не может быть таймаута). Необязательные аргументы mode и bufsize интерпретируются так же, как и встроенной функцией file().

Примечание

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

socket.recv(bufsize[, flags])

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

Примечание

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

socket.recvfrom(bufsize[, flags])

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

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

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

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

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

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

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

socket.send(string[, flags])

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

socket.sendall(string[, flags])

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

socket.sendto(string, address)

socket.sendto(string, flags, address)

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

socket.setblocking(flag)

Установить режим сокета: блокирующий или неблокирующий. Если flag равен 0, сокет переводится в неблокирующий режим, иначе — в блокирующий. Изначально все сокеты находятся в блокирующем режиме. В неблокирующем режиме, если вызов recv() не находит данных или вызов send() не может немедленно обработать данные, возникает исключение error; в блокирующем режиме вызовы блокируются до тех пор, пока не смогут продолжить работу. s.setblocking(0) эквивалентно s.settimeout(0.0); s.setblocking(1) эквивалентно s.settimeout(None).

socket.settimeout(value)

Установить таймаут для блокирующих операций с сокетом. Аргумент value может быть неотрицательным числом с плавающей точкой, представляющим секунды, или None. Если задано число с плавающей точкой, последующие операции с сокетом вызовут исключение timeout, если период таймаута value истечёт, прежде чем операция завершится. Установка таймаута None отключает таймауты для операций с сокетом. s.settimeout(0.0) эквивалентно s.setblocking(0); s.settimeout(None) эквивалентно s.setblocking(1).

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

socket.gettimeout()

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

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

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

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

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

socket.setsockopt(level, optname, value)

Установить значение заданного параметра сокета (см. страницу руководства Unix setsockopt(2)). Необходимые символьные константы определены в модуле socket (SO_* и т. д.). Значение может быть целым числом или строкой, представляющей буфер. В последнем случае вызывающая сторона должна обеспечить, что строка содержит правильные биты (см. необязательный встроенный модуль 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

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

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

socket.type

Тип сокета.

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

socket.proto

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

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

2. Пример

Вот четыре минимальных примера программ с использованием протокола 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
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 1:
    data = conn.recv(1024)
    if not data: break
    conn.sendall(data)
conn.close()

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.connect((HOST, PORT))
s.sendall('Hello, world')
data = s.recv(1024)
s.close()
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 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 1:
    data = conn.recv(1024)
    if not data: break
    conn.send(data)
conn.close()

# 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 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.sendall('Hello, world')
data = s.recv(1024)
s.close()
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)

Запуск примера несколько раз с слишком маленькой задержкой между запусками может привести к этой ошибке:

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