`socket.md`

1094 строк · 63.8 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.1/library/socket.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 17.2. `socket` – Низкоуровневый сетевой интерфейс89Этот модуль предоставляет доступ к интерфейсу BSD *socket*. Он доступен во всех современных Unix-системах, Windows, MacOS, OS/2 и, вероятно, на других платформах.1011> **Примечание**12>13> Некоторые аспекты поведения могут зависеть от платформы, поскольку вызовы выполняются через API сокетов операционной системы.1415Интерфейс Python представляет собой прямую трансляцию системных вызовов и библиотечного интерфейса сокетов Unix в объектно-ориентированном стиле Python: функция [`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket) возвращает *объект сокета*, методы которого реализуют различные системные вызовы сокетов. Типы параметров находятся на более высоком уровне, чем в интерфейсе C: как и при операциях `read()` и `write()` с файлами Python, выделение буфера при приёме происходит автоматически, а длина буфера при отправке подразумевается неявно.1617> **См. также**18>19> **Модуль [`socketserver`](https://python-all.ru/3.1/library/socketserver.html#module-socketserver)**20>21> Классы, упрощающие написание сетевых серверов.22>23> **Модуль [`ssl`](https://python-all.ru/3.1/library/ssl.html#module-ssl)**24>25> Обёртка TLS/SSL для объектов сокетов.2627## 17.2.1. Семейства сокетов2829В зависимости от системы и параметров сборки этим модулем поддерживаются различные семейства сокетов.3031Адреса сокетов представляются следующим образом:3233- Для семейства адресов [`AF_UNIX`](https://python-all.ru/3.1/library/socket.html#socket.AF_UNIX) используется одна строка.34- Пара `(host, port)` используется для семейства адресов [`AF_INET`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET), где *host* – строка, представляющая либо имя хоста в доменной нотации Интернета, например `'daring.cwi.nl'`, либо IPv4-адрес, например `'100.50.200.5'`, а *port* – целочисленный номер порта.35- Для семейства адресов [`AF_INET6`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET6) используется четырехэлементный кортеж `(host, port, flowinfo, scopeid)`, где *flowinfo* и *scopeid* представляют собой поля `sin6_flowinfo` и `sin6_scope_id` в структуре `struct sockaddr_in6` на языке C. Для методов модуля `socket`, *flowinfo* и *scopeid* могут быть опущены только для обратной совместимости. Однако обратите внимание, что пропуск *scopeid* может вызвать проблемы при работе с адресами IPv6 с областью действия (scoped).36- Сокеты `AF_NETLINK` представляются в виде пар `(pid, groups)`.37- Поддержка TIPC только для Linux доступна с использованием семейства адресов `AF_TIPC`. TIPC – это открытый сетевой протокол, не основанный на IP, предназначенный для использования в кластерных вычислительных средах. Адреса представляются в виде кортежа, и поля зависят от типа адреса. Общая форма кортежа: `(addr_type, v1, v2, v3 [, scope])`, где:3839  - *addr\_type* – одно из значений TIPC\_ADDR\_NAMESEQ, TIPC\_ADDR\_NAME или TIPC\_ADDR\_ID.40  - *scope* – одно из значений TIPC\_ZONE\_SCOPE, TIPC\_CLUSTER\_SCOPE и TIPC\_NODE\_SCOPE.41  - Если *addr\_type* равно TIPC\_ADDR\_NAME, то *v1* – это тип сервера, *v2* – идентификатор порта, а *v3* должно быть 0.4243    Если *addr\_type* равно TIPC\_ADDR\_NAMESEQ, то *v1* – это тип сервера, *v2* – нижний номер порта, а *v3* – верхний номер порта.4445    Если *addr\_type* равно TIPC\_ADDR\_ID, то *v1* – это узел, *v2* – ссылка (reference), а *v3* должно быть установлено в 0.4647    Если *addr\_type* равно TIPC\_ADDR\_ID, то *v1* – это узел, *v2* – ссылка (reference), а *v3* должно быть установлено в 0.48- Некоторые другие семейства адресов (`AF_BLUETOOTH`, `AF_PACKET`) поддерживают особые представления.4950Для IPv4-адресов вместо адреса хоста принимаются две специальные формы: пустая строка обозначает `INADDR_ANY`, а строка `'<broadcast>'` обозначает `INADDR_BROADCAST`. Такое поведение несовместимо с IPv6, поэтому от этих форм лучше отказаться, если планируется поддержка IPv6 в программах на Python.5152Если в части *узел* адреса сокета IPv4/v6 указано имя узла, программа может демонстрировать недетерминированное поведение, так как Python использует первый адрес, возвращённый при разрешении DNS. Адрес сокета будет разрешаться по-разному в фактический IPv4/v6-адрес в зависимости от результатов разрешения DNS и/или конфигурации узла. Для детерминированного поведения используйте числовой адрес в части *узел*.5354Все ошибки возбуждают исключения. Обычные исключения для недопустимых типов аргументов и нехватки памяти могут быть возбуждены; ошибки, связанные с семантикой сокета или адреса, возбуждают [`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error) или один из его подклассов.5556Неподдерживаемый режим поддерживается через [`setblocking()`](https://python-all.ru/3.1/library/socket.html#socket.socket.setblocking). Более общий подход на основе тайм-аутов поддерживается через [`settimeout()`](https://python-all.ru/3.1/library/socket.html#socket.socket.settimeout).5758## 17.2.2. Содержимое модуля5960Модуль `socket` экспортирует следующие константы и функции:6162#### `exception socket.error`6364Это исключение возникает при ошибках, связанных с сокетами. Сопутствующее значение – либо строка с описанием ошибки, либо пара `(errno, string)`, представляющая ошибку, возвращенную системным вызовом, аналогично значению, сопутствующему [`os.error`](https://python-all.ru/3.1/library/os.html#os.error). См. модуль [`errno`](https://python-all.ru/3.1/library/errno.html#module-errno), который содержит имена для кодов ошибок, определенных базовой операционной системой.6566#### `exception socket.herror`6768Это исключение возникает при ошибках, связанных с адресами, т.е. для функций, использующих *h\_errno* в C API, включая [`gethostbyname_ex()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyname_ex) и [`gethostbyaddr()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyaddr).6970Сопутствующее значение – это пара `(h_errno, string)`, представляющая ошибку, возвращенную библиотечным вызовом. *string* представляет описание *h\_errno*, как возвращено функцией `hstrerror()` языка C.7172#### `exception socket.gaierror`7374Это исключение возникает при ошибках, связанных с адресами, для7576[`getaddrinfo()`](https://python-all.ru/3.1/library/socket.html#socket.getaddrinfo)7778и7980[`getnameinfo()`](https://python-all.ru/3.1/library/socket.html#socket.getnameinfo)8182. Сопутствующее значение – это пара8384`(error, string)`8586, представляющая ошибку, возвращенную библиотечным вызовом.8788*string*8990представляет описание9192*error*9394, как возвращено функцией9596`gai_strerror()`9798языка C. Значение99100*error*101102будет соответствовать одной из констант103104`EAI_*`105106, определенных в этом модуле.107108#### `exception socket.timeout`109110Это исключение возникает при тайм-ауте на сокете, для которого тайм-ауты были включены предшествующим вызовом111112[`settimeout()`](https://python-all.ru/3.1/library/socket.html#socket.socket.settimeout)113114. Сопутствующее значение – это строка, которая в настоящее время всегда равна «timed out».115116#### `socket.AF_UNIX`117118#### `socket.AF_INET`119120#### `socket.AF_INET6`121122Эти константы представляют семейства адресов (и протоколов), используемые для первого аргумента123124[`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket)125126. Если константа127128[`AF_UNIX`](https://python-all.ru/3.1/library/socket.html#socket.AF_UNIX)129130не определена, то этот протокол не поддерживается. В зависимости от системы могут быть доступны дополнительные константы.131132#### `socket.SOCK_STREAM`133134#### `socket.SOCK_DGRAM`135136#### `socket.SOCK_RAW`137138#### `socket.SOCK_RDM`139140#### `socket.SOCK_SEQPACKET`141142Эти константы представляют типы сокетов, используемые для второго аргумента143144[`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket)145146. В зависимости от системы могут быть доступны дополнительные константы. (Обычно полезными считаются только147148[`SOCK_STREAM`](https://python-all.ru/3.1/library/socket.html#socket.SOCK_STREAM)149150и151152[`SOCK_DGRAM`](https://python-all.ru/3.1/library/socket.html#socket.SOCK_DGRAM)153154.)155156#### `SO_*`157158#### `socket.SOMAXCONN`159160#### `MSG_*`161162#### `SOL_*`163164#### `IPPROTO_*`165166#### `IPPORT_*`167168#### `INADDR_*`169170#### `IP_*`171172#### `IPV6_*`173174#### `EAI_*`175176#### `AI_*`177178#### `NI_*`179180#### `TCP_*`181182Многие константы этих форм, описанные в документации Unix по сокетам и/или протоколу IP, также определены в модуле socket. Они обычно используются в аргументах методов183184`setsockopt()`185186и187188`getsockopt()`189190объектов сокетов. В большинстве случаев определены только те символы, которые есть в заголовочных файлах Unix; для некоторых символов заданы значения по умолчанию.191192#### `SIO_*`193194#### `RCVALL_*`195196Константы для WSAIoctl() в Windows. Используются как аргументы метода197198`ioctl()`199200объектов сокетов.201202#### `TIPC_*`203204Константы, связанные с TIPC, соответствующие тем, что экспортируются C API сокетов. Дополнительную информацию см. в документации TIPC.205206#### `socket.has_ipv6`207208Эта константа содержит логическое значение, указывающее, поддерживается ли IPv6 на данной платформе.209210#### `socket.create_connection(address[, timeout])`211212Вспомогательная функция. Подключается к213214*address*215216(кортеж из двух элементов217218`(host, port)`219220) и возвращает объект сокета. Передача необязательного параметра221222*timeout*223224устанавливает тайм-аут для экземпляра сокета перед попыткой подключения. Если225226*timeout*227228не указан, используется глобальная настройка тайм-аута по умолчанию, возвращаемая229230[`getdefaulttimeout()`](https://python-all.ru/3.1/library/socket.html#socket.getdefaulttimeout)231232.233234#### `socket.getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0)`235236Преобразует аргументы *host*/*port* в последовательность кортежей из 5 элементов, содержащих все необходимые аргументы для создания сокета, подключённого к этой службе. *host* – это доменное имя, строковое представление IPv4/v6-адреса или `None`. *port* – это строковое имя службы, например `'http'`, числовой номер порта или `None`. Передавая `None` в качестве значения *host* и *port*, можно передать `NULL` в нижележащий C API.237238Аргументы *family*, *socktype* и *proto* можно необязательно указать, чтобы сузить список возвращаемых адресов. Если передать ноль в качестве значения для каждого из этих аргументов, будут выбраны все возможные результаты. Аргумент *flags* может быть одной или несколькими константами `AI_*` и влияет на то, как вычисляются и возвращаются результаты. Например, `AI_NUMERICHOST` отключает разрешение доменных имён и вызывает ошибку, если *host* является доменным именем.239240Функция возвращает список кортежей из 5 элементов со следующей структурой:241242`(family, socktype, proto, canonname, sockaddr)`243244В этих кортежах *family*, *socktype* и *proto* – целые числа, и их следует передавать функции [`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket). *canonname* будет строкой, представляющей каноническое имя узла *host*, если `AI_CANONNAME` входит в аргумент *flags*; в противном случае *canonname* будет пустой строкой. *sockaddr* – это кортеж, описывающий адрес сокета; его формат зависит от возвращённого *family* (двухэлементный кортеж `(address, port)` для [`AF_INET`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET), четырёхэлементный кортеж `(address, port, flow info, scope id)` для [`AF_INET6`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET6)). Этот кортеж предназначен для передачи методу [`socket.connect()`](https://python-all.ru/3.1/library/socket.html#socket.socket.connect).245246Следующий пример получает информацию об адресе для гипотетического TCP-соединения к `www.python.org` на порту 80 (на вашей системе результаты могут отличаться, если IPv6 не включён):247248```python249>>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP)250[(2, 1, 6, '', ('82.94.164.162', 80)),251 (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]252```253254#### `socket.getfqdn([name])`255256Возвращает полное доменное имя для257258*name*259260. Если261262*name*263264опущен или пуст, он интерпретируется как локальный хост. Чтобы найти полное имя, проверяется имя хоста, возвращённое265266[`gethostbyaddr()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyaddr)267268, а затем, при наличии, псевдонимы хоста. Выбирается первое имя, содержащее точку. Если полное доменное имя недоступно, возвращается имя хоста, полученное через269270[`gethostname()`](https://python-all.ru/3.1/library/socket.html#socket.gethostname)271272.273274#### `socket.gethostbyname(hostname)`275276Преобразует имя хоста в формат IPv4-адреса. IPv4-адрес возвращается в виде строки, например277278`'100.50.200.5'`279280. Если само имя хоста является IPv4-адресом, оно возвращается без изменений. См.281282[`gethostbyname_ex()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyname_ex)283284для более полного интерфейса.285286[`gethostbyname()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyname)287288не поддерживает разрешение имён IPv6, поэтому для поддержки dual stack IPv4/v6 следует использовать289290[`getaddrinfo()`](https://python-all.ru/3.1/library/socket.html#socket.getaddrinfo)291292.293294#### `socket.gethostbyname_ex(hostname)`295296Преобразует имя хоста в формат IPv4-адреса, расширенный интерфейс. Возвращает тройку297298`(hostname, aliaslist, ipaddrlist)`299300, где301302*hostname*303304– основное имя хоста, отвечающего на заданный305306*ip\_address*307308,309310*aliaslist*311312– (возможно, пустой) список альтернативных имён хоста для того же адреса, а313314*ipaddrlist*315316– список IPv4-адресов того же интерфейса на том же хосте (часто, но не всегда, один адрес).317318[`gethostbyname_ex()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyname_ex)319320не поддерживает разрешение имён IPv6, поэтому для поддержки dual stack IPv4/v6 следует использовать321322[`getaddrinfo()`](https://python-all.ru/3.1/library/socket.html#socket.getaddrinfo)323324.325326#### `socket.gethostname()`327328Возвращает строку, содержащую имя хоста машины, на которой в данный момент выполняется интерпретатор Python.329330Если нужно узнать IP-адрес текущей машины, можно использовать `gethostbyname(gethostname())`. Эта операция предполагает, что существует корректное отображение адреса на хост, и это предположение выполняется не всегда.331332Примечание: [`gethostname()`](https://python-all.ru/3.1/library/socket.html#socket.gethostname) не всегда возвращает полное доменное имя; используйте `getfqdn()` (см. выше).333334#### `socket.gethostbyaddr(ip_address)`335336Возвращает тройку337338`(hostname, aliaslist, ipaddrlist)`339340, где341342*hostname*343344– основное имя хоста, отвечающего на заданный345346*ip\_address*347348,349350*aliaslist*351352– (возможно, пустой) список альтернативных имён хоста для того же адреса, а353354*ipaddrlist*355356– список IPv4/v6-адресов того же интерфейса на том же хосте (скорее всего, содержащий только один адрес). Чтобы найти полное доменное имя, используйте функцию357358[`getfqdn()`](https://python-all.ru/3.1/library/socket.html#socket.getfqdn)359360.361362[`gethostbyaddr()`](https://python-all.ru/3.1/library/socket.html#socket.gethostbyaddr)363364поддерживает как IPv4, так и IPv6.365366#### `socket.getnameinfo(sockaddr, flags)`367368Преобразует адрес сокета369370*sockaddr*371372в кортеж из двух элементов373374`(host, port)`375376. В зависимости от настроек377378*flags*379380результат может содержать полное доменное имя или числовое представление адреса в381382*host*383384. Аналогично,385386*port*387388может содержать строковое имя порта или числовой номер порта.389390#### `socket.getprotobyname(protocolname)`391392Преобразует имя интернет-протокола (например,393394`'icmp'`395396) в константу, пригодную для передачи в качестве (необязательного) третьего аргумента функции397398[`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket)399400. Обычно это требуется только для сокетов, открытых в «сыром» режиме (401402[`SOCK_RAW`](https://python-all.ru/3.1/library/socket.html#socket.SOCK_RAW)403404); для обычных режимов сокета правильный протокол выбирается автоматически, если протокол опущен или равен нулю.405406#### `socket.getservbyname(servicename[, protocolname])`407408Преобразует имя интернет-службы и имя протокола в номер порта для этой службы. Необязательное имя протокола, если указано, должно быть409410`'tcp'`411412или413414`'udp'`415416, в противном случае подойдёт любой протокол.417418#### `socket.getservbyport(port[, protocolname])`419420Преобразует номер порта и имя протокола в имя службы для этой службы. Необязательное имя протокола, если указано, должно быть421422`'tcp'`423424или425426`'udp'`427428, иначе подойдет любой протокол.429430#### `socket.socket([family[, type[, proto]]])`431432Создаёт новый сокет с заданным семейством адресов, типом сокета и номером протокола. Семейство адресов должно быть433434[`AF_INET`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET)435436(по умолчанию),437438[`AF_INET6`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET6)439440или441442[`AF_UNIX`](https://python-all.ru/3.1/library/socket.html#socket.AF_UNIX)443444. Тип сокета должен быть445446[`SOCK_STREAM`](https://python-all.ru/3.1/library/socket.html#socket.SOCK_STREAM)447448(по умолчанию),449450[`SOCK_DGRAM`](https://python-all.ru/3.1/library/socket.html#socket.SOCK_DGRAM)451452или, возможно, одна из констант453454`SOCK_`455456. Номер протокола обычно равен нулю и в этом случае может быть опущен.457458#### `socket.socketpair([family[, type[, proto]]])`459460Создаёт пару соединённых объектов сокетов, используя указанное семейство адресов, тип сокета и номер протокола. Семейство адресов, тип сокета и номер протокола такие же, как для функции461462[`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket)463464выше. Семейство по умолчанию –465466[`AF_UNIX`](https://python-all.ru/3.1/library/socket.html#socket.AF_UNIX)467468, если оно определено на платформе; в противном случае по умолчанию используется469470[`AF_INET`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET)471472. Доступность: Unix.473474#### `socket.fromfd(fd, family, type[, proto])`475476Дублирует файловый дескриптор477478*fd*479480(целое число, возвращаемое методом481482`fileno()`483484файлового объекта) и создаёт из результата объект сокета. Семейство адресов, тип сокета и номер протокола – как у функции485486[`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket)487488выше. Файловый дескриптор должен указывать на сокет, но это не проверяется – последующие операции с объектом могут завершиться ошибкой, если дескриптор некорректен. Эта функция редко нужна, но может использоваться для получения или установки параметров сокета, переданного программе в качестве стандартного ввода или вывода (например, сервер, запущенный демоном inet в Unix). Предполагается, что сокет работает в блокирующем режиме. Доступность: Unix.489490#### `socket.ntohl(x)`491492Преобразует 32-битные положительные целые числа из сетевого порядка байтов в порядок байтов хоста. На машинах, где порядок байтов хоста совпадает с сетевым, эта операция ничего не делает; в противном случае выполняется перестановка 4 байтов.493494#### `socket.ntohs(x)`495496Преобразует 16-битные положительные целые числа из сетевого порядка байтов в порядок байтов хоста. На машинах, где порядок байтов хоста совпадает с сетевым, эта функция ничего не делает; в противном случае она выполняет обмен двух байтов.497498#### `socket.htonl(x)`499500Преобразует 32-битные положительные целые числа из порядка байтов хоста в сетевой порядок. На машинах, где порядок байтов хоста совпадает с сетевым, эта функция ничего не делает; в противном случае она выполняет обмен четырёх байтов.501502#### `socket.htons(x)`503504Преобразует 16-битные положительные целые числа из порядка байтов хоста в сетевой порядок. На машинах, где порядок байтов хоста совпадает с сетевым, эта функция ничего не делает; в противном случае она выполняет обмен двух байтов.505506#### `socket.inet_aton(ip_string)`507508Преобразует IPv4-адрес из строкового формата с точками (например, '123.45.67.89') в 32-битный упакованный двоичный формат в виде объекта bytes длиной четыре символа. Это полезно при взаимодействии с программой, использующей стандартную библиотеку C и требующей объекты типа `struct in_addr`, который является типом C для 32-битного упакованного двоичного представления, возвращаемого этой функцией.509510[`inet_aton()`](https://python-all.ru/3.1/library/socket.html#socket.inet_aton) также принимает строки с менее чем тремя точками; подробнее см. в руководстве Unix *inet(3)*.511512Если строка IPv4-адреса, переданная в эту функцию, недействительна, возбуждается [`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error). Обратите внимание, что точное определение допустимости зависит от реализации функции `inet_aton()` на C.513514[`inet_aton()`](https://python-all.ru/3.1/library/socket.html#socket.inet_aton) не поддерживает IPv6, и для поддержки двойного стека IPv4/IPv6 вместо него следует использовать [`inet_pton()`](https://python-all.ru/3.1/library/socket.html#socket.inet_pton).515516#### `socket.inet_ntoa(packed_ip)`517518Преобразует 32-битный упакованный IPv4-адрес (объект bytes длиной четыре символа) в его стандартное строковое представление с точками (например, '123.45.67.89'). Это полезно при взаимодействии с программой, использующей стандартную библиотеку C и требующей объекты типа `struct in_addr`, который является типом C для 32-битных упакованных двоичных данных, принимаемых этой функцией в качестве аргумента.519520Если длина переданной этой функции последовательности байтов не равна ровно 4 байтам, возбуждается [`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error). [`inet_ntoa()`](https://python-all.ru/3.1/library/socket.html#socket.inet_ntoa) не поддерживает IPv6, поэтому для поддержки двойного стека IPv4/IPv6 следует использовать [`inet_ntop()`](https://python-all.ru/3.1/library/socket.html#socket.inet_ntop).521522#### `socket.inet_pton(address_family, ip_string)`523524Преобразует IP-адрес из строкового формата, зависящего от семейства, в упакованный двоичный формат. [`inet_pton()`](https://python-all.ru/3.1/library/socket.html#socket.inet_pton) полезен, когда библиотека или сетевой протокол требует объект типа `struct in_addr` (аналогично [`inet_aton()`](https://python-all.ru/3.1/library/socket.html#socket.inet_aton)) или `struct in6_addr`.525526В настоящее время *address\_family* поддерживает значения [`AF_INET`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET) и [`AF_INET6`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET6). Если строка IP-адреса *ip\_string* недействительна, возбуждается [`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error). Имейте в виду, что точное определение допустимости зависит как от значения *address\_family*, так и от реализации `inet_pton()`.527528Доступность: Unix (возможно, не на всех платформах).529530#### `socket.inet_ntop(address_family, packed_ip)`531532Convert 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()`](https://python-all.ru/3.1/library/socket.html#socket.inet_ntop) is useful when a library or network protocol returns an object of type `struct in_addr` (similar to [`inet_ntoa()`](https://python-all.ru/3.1/library/socket.html#socket.inet_ntoa)) or `struct in6_addr`.533534В настоящее время *address\_family* поддерживает значения [`AF_INET`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET) и [`AF_INET6`](https://python-all.ru/3.1/library/socket.html#socket.AF_INET6). Если длина строки *packed\_ip* не соответствует указанному семейству адресов, возбуждается [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError). [`socket.error`](https://python-all.ru/3.1/library/socket.html#socket.error) возбуждается при ошибках вызова [`inet_ntop()`](https://python-all.ru/3.1/library/socket.html#socket.inet_ntop).535536Доступность: Unix (возможно, не на всех платформах).537538#### `socket.getdefaulttimeout()`539540Возвращает таймаут по умолчанию в секундах с плавающей запятой для новых объектов сокета. Значение541542`None`543544означает, что у новых объектов сокета нет таймаута. При первом импорте модуля socket значение по умолчанию –545546`None`547548.549550#### `socket.setdefaulttimeout(timeout)`551552Устанавливает таймаут по умолчанию в секундах с плавающей запятой для новых объектов сокета. При первом импорте модуля socket значение по умолчанию –553554`None`555556. Информацию о возможных значениях и их смысле см. в557558[`settimeout()`](https://python-all.ru/3.1/library/socket.html#socket.socket.settimeout)559560.561562#### `socket.SocketType`563564Это объект типа Python, представляющий тип объекта сокета. Он эквивалентен565566`type(socket(...))`567568.569570## 17.2.3. Объекты сокетов571572Объекты сокетов имеют следующие методы. За исключением `makefile()`, они соответствуют системным вызовам Unix, применимым к сокетам.573574#### `socket.accept()`575576Принимает соединение. Сокет должен быть привязан к адресу и прослушивать соединения. Возвращаемое значение – пара577578`(conn, address)`579580, где581582*conn*583584– это585586*новый*587588объект сокета, который можно использовать для отправки и получения данных по соединению, а589590*address*591592– это адрес, привязанный к сокету на другом конце соединения.593594#### `socket.bind(address)`595596Привязывает сокет к597598*address*599600. Сокет не должен быть уже привязан. (Формат601602*address*603604зависит от семейства адресов – см. выше.)605606#### `socket.close()`607608Закрывает сокет. Все последующие операции с объектом сокета будут завершаться ошибкой. Удаленная сторона не получит больше данных (после сброса находящихся в очереди данных). Сокеты автоматически закрываются при сборке мусора.609610> **Примечание**611>612> [`close()`](https://python-all.ru/3.1/library/socket.html#socket.socket.close) освобождает ресурс, связанный с соединением, но не обязательно закрывает соединение немедленно. Если требуется вовремя закрыть соединение, вызовите [`shutdown()`](https://python-all.ru/3.1/library/socket.html#socket.socket.shutdown) перед [`close()`](https://python-all.ru/3.1/library/socket.html#socket.socket.close).613614#### `socket.connect(address)`615616Подключается к удалённому сокету по адресу617618*address*619620. (Формат621622*address*623624зависит от семейства адресов – см. выше.)625626#### `socket.connect_ex(address)`627628Как и629630`connect(address)`631632, но возвращает индикатор ошибки вместо вызова исключения для ошибок, возвращаемых вызовом633634`connect()`635636на уровне C (другие проблемы, такие как «хост не найден», по-прежнему могут вызывать исключения). Индикатор ошибки равен637638`0`639640, если операция выполнена успешно, в противном случае – значению переменной641642`errno`643644. Это полезно, например, для поддержки асинхронных соединений.645646#### `socket.fileno()`647648Возвращает файловый дескриптор сокета (небольшое целое число). Это полезно с [`select.select()`](https://python-all.ru/3.1/library/select.html#select.select).649650В Windows небольшое целое число, возвращаемое этим методом, нельзя использовать там, где может использоваться файловый дескриптор (например, в [`os.fdopen()`](https://python-all.ru/3.1/library/os.html#os.fdopen)). В Unix такого ограничения нет.651652#### `socket.getpeername()`653654Возвращает удалённый адрес, к которому подключён сокет. Это полезно, например, для определения номера порта удалённого сокета IPv4/v6. (Формат возвращаемого адреса зависит от семейства адресов – см. выше.) На некоторых системах эта функция не поддерживается.655656#### `socket.getsockname()`657658Возвращает собственный адрес сокета. Это полезно, например, для определения номера порта сокета IPv4/v6. (Формат возвращаемого адреса зависит от семейства адресов – см. выше.)659660#### `socket.getsockopt(level, optname[, buflen])`661662Возвращает значение указанной опции сокета (см. страницу man Unix663664*getsockopt(2)*665666). Необходимые символьные константы (667668`SO_*`669670и т.д.) определены в этом модуле. Если671672*buflen*673674отсутствует, предполагается целочисленная опция, и функция возвращает её целочисленное значение. Если675676*buflen*677678присутствует, он задает максимальную длину буфера для получения опции, и этот буфер возвращается в виде объекта bytes. Вызывающий код должен сам декодировать содержимое буфера (см. опциональный встроенный модуль679680[`struct`](https://python-all.ru/3.1/library/struct.html#module-struct)681682для способа декодирования структур C, закодированных как байтовые строки).683684#### `socket.gettimeout()`685686Возвращает таймаут в секундах с плавающей запятой, связанный с операциями сокета, или687688`None`689690, если таймаут не установлен. Это значение отражает последний вызов691692[`setblocking()`](https://python-all.ru/3.1/library/socket.html#socket.socket.setblocking)693694или695696[`settimeout()`](https://python-all.ru/3.1/library/socket.html#socket.socket.settimeout)697698.699700#### `socket.ioctl(control, option)`701702| Платформа: | Windows |703| --- | --- |704705Метод [`ioctl()`](https://python-all.ru/3.1/library/socket.html#socket.socket.ioctl) представляет собой ограниченный интерфейс к системному интерфейсу WSAIoctl. Для получения дополнительной информации обратитесь к [документации Win32](https://python-all.ru/3.1/library/socket.html).706707On other platforms, the generic [`fcntl.fcntl()`](https://python-all.ru/3.1/library/fcntl.html#fcntl.fcntl) and [`fcntl.ioctl()`](https://python-all.ru/3.1/library/fcntl.html#fcntl.ioctl) functions may be used; they accept a socket object as their first argument.708709#### `socket.listen(backlog)`710711Ожидает подключения к сокету. Аргумент712713*backlog*714715задаёт максимальное количество ожидающих соединений в очереди и должен быть не менее 1; максимальное значение зависит от системы (обычно 5).716717#### `socket.makefile(mode='r', buffering=None, *, encoding=None, errors=None, newline=None)`718719Возвращает [*файловый объект*](https://python-all.ru/3.1/glossary.html#term-file-object), связанный с сокетом. Точный возвращаемый тип зависит от аргументов, переданных в [`makefile()`](https://python-all.ru/3.1/library/socket.html#socket.socket.makefile). Эти аргументы интерпретируются так же, как и встроенной функцией [`open()`](https://python-all.ru/3.1/library/functions.html#open).720721Закрытие файлового объекта не приведет к закрытию сокета, если не осталось ссылок на сокет. Сокет должен находиться в блокирующем режиме; он может иметь тайм-аут, но в случае его срабатывания внутренний буфер файлового объекта может оказаться в несогласованном состоянии.722723> **Примечание**724>725> В Windows файлоподобный объект, созданный [`makefile()`](https://python-all.ru/3.1/library/socket.html#socket.socket.makefile), нельзя использовать там, где требуется файловый объект с файловым дескриптором, например в аргументах потока [`subprocess.Popen()`](https://python-all.ru/3.1/library/subprocess.html#subprocess.Popen).726727#### `socket.recv(bufsize[, flags])`728729Получает данные из сокета. Возвращает объект bytes с полученными данными. Максимальный объём данных за одно получение задаётся параметром *bufsize*. Значение необязательного аргумента *flags* описано на странице руководства Unix *recv(2)*; по умолчанию он равен нулю.730731> **Примечание**732>733> Для наилучшего соответствия реальным характеристикам оборудования и сети значение *bufsize* должно быть относительно небольшой степенью двойки, например, 4096.734735#### `socket.recvfrom(bufsize[, flags])`736737Receive data from the socket. The return value is a pair738739`(bytes, address)`740741where742743*bytes*744745is a bytes object representing the data received and746747*address*748749is the address of the socket sending the data. See the Unix manual page750751*recv(2)*752753for the meaning of the optional argument754755*flags*756757; it defaults to zero. (The format of758759*address*760761depends on the address family – see above.)762763#### `socket.recvfrom_into(buffer[, nbytes[, flags]])`764765Receive data from the socket, writing it into766767*buffer*768769instead of creating a new bytestring. The return value is a pair770771`(nbytes, address)`772773where774775*nbytes*776777is the number of bytes received and778779*address*780781is the address of the socket sending the data. See the Unix manual page782783*recv(2)*784785for the meaning of the optional argument786787*flags*788789; it defaults to zero. (The format of790791*address*792793depends on the address family – see above.)794795#### `socket.recv_into(buffer[, nbytes[, flags]])`796797Принимает до798799*nbytes*800801байт из сокета, сохраняя данные в буфер, а не создавая новую байтовую строку. Если802803*nbytes*804805не указан (или равен 0), принимает столько байт, сколько помещается в переданный буфер. Смысл необязательного аргумента806807*flags*808809описан на странице руководства Unix810811*recv(2)*812813; по умолчанию он равен нулю.814815#### `socket.send(bytes[, flags])`816817Отправляет данные в сокет. Сокет должен быть подключён к удалённому сокету. Необязательный аргумент818819*flags*820821имеет тот же смысл, что и для822823[`recv()`](https://python-all.ru/3.1/library/socket.html#socket.socket.recv)824825выше. Возвращает количество отправленных байт. Приложения должны проверять, что все данные были отправлены; если передана только часть данных, приложению необходимо повторить попытку отправки оставшихся данных.826827#### `socket.sendall(bytes[, flags])`828829Отправляет данные в сокет. Сокет должен быть подключён к удалённому сокету. Необязательный аргумент830831*flags*832833имеет то же значение, что и для834835[`recv()`](https://python-all.ru/3.1/library/socket.html#socket.socket.recv)836837выше. В отличие от838839[`send()`](https://python-all.ru/3.1/library/socket.html#socket.socket.send)840841, этот метод продолжает отправлять данные из842843*bytes*844845, пока не будут отправлены все данные или не возникнет ошибка. В случае успеха возвращается846847`None`848849. При ошибке вызывается исключение, и невозможно определить, сколько данных (если вообще было) было успешно отправлено.850851#### `socket.sendto(bytes[, flags], address)`852853Отправляет данные в сокет. Сокет не должен быть подключён к удалённому сокету, так как целевой сокет задаётся аргументом854855*address*856857. Необязательный аргумент858859*flags*860861имеет то же значение, что и для862863[`recv()`](https://python-all.ru/3.1/library/socket.html#socket.socket.recv)864865выше. Возвращает количество отправленных байт. (Формат866867*address*868869зависит от семейства адресов – см. выше.)870871#### `socket.setblocking(flag)`872873Устанавливает блокирующий или неблокирующий режим сокета: если *flag* равен false, сокет переводится в неблокирующий режим, иначе в блокирующий.874875Этот метод является сокращением для некоторых вызовов [`settimeout()`](https://python-all.ru/3.1/library/socket.html#socket.socket.settimeout):876877- `sock.setblocking(True)` эквивалентно `sock.settimeout(None)`878- `sock.setblocking(False)` эквивалентно `sock.settimeout(0.0)`879880#### `socket.settimeout(value)`881882Устанавливает тайм-аут для блокирующих операций с сокетом. Аргумент *value* может быть неотрицательным числом с плавающей запятой, выражающим секунды, или `None`. Если задано ненулевое значение, последующие операции с сокетом будут вызывать исключение [`timeout`](https://python-all.ru/3.1/library/socket.html#socket.timeout), если период тайм-аута *value* истек до завершения операции. Если задан ноль, сокет переводится в неблокирующий режим. Если задано `None`, сокет переводится в блокирующий режим.883884Для получения дополнительной информации обратитесь к [*заметкам о тайм-аутах сокетов*](https://python-all.ru/3.1/library/socket.html#socket-timeouts).885886#### `socket.setsockopt(level, optname, value)`887888Устанавливает значение указанного параметра сокета (см. страницу руководства Unix *setsockopt(2)*). Необходимые символические константы определены в модуле `socket` (`SO_*` и т.д.). Значением может быть целое число или объект bytes, представляющий буфер. В последнем случае вызывающая сторона должна обеспечить, чтобы байтовая строка содержала правильные биты (см. дополнительный встроенный модуль [`struct`](https://python-all.ru/3.1/library/struct.html#module-struct) для способа кодирования структур C в виде байтовых строк).889890#### `socket.shutdown(how)`891892Завершает одну или обе половины соединения. Если893894*how*895896равно897898`SHUT_RD`899900, дальнейший приём данных запрещён. Если901902*how*903904равно905906`SHUT_WR`907908, дальнейшая отправка данных запрещена. Если909910*how*911912равно913914`SHUT_RDWR`915916, дальнейшие отправка и приём данных запрещены. В зависимости от платформы завершение одной половины соединения может также закрыть противоположную половину (например, на Mac OS X917918`shutdown(SHUT_WR)`919920не позволяет выполнять чтение на другом конце соединения).921922Обратите внимание, что методов `read()` или `write()` не существует; вместо них используйте [`recv()`](https://python-all.ru/3.1/library/socket.html#socket.socket.recv) и [`send()`](https://python-all.ru/3.1/library/socket.html#socket.socket.send) без аргумента *flags*.923924Объекты сокетов также имеют следующие (только для чтения) атрибуты, которые соответствуют значениям, переданным конструктору [`socket`](https://python-all.ru/3.1/library/socket.html#socket.socket).925926#### `socket.family`927928Семейство сокета.929930#### `socket.type`931932Тип сокета.933934#### `socket.proto`935936Протокол сокета.937938## 17.2.4. Замечания о тайм-аутах сокетов939940Объект сокета может находиться в одном из трёх режимов: блокирующем, неблокирующем или с тайм-аутом. По умолчанию сокеты всегда создаются в блокирующем режиме, но это можно изменить, вызвав [`setdefaulttimeout()`](https://python-all.ru/3.1/library/socket.html#socket.setdefaulttimeout).941942- В *блокирующем режиме* операции блокируются до завершения или пока система не вернет ошибку (например, истекло время соединения).943- В *неблокирующем режиме* операции завершаются ошибкой (с ошибкой, которая, к сожалению, зависит от системы), если их нельзя выполнить немедленно: функции из модуля [`select`](https://python-all.ru/3.1/library/select.html#module-select) можно использовать, чтобы узнать, когда и доступен ли сокет для чтения или записи.944- В *режиме с тайм-аутом* операции завершаются ошибкой, если их нельзя выполнить в течение тайм-аута, указанного для сокета (они вызывают исключение [`timeout`](https://python-all.ru/3.1/library/socket.html#socket.timeout)), или если система возвращает ошибку.945946> **Примечание**947>948> На уровне операционной системы сокеты в *режиме с тайм-аутом* внутренне устанавливаются в неблокирующий режим. Кроме того, блокирующий режим и режим тайм-аута разделяются между файловыми дескрипторами и объектами сокетов, которые относятся к одной и той же сетевой конечной точке. Эта деталь реализации может иметь заметные последствия, если, например, вы решите использовать [`fileno()`](https://python-all.ru/3.1/library/socket.html#socket.socket.fileno) сокета.949950### 17.2.4.1. Тайм-ауты и метод `connect`951952Операция [`connect()`](https://python-all.ru/3.1/library/socket.html#socket.socket.connect) также подчиняется настройке тайм-аута, и в целом рекомендуется вызывать [`settimeout()`](https://python-all.ru/3.1/library/socket.html#socket.socket.settimeout) перед вызовом [`connect()`](https://python-all.ru/3.1/library/socket.html#socket.socket.connect) или передавать параметр тайм-аута в [`create_connection()`](https://python-all.ru/3.1/library/socket.html#socket.create_connection). Однако сетевой стек системы также может вернуть собственную ошибку тайм-аута соединения независимо от любой настройки тайм-аута сокета Python.953954## 17.2.5. Пример955956Вот четыре минимальных примера программ, использующих протокол TCP/IP: сервер, который отправляет обратно все полученные данные (обслуживая только одного клиента), и клиент, использующий его. Обратите внимание, что сервер должен выполнить последовательность [`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket), [`bind()`](https://python-all.ru/3.1/library/socket.html#socket.socket.bind), [`listen()`](https://python-all.ru/3.1/library/socket.html#socket.socket.listen), [`accept()`](https://python-all.ru/3.1/library/socket.html#socket.socket.accept) (возможно, повторяя [`accept()`](https://python-all.ru/3.1/library/socket.html#socket.socket.accept) для обслуживания более чем одного клиента), в то время как клиенту нужна только последовательность [`socket()`](https://python-all.ru/3.1/library/socket.html#socket.socket), [`connect()`](https://python-all.ru/3.1/library/socket.html#socket.socket.connect). Также обратите внимание, что сервер не вызывает [`send()`](https://python-all.ru/3.1/library/socket.html#socket.socket.send)/[`recv()`](https://python-all.ru/3.1/library/socket.html#socket.socket.recv) на сокете, который прослушивает, а на новом сокете, возвращённом [`accept()`](https://python-all.ru/3.1/library/socket.html#socket.socket.accept).957958Первые два примера поддерживают только IPv4.959960```python961# Программа эхо-сервера962import socket963964HOST = ''                 # Символическое имя, обозначающее все доступные интерфейсы965PORT = 50007              # Произвольный непривилегированный порт966s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)967s.bind((HOST, PORT))968s.listen(1)969conn, addr = s.accept()970print('Connected by', addr)971while True:972    data = conn.recv(1024)973    if not data: break974    conn.send(data)975conn.close()976```977978```python979# Программа эхо-клиента980import socket981982HOST = 'daring.cwi.nl'    # Удалённый хост983PORT = 50007              # Тот же порт, что и у сервера984s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)985s.connect((HOST, PORT))986s.send(b'Hello, world')987data = s.recv(1024)988s.close()989print('Received', repr(data))990```991992Следующие два примера идентичны двум предыдущим, но поддерживают как IPv4, так и IPv6. Серверная сторона будет прослушивать первое доступное семейство адресов (ей следовало бы прослушивать оба). На большинстве систем, готовых к IPv6, IPv6 будет иметь приоритет, и сервер может не принимать IPv4-трафик. Клиентская сторона попытается подключиться ко всем адресам, полученным в результате разрешения имен, и отправляет трафик на первый успешно подключенный.993994```python995# Программа эхо-сервера996import socket997import sys998999HOST = None               # Символическое имя, обозначающее все доступные интерфейсы1000PORT = 50007              # Произвольный непривилегированный порт1001s = None1002for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,1003                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):1004    af, socktype, proto, canonname, sa = res1005    try:1006        s = socket.socket(af, socktype, proto)1007    except socket.error as msg:1008        s = None1009        continue1010    try:1011        s.bind(sa)1012        s.listen(1)1013    except socket.error as msg:1014        s.close()1015        s = None1016        continue1017    break1018if s is None:1019    print('could not open socket')1020    sys.exit(1)1021conn, addr = s.accept()1022print('Connected by', addr)1023while True:1024    data = conn.recv(1024)1025    if not data: break1026    conn.send(data)1027conn.close()1028```10291030```python1031# Программа эхо-клиента1032import socket1033import sys10341035HOST = 'daring.cwi.nl'    # Удалённый хост1036PORT = 50007              # Тот же порт, что и у сервера1037s = None1038for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):1039    af, socktype, proto, canonname, sa = res1040    try:1041        s = socket.socket(af, socktype, proto)1042    except socket.error as msg:1043        s = None1044        continue1045    try:1046        s.connect(sa)1047    except socket.error as msg:1048        s.close()1049        s = None1050        continue1051    break1052if s is None:1053    print('could not open socket')1054    sys.exit(1)1055s.send(b'Hello, world')1056data = s.recv(1024)1057s.close()1058print('Received', repr(data))1059```10601061Последний пример показывает, как написать очень простой сетевой сниффер с помощью сырых сокетов в Windows. Для выполнения примера требуются права администратора для изменения интерфейса:10621063```python1064import socket10651066# общедоступный сетевой интерфейс1067HOST = socket.gethostbyname(socket.gethostname())10681069# создать сырой сокет и привязать его к общедоступному интерфейсу1070s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)1071s.bind((HOST, 0))10721073# Включать IP-заголовки1074s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)10751076# принять все пакеты1077s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)10781079# принять пакет1080print(s.recvfrom(65565))10811082# неразборчивый режим отключён1083s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)1084```10851086> **См. также**1087>1088> Для ознакомления с программированием сокетов (на C) см. следующие статьи:1089>1090> - *Вводное руководство по межпроцессному взаимодействию в 4.3BSD*, Стюарт Сечрест1091> - *Продвинутое руководство по межпроцессному взаимодействию в 4.3BSD*, Сэмюэл Дж. Леффлер и др.1092>1093> Оба находятся в UNIX Programmer’s Manual, Supplementary Documents 1 (разделы PS1:7 и PS1:8). Справочные материалы по сокетным системным вызовам для конкретных платформ также являются ценным источником информации о деталях семантики сокетов. Для Unix обращайтесь к страницам руководства; для Windows – к спецификации WinSock (или Winsock 2). Для API с поддержкой IPv6 читателю может быть полезно обратиться к [**RFC 3493**](https://python-all.ru/3.1/library/socket.html) под названием Basic Socket Interface Extensions for IPv6.1094