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

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

Для введения в программирование сокетов (на C) см. следующие статьи: «An Introductory 4.3BSD Interprocess Communication Tutorial» (Стюарт Сечрест) и «An Advanced 4.3BSD Interprocess Communication Tutorial» (Сэмюэл Дж. Леффлер и др.), обе в UNIX Programmer’s Manual, Supplementary Documents 1 (разделы PS1:7 и PS1:8). Справочные материалы, специфичные для платформы, по различным системным вызовам сокетов также являются ценным источником информации о деталях семантики сокетов. Для Unix обратитесь к man-страницам; для Windows – к спецификации WinSock (или Winsock 2). Для API, поддерживающих IPv6, читателям рекомендуется обратиться к RFC 3493 под названием «Basic Socket Interface Extensions for IPv6».

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

Сокетные адреса представляются следующим образом: для семейства адресов 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 с областью действия. Другие семейства адресов в настоящее время не поддерживаются. Формат адреса, требуемый конкретным сокетным объектом, автоматически выбирается на основе семейства адресов, указанного при создании сокетного объекта.

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

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

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

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

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

exception socket.error¶

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

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

exception socket.herror¶

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

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

exception socket.gaierror¶

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

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

Если указан, source_address должен быть кортежем из двух элементов (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 будет строкой, представляющей каноническое имя хоста, если 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, вместо него для поддержки двойного стека IPv4/v6 следует использовать getaddrinfo().

socket.gethostbyname_ex(hostname)¶

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

socket.gethostname()¶

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

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

Новое в версии 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-битные положительные целые числа из сетевого порядка байтов в порядок байтов хоста. На машинах, где порядок байтов хоста совпадает с сетевым, эта функция ничего не делает; в противном случае она выполняет обмен двух байтов.

socket.htonl(x)¶

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

socket.htons(x)¶

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

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

socket.inet_ntoa(packed_ip)¶

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

Если переданная этой функции строка имеет длину не ровно 4 байта, будет вызвано исключение socket.error. Функция inet_ntoa() не поддерживает IPv6, для поддержки двух стеков IPv4/v6 вместо неё следует использовать 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 (возможно, не на всех платформах).

Новое в версии 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()¶

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

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

socket.setdefaulttimeout(timeout)¶

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

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

socket.SocketType¶

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

# Программа эхо-сервера
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 1:
    data = conn.recv(1024)
    if not data: break
    conn.sendall(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.sendall('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', repr(data)

# Программа эхо-сервера
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 1:
    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.sendall('Hello, world')
data = s.recv(1024)
s.close()
print 'Received', repr(data)

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)

socket.error: [Errno 98] Address already in use

s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((HOST, PORT))