socket — Low-level networking interface

Вихідний код: Lib/socket.py

Цей модуль забезпечує доступ до інтерфейсу BSD socket. Він доступний у всіх сучасних системах Unix, Windows, MacOS і, можливо, на додаткових платформах.

Примітка

Деяка поведінка може залежати від платформи, оскільки виклики здійснюються до API сокетів операційної системи.

The Python interface is a straightforward transliteration of the Unix system call and library interface for sockets to Python’s object-oriented style: the socket() function returns a socket object whose methods implement the various socket system calls. Parameter types are somewhat higher-level than in the C interface: as with read() and write() operations on Python files, buffer allocation on receive operations is automatic, and buffer length is implicit on send operations.

Дивись також

Модуль socketserver

Класи, які спрощують написання мережевих серверів.

Модуль ssl

Обгортка TLS/SSL для об’єктів сокета.

Сімейства розеток

Залежно від системи та параметрів збірки, цей модуль підтримує різні сімейства сокетів.

Формат адреси, необхідний для певного об’єкта сокета, вибирається автоматично на основі сімейства адрес, указаного під час створення об’єкта сокета. Адреси сокетів представлені таким чином:

  • Адреса сокета AF_UNIX, пов’язаного з вузлом файлової системи, представлена у вигляді рядка з використанням кодування файлової системи та обробника помилок 'surrogateescape' (див. PEP 383). Адреса в абстрактному просторі імен Linux повертається як bytes-like object з початковим нульовим байтом; зауважте, що сокети в цьому просторі імен можуть взаємодіяти зі звичайними сокетами файлової системи, тому програми, призначені для роботи в Linux, можуть мати справу з обома типами адрес. Рядок або байт-подібний об’єкт можна використовувати для будь-якого типу адреси, передаючи його як аргумент.

    Змінено в версії 3.3: Раніше вважалося, що шляхи сокетів AF_UNIX використовували кодування UTF-8.

    Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

  • A pair (host, port) is used for the AF_INET address family, where host is a string representing either a hostname in Internet domain notation like 'daring.cwi.nl' or an IPv4 address like '100.50.200.5', and port is an integer.

    • Для адрес IPv4 приймаються дві спеціальні форми замість адреси хоста: '' представляє INADDR_ANY, який використовується для прив’язки до всіх інтерфейсів, а рядок ' <broadcast> '' представляє INADDR_BROADCAST. Така поведінка несумісна з IPv6, тому ви можете уникнути цього, якщо ви маєте намір підтримувати IPv6 у своїх програмах на Python.

  • Для родини адрес AF_INET6 використовується чотирикортеж (host, port, flowinfo, scope_id), де flowinfo та scope_id представляють sin6_flowinfo та sin6_scope_id члени в struct sockaddr_in6 в C. Для методів модуля socket flowinfo та scope_id можна опустити тільки для зворотної сумісності. Однак зауважте, що пропуск scope_id може спричинити проблеми під час маніпулювання адресами IPv6 із областю дії.

    Змінено в версії 3.7: Для багатоадресних адрес (зі значенням scope_id) address не може містити частину %scope_id (або zone id). Ця інформація є зайвою, і її можна сміливо опустити (рекомендовано).

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

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

    • addr_type є одним із TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME або TIPC_ADDR_ID.

    • scope є одним із TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE та TIPC_NODE_SCOPE.

    • Якщо addr_type дорівнює TIPC_ADDR_NAME, тоді v1 — це тип сервера, v2 — ідентифікатор порту, а v3 має бути 0.

      Якщо addr_type дорівнює TIPC_ADDR_NAMESEQ, то v1 — це тип сервера, v2 — нижній номер порту, а v3 — верхній номер порту.

      Якщо addr_type дорівнює TIPC_ADDR_ID, тоді v1 є вузлом, v2 є посиланням, а v3 має бути встановлено на 0.

  • Кортеж (інтерфейс, ) використовується для сімейства адрес AF_CAN, де інтерфейс — це рядок, що представляє назву мережевого інтерфейсу, наприклад 'can0'. Ім’я мережевого інтерфейсу '' можна використовувати для отримання пакетів від усіх мережевих інтерфейсів цього сімейства.

    • Протокол CAN_ISOTP вимагає кортеж (interface, rx_addr, tx_addr), де обидва додаткові параметри є довгим цілим числом без знаку, що представляє ідентифікатор CAN (стандартний або розширений).

    • CAN_J1939 protocol require a tuple (interface, name, pgn, addr) where additional parameters are 64-bit unsigned integer representing the ECU name, a 32-bit unsigned integer representing the Parameter Group Number (PGN), and an 8-bit integer representing the address.

  • A string or a tuple (id, unit) is used for the SYSPROTO_CONTROL protocol of the PF_SYSTEM family. The string is the name of a kernel control using a dynamically-assigned ID. The tuple can be used if ID and unit number of the kernel control are known or if a registered ID is used.

    Нове в версії 3.3.

  • AF_BLUETOOTH підтримує наступні протоколи та формати адрес:

    • BTPROTO_L2CAP приймає (bdaddr, psm), де bdaddr — адреса Bluetooth у вигляді рядка, а psm — ціле число.

    • BTPROTO_RFCOMM приймає (bdaddr, канал), де bdaddr — це адреса Bluetooth у вигляді рядка, а channel — ціле число.

    • BTPROTO_HCI приймає (device_id,), де device_id є або цілим числом, або рядком з адресою Bluetooth інтерфейсу. (Це залежить від вашої ОС; NetBSD і DragonFlyBSD очікують адресу Bluetooth, а всі інші очікують ціле число.)

      Змінено в версії 3.2: Додано підтримку NetBSD і DragonFlyBSD.

    • BTPROTO_SCO приймає bdaddr, де bdaddr є об’єктом bytes, що містить адресу Bluetooth у форматі рядка. (наприклад, b'12:23:34:45:56:67'') Цей протокол не підтримується FreeBSD.

  • AF_ALG — це інтерфейс для криптографії ядра на основі сокетів лише для Linux. Сокет алгоритму налаштований за допомогою кортежу з двох-чотирьох елементів (type, name [, feat [, mask]]), де:

    • type — це тип алгоритму як рядок, напр. aead, hash, skcipher або rng.

    • ім’я — це назва алгоритму та режим роботи у вигляді рядка, напр. sha256, hmac(sha256), cbc(aes) або drbg_nopr_ctr_aes256.

    • feat і mask — це 32-розрядні цілі числа без знаку.

    Availability: Linux 2.6.38, some algorithm types require more recent Kernels.

    Нове в версії 3.6.

  • AF_VSOCK дозволяє спілкуватися між віртуальними машинами та їх хостами. Сокети представлені як кортеж (CID, порт), де ідентифікатор контексту або CID і порт є цілими числами.

    Availability: Linux >= 4.8 QEMU >= 2.8 ESX >= 4.0 ESX Workstation >= 6.5.

    Нове в версії 3.7.

  • AF_PACKET is a low-level interface directly to network devices. The packets are represented by the tuple (ifname, proto[, pkttype[, hatype[, addr]]]) where:

    • ifname - Рядок, що визначає назву пристрою.

    • proto - An in network-byte-order integer specifying the Ethernet protocol number.

    • pkttype - додаткове ціле число, що вказує тип пакета:

      • PACKET_HOST (за замовчуванням) - пакет, адресований локальному хосту.

      • PACKET_BROADCAST - широкомовний пакет фізичного рівня.

      • PACKET_MULTIHOST - Packet sent to a physical-layer multicast address.

      • PACKET_OTHERHOST - Пакет до іншого хосту, який був перехоплений драйвером пристрою в безладному режимі.

      • PACKET_OUTGOING – Пакет, що надходить від локального хосту і повертається до сокета пакета.

    • hatype – додаткове ціле число, що визначає тип апаратної адреси ARP.

    • addr – необов’язковий байтовий об’єкт, що вказує апаратну фізичну адресу, інтерпретація якої залежить від пристрою.

    Availability: Linux >= 2.2.

  • AF_QIPCRTR — це інтерфейс на основі сокетів лише для Linux для зв’язку зі службами, що працюють на співпроцесорах на платформах Qualcomm. Сімейство адрес представлено як кортеж (вузол, порт), де вузол і порт є невід’ємними цілими числами.

    Availability: Linux >= 4.7.

    Нове в версії 3.8.

  • IPPROTO_UDPLITE — це варіант UDP, який дозволяє вказати, яку частину пакету охоплює контрольна сума. Він додає два варіанти розеток, які ви можете змінити. self.setsockopt(IPPROTO_UDPLITE, UDPLITE_SEND_CSCOV, length) змінить частину вихідних пакетів, охоплених контрольною сумою, а self.setsockopt(IPPROTO_UDPLITE, UDPLITE_RECV_CSCOV, length) відфільтровує пакети, які покривають занадто мало їхні дані. В обох випадках довжина має бути в діапазоні (8, 2**16, 8).

    Такий сокет має бути створений за допомогою socket(AF_INET, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv4 або socket(AF_INET6, SOCK_DGRAM, IPPROTO_UDPLITE) для IPv6.

    Availability: Linux >= 2.6.20, FreeBSD >= 10.1-RELEASE

    Нове в версії 3.9.

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

All errors raise exceptions. The normal exceptions for invalid argument types and out-of-memory conditions can be raised; starting from Python 3.3, errors related to socket or address semantics raise OSError or one of its subclasses (they used to raise socket.error).

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

Зміст модуля

Модуль socket експортує такі елементи.

Винятки

exception socket.error

Застарілий псевдонім OSError.

Змінено в версії 3.3: Після PEP 3151 цей клас отримав псевдонім OSError.

exception socket.herror

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

Змінено в версії 3.3: Цей клас було створено підкласом OSError.

exception socket.gaierror

A subclass of OSError, this exception is raised for address-related errors by getaddrinfo() and getnameinfo(). The accompanying value is a pair (error, string) representing an error returned by a library call. string represents the description of error, as returned by the gai_strerror() C function. The numeric error value will match one of the EAI_* constants defined in this module.

Змінено в версії 3.3: Цей клас було створено підкласом OSError.

exception socket.timeout

Підклас OSError, цей виняток виникає, коли тайм-аут виникає в сокеті, для якого було ввімкнено тайм-аути через попередній виклик settimeout() (або неявно через setdefaulttimeout()). Супровідне значення - це рядок, значення якого наразі завжди «закінчено».

Змінено в версії 3.3: Цей клас було створено підкласом OSError.

Константи

Константи AF_* і SOCK_* тепер є колекціями AddressFamily і SocketKind IntEnum.

Нове в версії 3.4.

socket.AF_UNIX
socket.AF_INET
socket.AF_INET6

These constants represent the address (and protocol) families, used for the first argument to socket(). If the AF_UNIX constant is not defined then this protocol is unsupported. More constants may be available depending on the system.

socket.SOCK_STREAM
socket.SOCK_DGRAM
socket.SOCK_RAW
socket.SOCK_RDM
socket.SOCK_SEQPACKET

These constants represent the socket types, used for the second argument to socket(). More constants may be available depending on the system. (Only SOCK_STREAM and SOCK_DGRAM appear to be generally useful.)

socket.SOCK_CLOEXEC
socket.SOCK_NONBLOCK

Ці дві константи, якщо їх визначено, можна комбінувати з типами сокетів і дозволити вам встановлювати деякі прапори атомарно (таким чином уникаючи можливих умов змагання та потреби в окремих викликах).

Дивись також

Secure File Descriptor Handling for a more thorough explanation.

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

Нове в версії 3.2.

SO_*
socket.SOMAXCONN
MSG_*
SOL_*
SCM_*
IPPROTO_*
IPPORT_*
INADDR_*
IP_*
IPV6_*
EAI_*
AI_*
NI_*
TCP_*

Many constants of these forms, documented in the Unix documentation on sockets and/or the IP protocol, are also defined in the socket module. They are generally used in arguments to the setsockopt() and getsockopt() methods of socket objects. In most cases, only those symbols that are defined in the Unix header files are defined; for a few symbols, default values are provided.

Змінено в версії 3.6: Додано SO_DOMAIN, SO_PROTOCOL, SO_PEERSEC, SO_PASSSEC, TCP_USER_TIMEOUT, TCP_CONGESTION.

Змінено в версії 3.6.5: У Windows відображаються TCP_FASTOPEN, TCP_KEEPCNT, якщо Windows підтримує режим виконання.

Змінено в версії 3.7: TCP_NOTSENT_LOWAT було додано.

У Windows відображаються TCP_KEEPIDLE, TCP_KEEPINTVL, якщо Windows підтримує режим виконання.

socket.AF_CAN
socket.PF_CAN
SOL_CAN_*
CAN_*

Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

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

Нове в версії 3.3.

socket.CAN_BCM
CAN_BCM_*

CAN_BCM, у сімействі протоколів CAN, є протоколом менеджера трансляції (BCM). Константи менеджера трансляції, задокументовані в документації Linux, також визначені в модулі сокета.

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

Примітка

Прапор CAN_BCM_CAN_FD_FRAME доступний лише в Linux >= 4.8.

Нове в версії 3.4.

socket.CAN_RAW_FD_FRAMES

Вмикає підтримку CAN FD у гнізді CAN_RAW. За замовчуванням це вимкнено. Це дозволяє вашій програмі надсилати кадри CAN і CAN FD; однак під час читання з роз’єму ви повинні приймати як CAN, так і CAN FD кадри.

Ця константа задокументована в документації Linux.

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

Нове в версії 3.5.

socket.CAN_RAW_JOIN_FILTERS

Об’єднує застосовані фільтри CAN, щоб у простір користувача передавалися лише кадри CAN, які відповідають усім наданим фільтрам CAN.

Ця константа задокументована в документації Linux.

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

Нове в версії 3.9.

socket.CAN_ISOTP

CAN_ISOTP у сімействі протоколів CAN є протоколом ISO-TP (ISO 15765-2). Константи ISO-TP, задокументовані в документації Linux.

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

Нове в версії 3.7.

socket.CAN_J1939

CAN_J1939 у сімействі протоколів CAN є протоколом SAE J1939. Константи J1939, задокументовані в документації Linux.

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

Нове в версії 3.9.

socket.AF_PACKET
socket.PF_PACKET
PACKET_*

Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

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

socket.AF_RDS
socket.PF_RDS
socket.SOL_RDS
RDS_*

Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

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

Нове в версії 3.3.

socket.SIO_RCVALL
socket.SIO_KEEPALIVE_VALS
socket.SIO_LOOPBACK_FAST_PATH
RCVALL_*

Константи для Windows WSAIoctl(). Константи використовуються як аргументи методу ioctl() об’єктів сокета.

Змінено в версії 3.6: SIO_LOOPBACK_FAST_PATH було додано.

TIPC_*

Константи, пов’язані з TIPC, що збігаються з тими, які експортує API сокета C. Додаткову інформацію див. у документації TIPC.

socket.AF_ALG
socket.SOL_ALG
ALG_*

Константи для криптографії ядра Linux.

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

Нове в версії 3.6.

socket.AF_VSOCK
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID
VMADDR*
SO_VM*

Константи для зв’язку хост/гость Linux.

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

Нове в версії 3.7.

Наявність: BSD, macOS.

Нове в версії 3.4.

socket.has_ipv6

Ця константа містить логічне значення, яке вказує, чи підтримується IPv6 на цій платформі.

socket.BDADDR_ANY
socket.BDADDR_LOCAL

Це рядкові константи, що містять адреси Bluetooth зі спеціальними значеннями. Наприклад, BDADDR_ANY можна використовувати для вказівки будь-якої адреси, коли вказується сокет прив’язки за допомогою BTPROTO_RFCOMM.

socket.HCI_FILTER
socket.HCI_TIME_STAMP
socket.HCI_DATA_DIR

Для використання з BTPROTO_HCI. HCI_FILTER недоступний для NetBSD або DragonFlyBSD. HCI_TIME_STAMP і HCI_DATA_DIR недоступні для FreeBSD, NetBSD або DragonFlyBSD.

socket.AF_QIPCRTR

Константа для протоколу маршрутизатора IPC Qualcomm, який використовується для зв’язку з віддаленими процесорами, що надають послуги.

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

Функції

Створення сокетів

Усі наступні функції створюють об’єкти socket.

class socket.socket(family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None)

Створіть новий сокет, використовуючи вказане сімейство адрес, тип сокета та номер протоколу. Сімейство адрес має бути AF_INET (за замовчуванням), AF_INET6, AF_UNIX, AF_CAN, AF_PACKET або AF_RDS. Тип сокета має бути SOCK_STREAM (за замовчуванням), SOCK_DGRAM, SOCK_RAW або, можливо, одна з інших констант SOCK_. Номер протоколу зазвичай дорівнює нулю і може бути пропущений або у випадку, коли сімейство адрес AF_CAN, протокол має бути одним із CAN_RAW, CAN_BCM, CAN_ISOTP або CAN_J1939.

If fileno is specified, the values for family, type, and proto are auto-detected from the specified file descriptor. Auto-detection can be overruled by calling the function with explicit family, type, or proto arguments. This only affects how Python represents e.g. the return value of socket.getpeername() but not the actual OS resource. Unlike socket.fromfd(), fileno will return the same socket and not a duplicate. This may help close a detached socket using socket.close().

Новостворений сокет не успадковується.

Викликає подію аудиту socket.__new__ з аргументами self, family, type, protocol.

Змінено в версії 3.3: Додано сімейство AF_CAN. Додано сімейство AF_RDS.

Змінено в версії 3.4: Додано протокол CAN_BCM.

Змінено в версії 3.4: Повернений сокет тепер не успадковується.

Змінено в версії 3.7: Додано протокол CAN_ISOTP.

Змінено в версії 3.7: When SOCK_NONBLOCK or SOCK_CLOEXEC bit flags are applied to type they are cleared, and socket.type will not reflect them. They are still passed to the underlying system socket() call. Therefore,

sock = socket.socket(
    socket.AF_INET,
    socket.SOCK_STREAM | socket.SOCK_NONBLOCK)

усе одно створить неблокуючий сокет в ОС, які підтримують SOCK_NONBLOCK, але sock.type буде встановлено на socket.SOCK_STREAM.

Змінено в версії 3.9: Додано протокол CAN_J1939.

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

Build a pair of connected socket objects using the given address family, socket type, and protocol number. Address family, socket type, and protocol number are as for the socket() function above. The default family is AF_UNIX if defined on the platform; otherwise, the default is AF_INET.

Новостворені сокети не успадковуються.

Змінено в версії 3.2: Повернені об’єкти сокета тепер підтримують весь API сокета, а не його підмножину.

Змінено в версії 3.4: Повернені сокети тепер не успадковуються.

Змінено в версії 3.5: Додано підтримку Windows.

socket.create_connection(address[, timeout[, source_address]])

Connect to a TCP service listening on the Internet address (a 2-tuple (host, port)), and return the socket object. This is a higher-level function than socket.connect(): if host is a non-numeric hostname, it will try to resolve it for both AF_INET and AF_INET6, and then try to connect to all possible addresses in turn until a connection succeeds. This makes it easy to write clients that are compatible to both IPv4 and IPv6.

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

Якщо надано, source_address має бути 2-кортежем (хост, порт), щоб сокет прив’язувався до своєї адреси джерела перед підключенням. Якщо хост або порт мають значення „“ або 0 відповідно, буде використано типову поведінку ОС.

Змінено в версії 3.2: вихідна_адреса була додана.

socket.create_server(address, *, family=AF_INET, backlog=None, reuse_port=False, dualstack_ipv6=False)

Convenience function which creates a TCP socket bound to address (a 2-tuple (host, port)) and return the socket object.

family should be either AF_INET or AF_INET6. backlog is the queue size passed to socket.listen(); when 0 a default reasonable value is chosen. reuse_port dictates whether to set the SO_REUSEPORT socket option.

Якщо dualstack_ipv6 має значення true і платформа підтримує його, сокет зможе приймати як з’єднання IPv4, так і IPv6, інакше виникне ValueError. Більшість платформ POSIX і Windows повинні підтримувати цю функцію. Якщо цю функцію ввімкнено, адреса, яку повертає socket.getpeername() під час встановлення з’єднання IPv4, буде адресою IPv6, представленою як адреса IPv6, відображена в IPv4. Якщо dualstack_ipv6 має значення false, це явно вимикає цю функцію на платформах, які ввімкнули її за замовчуванням (наприклад, Linux). Цей параметр можна використовувати в поєднанні з has_dualstack_ipv6():

import socket

addr = ("", 8080)  # all interfaces, port 8080
if socket.has_dualstack_ipv6():
    s = socket.create_server(addr, family=socket.AF_INET6, dualstack_ipv6=True)
else:
    s = socket.create_server(addr)

Примітка

На платформах POSIX параметр сокета SO_REUSEADDR встановлено для негайного повторного використання попередніх сокетів, які були прив’язані до тієї самої адреси та залишалися в стані TIME_WAIT.

Нове в версії 3.8.

socket.has_dualstack_ipv6()

Повертає True, якщо платформа підтримує створення TCP-сокета, який може обробляти з’єднання IPv4 і IPv6.

Нове в версії 3.8.

socket.fromfd(fd, family, type, proto=0)

Duplicate the file descriptor fd (an integer as returned by a file object’s fileno() method) and build a socket object from the result. Address family, socket type and protocol number are as for the socket() function above. The file descriptor should refer to a socket, but this is not checked — subsequent operations on the object may fail if the file descriptor is invalid. This function is rarely needed, but can be used to get or set socket options on a socket passed to a program as standard input or output (such as a server started by the Unix inet daemon). The socket is assumed to be in blocking mode.

Новостворений сокет не успадковується.

Змінено в версії 3.4: Повернений сокет тепер не успадковується.

socket.fromshare(data)

Створіть екземпляр сокета з даних, отриманих з методу socket.share(). Передбачається, що розетка знаходиться в режимі блокування.

Наявність: Windows.

Нове в версії 3.3.

socket.SocketType

Це об’єкт типу Python, який представляє тип об’єкта сокета. Це те саме, що type(socket(...)).

Інші функції

Модуль socket також пропонує різноманітні мережеві служби:

socket.close(fd)

Закрийте дескриптор файлу сокета. Це як os.close(), але для сокетів. На деяких платформах (найбільш помітна Windows) os.close() не працює для дескрипторів файлів сокетів.

Нове в версії 3.7.

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

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

Аргументи сімейство, тип і прото можна додатково вказати, щоб звузити список адрес, що повертаються. Передача нуля як значення для кожного з цих аргументів вибирає повний діапазон результатів. Аргумент flags може бути однією або декількома константами AI_* і впливатиме на спосіб обчислення та повернення результатів. Наприклад, AI_NUMERICHOST вимкне розпізнавання доменного імені та викличе помилку, якщо host є доменним іменем.

Функція повертає список із 5-ти кортежів із такою структурою:

(сімейство, тип, прото, canonname, sockaddr)

In these tuples, family, type, proto are all integers and are meant to be passed to the socket() function. canonname will be a string representing the canonical name of the host if AI_CANONNAME is part of the flags argument; else canonname will be empty. sockaddr is a tuple describing a socket address, whose format depends on the returned family (a (address, port) 2-tuple for AF_INET, a (address, port, flowinfo, scope_id) 4-tuple for AF_INET6), and is meant to be passed to the socket.connect() method.

Викликає подію аудиту socket.getaddrinfo з аргументами хост, порт, сімейство, тип, протокол.

У наступному прикладі отримується інформація про адресу для гіпотетичного TCP-з’єднання з example.org на порту 80 (результати можуть відрізнятися у вашій системі, якщо IPv6 не ввімкнено):

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(<AddressFamily.AF_INET6: 10>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (<AddressFamily.AF_INET: 2>, <SocketType.SOCK_STREAM: 1>,
 6, '', ('93.184.216.34', 80))]

Змінено в версії 3.2: параметри тепер можна передавати за допомогою аргументів ключових слів.

Змінено в версії 3.7: для багатоадресних адрес IPv6 рядок, що представляє адресу, не міститиме частину %scope_id.

socket.getfqdn([name])

Повернути повне доменне ім’я для name. Якщо ім’я опущене або порожнє, воно інтерпретується як локальний хост. Щоб знайти повне ім’я, перевіряється ім’я хоста, яке повертає gethostbyaddr(), а потім ідуть псевдоніми хоста, якщо вони доступні. Вибрано перше ім’я, яке містить крапку. Якщо повне доменне ім’я недоступне, а було вказано ім’я, воно повертається без змін. Якщо name було порожнім або дорівнює '0.0.0.0', повертається ім’я хоста з gethostname().

socket.gethostbyname(hostname)

Перекладіть ім’я хоста у формат адреси IPv4. Адреса IPv4 повертається у вигляді рядка, наприклад '100.50.200.5. Якщо ім’я хоста є адресою IPv4, воно повертається без змін. Дивіться gethostbyname_ex() для більш повного інтерфейсу. gethostbyname() не підтримує розпізнавання імен IPv6, а getaddrinfo() слід використовувати замість цього для підтримки подвійного стеку IPv4/v6.

Викликає подію аудиту socket.gethostbyname з аргументом hostname.

socket.gethostbyname_ex(hostname)

Translate a host name to IPv4 address format, extended interface. Return a triple (hostname, aliaslist, ipaddrlist) where hostname is the host’s primary host name, aliaslist is a (possibly empty) list of alternative host names for the same address, and ipaddrlist is a list of IPv4 addresses for the same interface on the same host (often but not always a single address). gethostbyname_ex() does not support IPv6 name resolution, and getaddrinfo() should be used instead for IPv4/v6 dual stack support.

Викликає подію аудиту socket.gethostbyname з аргументом hostname.

socket.gethostname()

Повертає рядок, що містить ім’я хоста машини, на якій зараз виконується інтерпретатор Python.

Викликає подію аудиту socket.gethostname без аргументів.

Примітка: gethostname() не завжди повертає повне доменне ім’я; використовуйте для цього getfqdn().

socket.gethostbyaddr(ip_address)

Return a triple (hostname, aliaslist, ipaddrlist) where hostname is the primary host name responding to the given ip_address, aliaslist is a (possibly empty) list of alternative host names for the same address, and ipaddrlist is a list of IPv4/v6 addresses for the same interface on the same host (most likely containing only a single address). To find the fully qualified domain name, use the function getfqdn(). gethostbyaddr() supports both IPv4 and IPv6.

Викликає подію аудиту socket.gethostbyaddr з аргументом ip_address.

socket.getnameinfo(sockaddr, flags)

Translate a socket address sockaddr into a 2-tuple (host, port). Depending on the settings of flags, the result can contain a fully-qualified domain name or numeric address representation in host. Similarly, port can contain a string port name or a numeric port number.

Для адрес IPv6 %scope_id додається до частини хоста, якщо sockaddr містить значимий scope_id. Зазвичай це відбувається для багатоадресних адрес.

Для отримання додаткової інформації про прапори ви можете звернутися до getnameinfo(3).

Викликає подію аудиту socket.getnameinfo з аргументом sockaddr.

socket.getprotobyname(protocolname)

Translate an Internet protocol name (for example, 'icmp') to a constant suitable for passing as the (optional) third argument to the socket() function. This is usually only needed for sockets opened in «raw» mode (SOCK_RAW); for the normal socket modes, the correct protocol is chosen automatically if the protocol is omitted or zero.

socket.getservbyname(servicename[, protocolname])

Translate an Internet service name and protocol name to a port number for that service. The optional protocol name, if given, should be 'tcp' or 'udp', otherwise any protocol will match.

Викликає подію аудиту socket.getservbyname з аргументами servicename, protocolname.

socket.getservbyport(port[, protocolname])

Translate an Internet port number and protocol name to a service name for that service. The optional protocol name, if given, should be 'tcp' or 'udp', otherwise any protocol will match.

Викликає подію аудиту socket.getservbyport з аргументами port, protocolname.

socket.ntohl(x)

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

socket.ntohs(x)

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

Застаріло починаючи з версії 3.7: In case x does not fit in 16-bit unsigned integer, but does fit in a positive C int, it is silently truncated to 16-bit unsigned integer. This silent truncation feature is deprecated, and will raise an exception in future versions of Python.

socket.htonl(x)

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

socket.htons(x)

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

Застаріло починаючи з версії 3.7: In case x does not fit in 16-bit unsigned integer, but does fit in a positive C int, it is silently truncated to 16-bit unsigned integer. This silent truncation feature is deprecated, and will raise an exception in future versions of Python.

socket.inet_aton(ip_string)

Convert an IPv4 address from dotted-quad string format (for example, „123.45.67.89“) to 32-bit packed binary format, as a bytes object four characters in length. This is useful when conversing with a program that uses the standard C library and needs objects of type struct in_addr, which is the C type for the 32-bit packed binary this function returns.

inet_aton() також приймає рядки з менш ніж трьома крапками; подробиці див. на сторінці посібника Unix inet(3).

Якщо рядок адреси IPv4, переданий цій функції, недійсний, буде викликано OSError. Зауважте, що саме те, що є дійсним, залежить від базової реалізації C inet_aton().

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

socket.inet_ntoa(packed_ip)

Convert a 32-bit packed IPv4 address (a bytes-like object four bytes in length) to its standard dotted-quad string representation (for example, „123.45.67.89“). This is useful when conversing with a program that uses the standard C library and needs objects of type struct in_addr, which is the C type for the 32-bit packed binary data this function takes as an argument.

Якщо послідовність байтів, передана цій функції, не має довжини точно 4 байти, виникне OSError. inet_ntoa() не підтримує IPv6, а inet_ntop() слід використовувати замість цього для підтримки подвійного стеку IPv4/v6.

Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

socket.inet_pton(address_family, ip_string)

Convert an IP address from its family-specific string format to a packed, binary format. inet_pton() is useful when a library or network protocol calls for an object of type struct in_addr (similar to inet_aton()) or struct in6_addr.

Підтримувані значення для address_family наразі: AF_INET і AF_INET6. Якщо рядок IP-адреси ip_string недійсний, виникне OSError. Зауважте, що саме те, що є дійсним, залежить як від значення address_family, так і від базової реалізації inet_pton().

Availability: Unix (maybe not all platforms), Windows.

Змінено в версії 3.4: Додано підтримку Windows

socket.inet_ntop(address_family, packed_ip)

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

Підтримувані значення для address_family наразі: AF_INET і AF_INET6. Якщо об’єкт bytes packed_ip не має правильної довжини для вказаного сімейства адрес, буде викликано ValueError. OSError викликається для помилок виклику inet_ntop().

Availability: Unix (maybe not all platforms), Windows.

Змінено в версії 3.4: Додано підтримку Windows

Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

socket.CMSG_LEN(length)

Повертає загальну довжину, без заповнення в кінці, елемента допоміжних даних із пов’язаними даними заданої довжини. Це значення часто можна використовувати як розмір буфера для recvmsg() для отримання окремого елемента допоміжних даних, але RFC 3542 вимагає, щоб портативні програми використовували CMSG_SPACE() і таким чином включали простір для заповнення, навіть якщо елемент буде останнім у буфері. Викликає OverflowError, якщо length виходить за межі допустимого діапазону значень.

Availability: most Unix platforms, possibly others.

Нове в версії 3.3.

socket.CMSG_SPACE(length)

Повертає розмір буфера, необхідний для recvmsg() для отримання елемента допоміжних даних із пов’язаними даними заданої довжини разом із будь-яким доповненням у кінці. Буферний простір, необхідний для отримання кількох елементів, є сумою значень CMSG_SPACE() для відповідної довжини даних. Викликає OverflowError, якщо length виходить за межі допустимого діапазону значень.

Зауважте, що деякі системи можуть підтримувати допоміжні дані без надання цієї функції. Також зауважте, що встановлення розміру буфера за допомогою результатів цієї функції може не обмежувати точно кількість допоміжних даних, які можна отримати, оскільки додаткові дані можуть поміститися в область заповнення.

Availability: most Unix platforms, possibly others.

Нове в версії 3.3.

socket.getdefaulttimeout()

Повертає стандартний час очікування в секундах (float) для нових об’єктів сокета. Значення None вказує на те, що нові об’єкти сокета не мають часу очікування. Коли модуль сокета імпортовано вперше, за замовчуванням буде None.

socket.setdefaulttimeout(timeout)

Встановіть стандартний час очікування в секундах (float) для нових об’єктів сокета. Коли модуль сокета імпортовано вперше, за замовчуванням буде None. Перегляньте settimeout() можливі значення та їх відповідні значення.

socket.sethostname(name)

Встановіть ім’я хоста машини на name. Це викличе OSError, якщо у вас недостатньо прав.

Викликає подію аудиту socket.sethostname з аргументом name.

Наявність: Unix.

Нове в версії 3.3.

socket.if_nameindex()

Повертає список кортежів інформації про мережевий інтерфейс (index int, name string). OSError, якщо системний виклик не вдається.

Наявність: Unix, Windows.

Нове в версії 3.3.

Змінено в версії 3.8: Додано підтримку Windows.

Примітка

У Windows мережеві інтерфейси мають різні імена в різних контекстах (усі імена є прикладами):

  • UUID: {FB605B73-AAC2-49A6-9A2F-25416AEA0573}

  • назва: ethernet_32770

  • зрозуміла назва: vEthernet (nat)

  • опис: Hyper-V Virtual Ethernet Adapter

Ця функція повертає імена другої форми зі списку, ethernet_32770 у цьому прикладі.

socket.if_nametoindex(if_name)

Повертає номер індексу мережевого інтерфейсу, який відповідає імені інтерфейсу. OSError, якщо не існує інтерфейсу з вказаною назвою.

Наявність: Unix, Windows.

Нове в версії 3.3.

Змінено в версії 3.8: Додано підтримку Windows.

Дивись також

«Назва інтерфейсу» — це назва, задокументована в if_nameindex().

socket.if_indextoname(if_index)

Повертає назву мережевого інтерфейсу, що відповідає номеру індексу інтерфейсу. OSError, якщо не існує інтерфейсу з даним індексом.

Наявність: Unix, Windows.

Нове в версії 3.3.

Змінено в версії 3.8: Додано підтримку Windows.

Дивись також

«Назва інтерфейсу» — це назва, задокументована в if_nameindex().

socket.send_fds(sock, buffers, fds[, flags[, address]])

Send the list of file descriptors fds over an AF_UNIX socket sock. The fds parameter is a sequence of file descriptors. Consult sendmsg() for the documentation of these parameters.

Availability: Unix supporting sendmsg() and SCM_RIGHTS mechanism.

Нове в версії 3.9.

socket.recv_fds(sock, bufsize, maxfds[, flags])

Receive up to maxfds file descriptors from an AF_UNIX socket sock. Return (msg, list(fds), flags, addr). Consult recvmsg() for the documentation of these parameters.

Availability: Unix supporting recvmsg() and SCM_RIGHTS mechanism.

Нове в версії 3.9.

Примітка

Будь-які скорочені цілі числа в кінці списку дескрипторів файлів.

Об’єкти Socket

Об’єкти Socket мають такі методи. За винятком makefile(), вони відповідають системним викликам Unix, застосовним до сокетів.

Змінено в версії 3.2: Додано підтримку протоколу context manager. Вихід із контекстного менеджера еквівалентний виклику close().

socket.accept()

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

Новостворений сокет не успадковується.

Змінено в версії 3.4: Тепер сокет не успадковується.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.bind(address)

Прив’яжіть сокет до адреси. Розетка ще не повинна бути прив’язаною. (Формат адреси залежить від групи адрес — див. вище.)

Викликає подію аудиту socket.bind з аргументами self, address.

socket.close()

Mark the socket closed. The underlying system resource (e.g. a file descriptor) is also closed when all file objects from makefile() are closed. Once that happens, all future operations on the socket object will fail. The remote end will receive no more data (after queued data is flushed).

Сокети автоматично закриваються під час збирання сміття, але рекомендується close() їх явно або використовувати оператор with навколо них.

Змінено в версії 3.6: OSError тепер викликається, якщо виникає помилка під час основного виклику close().

Примітка

close() releases the resource associated with a connection but does not necessarily close the connection immediately. If you want to close the connection in a timely fashion, call shutdown() before close().

socket.connect(address)

Підключіться до віддаленої розетки за адресою. (Формат адреси залежить від групи адрес — див. вище.)

If the connection is interrupted by a signal, the method waits until the connection completes, or raise a socket.timeout on timeout, if the signal handler doesn’t raise an exception and the socket is blocking or has a timeout. For non-blocking sockets, the method raises an InterruptedError exception if the connection is interrupted by a signal (or the exception raised by the signal handler).

Викликає подію аудиту socket.connect з аргументами self, address.

Змінено в версії 3.5: Тепер метод очікує, доки з’єднання завершиться, замість того, щоб викликати виняток InterruptedError, якщо з’єднання перервано сигналом, обробник сигналу не викликає виключення, а сокет блокується або має тайм-аут (див. PEP 475 для обґрунтування).

socket.connect_ex(address)

Подібно до connect(address), але повертає індикатор помилки замість виклику винятку для помилок, які повертає виклик connect() рівня C (інші проблеми, такі як «хост не знайдено», можуть все ще викликають винятки). Індикатор помилки – 0, якщо операція виконана успішно, інакше значення змінної errno. Це корисно для підтримки, наприклад, асинхронних підключень.

Викликає подію аудиту socket.connect з аргументами self, address.

socket.detach()

Переведіть об’єкт сокета в закритий стан, фактично не закриваючи базовий файловий дескриптор. Файловий дескриптор повертається, і його можна повторно використовувати для інших цілей.

Нове в версії 3.2.

socket.dup()

Дублюйте розетку.

Новостворений сокет не успадковується.

Змінено в версії 3.4: Тепер сокет не успадковується.

socket.fileno()

Повертає дескриптор файлу сокета (мале ціле число) або -1 у разі помилки. Це корисно з select.select().

Під Windows мале ціле число, яке повертає цей метод, не можна використовувати там, де можна використовувати дескриптор файлу (наприклад, os.fdopen()). Unix не має цього обмеження.

socket.get_inheritable()

Отримайте inheritable flag дескриптора файлу сокета або дескриптора сокета: True, якщо сокет можна успадкувати в дочірніх процесах, False, якщо це неможливо.

Нове в версії 3.4.

socket.getpeername()

Повертає віддалену адресу, до якої підключений сокет. Це корисно, наприклад, щоб дізнатися номер порту віддаленого сокета IPv4/v6. (Формат адреси, що повертається, залежить від родини адрес — див. вище.) У деяких системах ця функція не підтримується.

socket.getsockname()

Повернути власну адресу сокета. Це корисно, наприклад, щоб дізнатися номер порту сокета IPv4/v6. (Формат адреси, що повертається, залежить від сімейства адрес — див. вище.)

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

Return the value of the given socket option (see the Unix man page getsockopt(2)). The needed symbolic constants (SO_* etc.) are defined in this module. If buflen is absent, an integer option is assumed and its integer value is returned by the function. If buflen is present, it specifies the maximum length of the buffer used to receive the option in, and this buffer is returned as a bytes object. It is up to the caller to decode the contents of the buffer (see the optional built-in module struct for a way to decode C structures encoded as byte strings).

socket.getblocking()

Повертає True, якщо сокет знаходиться в режимі блокування, False, якщо він не блокується.

This is equivalent to checking socket.gettimeout() == 0.

Нове в версії 3.7.

socket.gettimeout()

Повертає тайм-аут у секундах (float), пов’язаний з операціями сокета, або None, якщо тайм-аут не встановлено. Це відображає останній виклик setblocking() або settimeout().

socket.ioctl(control, option)
платформа

вікна

Метод ioctl() є обмеженим інтерфейсом системного інтерфейсу WSAIoctl. Будь ласка, зверніться до документації Win32 для отримання додаткової інформації.

На інших платформах можна використовувати загальні функції fcntl.fcntl() і fcntl.ioctl(); вони приймають об’єкт сокета як свій перший аргумент.

Наразі підтримуються лише такі керуючі коди: SIO_RCVALL, SIO_KEEPALIVE_VALS і SIO_LOOPBACK_FAST_PATH.

Змінено в версії 3.6: SIO_LOOPBACK_FAST_PATH було додано.

socket.listen([backlog])

Увімкніть сервер для прийняття підключень. Якщо вказано backlog, воно має бути принаймні 0 (якщо менше, то встановлюється на 0); він визначає кількість неприйнятих підключень, які система дозволить перед тим, як відхилити нові підключення. Якщо не вказано, вибирається розумне значення за умовчанням.

Змінено в версії 3.5: Параметр backlog тепер необов’язковий.

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

Return a file object associated with the socket. The exact returned type depends on the arguments given to makefile(). These arguments are interpreted the same way as by the built-in open() function, except the only supported mode values are 'r' (default), 'w' and 'b'.

Розетка повинна бути в режимі блокування; він може мати тайм-аут, але внутрішній буфер файлового об’єкта може опинитися в неузгодженому стані, якщо відбудеться тайм-аут.

Закриття файлового об’єкта, який повертає makefile(), не закриє оригінальний сокет, якщо всі інші файлові об’єкти не закриті та socket.close() не викликано для об’єкта сокета.

Примітка

У Windows файлоподібний об’єкт, створений makefile(), не можна використовувати там, де очікується файловий об’єкт із дескриптором файлу, наприклад аргументи потоку subprocess.Popen().

socket.recv(bufsize[, flags])

Receive data from the socket. The return value is a bytes object representing the data received. The maximum amount of data to be received at once is specified by bufsize. See the Unix manual page recv(2) for the meaning of the optional argument flags; it defaults to zero.

Примітка

Для найкращої відповідності апаратному забезпеченню та мережевим реаліям значення bufsize має бути відносно малим ступенем 2, наприклад, 4096.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.recvfrom(bufsize[, flags])

Отримувати дані з розетки. Поверненим значенням є пара (байти, адреса), де байт — об’єкт байтів, що представляє отримані дані, а адреса — адреса сокета, який надсилає дані. Перегляньте сторінку посібника Unix recv(2) для визначення значення необов’язкового аргументу flags; за замовчуванням він дорівнює нулю. (Формат адреси залежить від групи адрес — див. вище.)

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

Змінено в версії 3.7: Для багатоадресної адреси IPv6 перший елемент address більше не містить частини %scope_id. Щоб отримати повну адресу IPv6, використовуйте getnameinfo().

socket.recvmsg(bufsize[, ancbufsize[, flags]])

Отримувати звичайні дані (до bufsize байтів) і допоміжні дані з сокета. Аргумент ancbufsize встановлює розмір у байтах внутрішнього буфера, який використовується для отримання допоміжних даних; за замовчуванням він дорівнює 0, що означає, що допоміжні дані не будуть отримані. Відповідні розміри буферів для допоміжних даних можна обчислити за допомогою CMSG_SPACE() або CMSG_LEN(), а елементи, які не вміщаються в буфер, можуть бути скорочені або відкинуті. Аргумент flags за умовчанням дорівнює 0 і має те саме значення, що й для recv().

Повернене значення – це 4-кортеж: (data, ancdata, msg_flags, address). Елемент data — це об’єкт bytes, що містить отримані непобічні дані. Елемент ancdata — це список із нуля або більше кортежів (cmsg_level, cmsg_type, cmsg_data), що представляють отримані допоміжні дані (керуючі повідомлення): cmsg_level і cmsg_type — цілі числа, що визначають рівень протоколу та протокол- певного типу відповідно, і cmsg_data є об’єктом bytes, що містить пов’язані дані. Елемент msg_flags — це порозрядне АБО різних прапорів, що вказують на умови отриманого повідомлення; подробиці дивіться в системній документації. Якщо сокет-одержувач не підключений, адреса є адресою сокета-відправника, якщо він доступний; інакше його значення не вказано.

On some systems, sendmsg() and recvmsg() can be used to pass file descriptors between processes over an AF_UNIX socket. When this facility is used (it is often restricted to SOCK_STREAM sockets), recvmsg() will return, in its ancillary data, items of the form (socket.SOL_SOCKET, socket.SCM_RIGHTS, fds), where fds is a bytes object representing the new file descriptors as a binary array of the native C int type. If recvmsg() raises an exception after the system call returns, it will first attempt to close any file descriptors received via this mechanism.

Деякі системи не вказують скорочену довжину елементів допоміжних даних, які були отримані лише частково. Якщо елемент виходить за кінець буфера, recvmsg() видає RuntimeWarning і повертає його частину, яка знаходиться всередині буфера, за умови, що вона не була скорочена до початку своїх пов’язаних даних.

У системах, які підтримують механізм SCM_RIGHTS, наступна функція отримає до maxfds файлових дескрипторів, повертаючи дані повідомлення та список, що містить дескриптори (ігноруючи неочікувані умови, такі як отримання непов’язаних керуючих повідомлень). Дивіться також sendmsg().

import socket, array

def recv_fds(sock, msglen, maxfds):
    fds = array.array("i")   # Array of ints
    msg, ancdata, flags, addr = sock.recvmsg(msglen, socket.CMSG_LEN(maxfds * fds.itemsize))
    for cmsg_level, cmsg_type, cmsg_data in ancdata:
        if cmsg_level == socket.SOL_SOCKET and cmsg_type == socket.SCM_RIGHTS:
            # Append data, ignoring any truncated integers at the end.
            fds.frombytes(cmsg_data[:len(cmsg_data) - (len(cmsg_data) % fds.itemsize)])
    return msg, list(fds)

Availability: most Unix platforms, possibly others.

Нове в версії 3.3.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.recvmsg_into(buffers[, ancbufsize[, flags]])

Отримувати звичайні дані та допоміжні дані з сокета, поводячись так, як це зробив би recvmsg(), але розкидати не допоміжні дані в ряд буферів замість повернення нового об’єкта bytes. Аргумент buffers має бути ітерованим об’єктами, які експортують записувані буфери (наприклад, об’єкти bytearray); вони будуть заповнені послідовними фрагментами непоміжних даних, доки вони не будуть записані або більше не залишиться буферів. Операційна система може встановити обмеження (sysconf() значення SC_IOV_MAX) на кількість буферів, які можна використовувати. Аргументи ancbufsize і flags мають те саме значення, що й для recvmsg().

Повернене значення — це 4-кортеж: (nbytes, ancdata, msg_flags, address), де nbytes — загальна кількість байтів непоміжних даних, записаних у буфери, а ancdata, msg_flags і адреса такі самі, як і для recvmsg().

Приклад:

>>> import socket
>>> s1, s2 = socket.socketpair()
>>> b1 = bytearray(b'----')
>>> b2 = bytearray(b'0123456789')
>>> b3 = bytearray(b'--------------')
>>> s1.send(b'Mary had a little lamb')
22
>>> s2.recvmsg_into([b1, memoryview(b2)[2:9], b3])
(22, [], 0, None)
>>> [b1, b2, b3]
[bytearray(b'Mary'), bytearray(b'01 had a 9'), bytearray(b'little lamb---')]

Availability: most Unix platforms, possibly others.

Нове в версії 3.3.

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

Отримувати дані з сокета, записуючи їх у буфер замість створення нового байтового рядка. Поверненим значенням є пара (nbytes, address), де nbytes — це кількість отриманих байтів, а address — це адреса сокета, який надсилає дані. Перегляньте сторінку посібника Unix recv(2) для визначення значення необов’язкового аргументу flags; за замовчуванням він дорівнює нулю. (Формат адреси залежить від групи адрес — див. вище.)

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

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

socket.send(bytes[, flags])

Надіслати дані в сокет. Розетка повинна бути підключена до віддаленої розетки. Необов’язковий аргумент flags має те саме значення, що й для recv() вище. Повертає кількість надісланих байтів. Додатки відповідають за перевірку того, що всі дані були надіслані; якщо було передано лише частину даних, програма повинна спробувати доставити решту даних. Для отримання додаткової інформації з цієї теми зверніться до HOWTO з програмування сокетів.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.sendall(bytes[, flags])

Надіслати дані в сокет. Розетка повинна бути підключена до віддаленої розетки. Необов’язковий аргумент flags має те саме значення, що й для recv() вище. На відміну від send(), цей метод продовжує надсилати дані з байтів, доки не буде надіслано всі дані або не станеться помилка. None повертається в разі успіху. У разі помилки виникає виняток, і немає способу визначити, скільки даних було успішно надіслано, якщо такі були.

Змінено в версії 3.5: The socket timeout is no more reset each time data is sent successfully. The socket timeout is now the maximum total duration to send all data.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.sendto(bytes, address)
socket.sendto(bytes, flags, address)

Надіслати дані в сокет. Сокет не слід підключати до віддаленого сокета, оскільки сокет призначення вказується адресою. Необов’язковий аргумент flags має те саме значення, що й для recv() вище. Повертає кількість надісланих байтів. (Формат адреси залежить від групи адрес — див. вище.)

Викликає подію аудиту socket.sendto з аргументами self, address.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.sendmsg(buffers[, ancdata[, flags[, address]]])

Надсилайте звичайні та допоміжні дані в сокет, збираючи недопоміжні дані з ряду буферів і об’єднуючи їх в одне повідомлення. Аргумент buffers вказує на не допоміжні дані як ітерацію bytes-подібних об’єктів (наприклад, bytes об’єктів); операційна система може встановити обмеження (sysconf() значення SC_IOV_MAX) на кількість буферів, які можна використовувати. Аргумент ancdata визначає допоміжні дані (керуючі повідомлення) як ітерацію з нуля або більше кортежів (cmsg_level, cmsg_type, cmsg_data), де cmsg_level і cmsg_type є цілими числами, що визначають рівень протоколу та протокол- певного типу відповідно, а cmsg_data — це байтиподібний об’єкт, що містить пов’язані дані. Зверніть увагу, що деякі системи (зокрема, системи без CMSG_SPACE()) можуть підтримувати надсилання лише одного керуючого повідомлення на виклик. Аргумент flags за умовчанням дорівнює 0 і має те саме значення, що й для send(). Якщо вказано address, а не None, це встановлює адресу призначення для повідомлення. Повернене значення — це кількість байтів надісланих непоміжних даних.

Наступна функція надсилає список дескрипторів файлів fds через сокет AF_UNIX у системах, які підтримують механізм SCM_RIGHTS. Дивіться також recvmsg().

import socket, array

def send_fds(sock, msg, fds):
    return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, array.array("i", fds))])

Availability: most Unix platforms, possibly others.

Викликає подію аудиту socket.sendmsg з аргументами self, address.

Нове в версії 3.3.

Змінено в версії 3.5: Якщо системний виклик перервано, а обробник сигналу не викликає виключення, метод тепер повторює системний виклик замість того, щоб викликати виняток InterruptedError (перегляньте PEP 475 для обґрунтування).

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])

Спеціалізована версія sendmsg() для AF_ALG сокета. Установіть довжину пов’язаних даних режиму, IV, AEAD і прапорці для сокета AF_ALG.

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

Нове в версії 3.6.

socket.sendfile(file, offset=0, count=None)

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

Нове в версії 3.5.

socket.set_inheritable(inheritable)

Установіть inheritable flag дескриптора файлу сокета або дескриптора сокета.

Нове в версії 3.4.

socket.setblocking(flag)

Встановіть блокуючий або неблокуючий режим сокета: якщо flag має значення false, сокет встановлено в неблокуючий режим, інакше в режим блокування.

Цей метод є скороченням певних викликів settimeout():

  • sock.setblocking(True) еквівалентно sock.settimeout(None)

  • sock.setblocking(False) еквівалентний sock.settimeout(0.0)

Змінено в версії 3.7: Метод більше не застосовує прапор SOCK_NONBLOCK до socket.type.

socket.settimeout(value)

Set a timeout on blocking socket operations. The value argument can be a nonnegative floating point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations will raise a timeout exception if the timeout period value has elapsed before the operation has completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket is put in blocking mode.

Щоб отримати додаткову інформацію, зверніться до приміток щодо тайм-аутів сокетів.

Змінено в версії 3.7: Метод більше не вмикає прапор SOCK_NONBLOCK на socket.type.

socket.setsockopt(level, optname, value: int)
socket.setsockopt(level, optname, value: buffer)
socket.setsockopt(level, optname, None, optlen: int)

Set the value of the given socket option (see the Unix manual page setsockopt(2)). The needed symbolic constants are defined in the socket module (SO_* etc.). The value can be an integer, None or a bytes-like object representing a buffer. In the later case it is up to the caller to ensure that the bytestring contains the proper bits (see the optional built-in module struct for a way to encode C structures as bytestrings). When value is set to None, optlen argument is required. It’s equivalent to call setsockopt() C function with optval=NULL and optlen=optlen.

Змінено в версії 3.5: Записуваний bytes-like object тепер приймається.

Змінено в версії 3.6: Додано форму setsockopt(level, optname, None, optlen: int).

socket.shutdown(how)

Вимкніть одну або обидві половини з’єднання. Якщо how SHUT_RD, подальші прийоми заборонені. Якщо how SHUT_WR, подальші надсилання заборонені. Якщо how SHUT_RDWR, подальше надсилання та отримання заборонено.

socket.share(process_id)

Скопіюйте сокет і підготуйте його для спільного використання з цільовим процесом. Цільовому процесу має бути надано process_id. Отриманий об’єкт bytes потім можна передати цільовому процесу за допомогою певної форми міжпроцесного зв’язку, а сокет можна відтворити там за допомогою fromshare(). Після виклику цього методу можна безпечно закрити сокет, оскільки операційна система вже скопіювала його для цільового процесу.

Наявність: Windows.

Нове в версії 3.3.

Зверніть увагу, що немає методів read() або write(); замість цього використовуйте recv() і send() без аргументу flags.

Об’єкти Socket також мають ці атрибути (лише для читання), які відповідають значенням, наданим конструктору socket.

socket.family

Сімейство розеток.

socket.type

Тип розетки.

socket.proto

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

Примітки щодо тайм-аутів сокетів

Об’єкт сокета може бути в одному з трьох режимів: блокування, неблокування або час очікування. За умовчанням сокети завжди створюються в режимі блокування, але це можна змінити, викликавши setdefaulttimeout().

  • У режимі блокування операції блокуються до завершення або доки система не поверне повідомлення про помилку (наприклад, час очікування підключення закінчився).

  • In non-blocking mode, operations fail (with an error that is unfortunately system-dependent) if they cannot be completed immediately: functions from the select can be used to know when and whether a socket is available for reading or writing.

  • У режимі тайм-ауту операції завершуються невдало, якщо їх не можна завершити протягом тайм-ауту, указаного для сокета (вони викликають виняток timeout) або якщо система повертає помилку.

Примітка

At the operating system level, sockets in timeout mode are internally set in non-blocking mode. Also, the blocking and timeout modes are shared between file descriptors and socket objects that refer to the same network endpoint. This implementation detail can have visible consequences if e.g. you decide to use the fileno() of a socket.

Час очікування та метод connect

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

Час очікування та метод accept

Якщо getdefaulttimeout() не None, сокети, повернуті методом accept(), успадковують цей час очікування. В іншому випадку поведінка залежить від налаштувань прослуховувального сокета:

  • якщо прослуховувальний сокет знаходиться в режимі блокування або в режимі очікування, сокет, який повертає accept(), знаходиться в режимі блокування;

  • якщо сокет, що прослуховує, знаходиться в неблокуючому режимі, чи є сокет, повернутий accept() у блокуючому чи неблокуючому режимі, залежить від операційної системи. Якщо ви хочете забезпечити кросплатформну поведінку, радимо вручну змінити це налаштування.

приклад

Here are four minimal example programs using the TCP/IP protocol: a server that echoes all data that it receives back (servicing only one client), and a client using it. Note that a server must perform the sequence socket(), bind(), listen(), accept() (possibly repeating the accept() to service more than one client), while a client only needs the sequence socket(), connect(). Also note that the server does not sendall()/recv() on the socket it is listening on but on the new socket returned by accept().

Перші два приклади підтримують лише IPv4.

# Echo server program
import socket

HOST = ''                 # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.bind((HOST, PORT))
    s.listen(1)
    conn, addr = s.accept()
    with conn:
        print('Connected by', addr)
        while True:
            data = conn.recv(1024)
            if not data: break
            conn.sendall(data)

# Echo client program
import socket

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
    s.connect((HOST, PORT))
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

The next two examples are identical to the above two, but support both IPv4 and IPv6. The server side will listen to the first address family available (it should listen to both instead). On most of IPv6-ready systems, IPv6 will take precedence and the server may not accept IPv4 traffic. The client side will try to connect to the all addresses returned as a result of the name resolution, and sends traffic to the first one connected successfully.

# Echo server program
import socket
import sys

HOST = None               # Symbolic name meaning all available interfaces
PORT = 50007              # Arbitrary non-privileged port
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC,
                              socket.SOCK_STREAM, 0, socket.AI_PASSIVE):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.bind(sa)
        s.listen(1)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
conn, addr = s.accept()
with conn:
    print('Connected by', addr)
    while True:
        data = conn.recv(1024)
        if not data: break
        conn.send(data)

# Echo client program
import socket
import sys

HOST = 'daring.cwi.nl'    # The remote host
PORT = 50007              # The same port as used by the server
s = None
for res in socket.getaddrinfo(HOST, PORT, socket.AF_UNSPEC, socket.SOCK_STREAM):
    af, socktype, proto, canonname, sa = res
    try:
        s = socket.socket(af, socktype, proto)
    except OSError as msg:
        s = None
        continue
    try:
        s.connect(sa)
    except OSError as msg:
        s.close()
        s = None
        continue
    break
if s is None:
    print('could not open socket')
    sys.exit(1)
with s:
    s.sendall(b'Hello, world')
    data = s.recv(1024)
print('Received', repr(data))

У наступному прикладі показано, як написати дуже простий мережевий сніфер із необробленими сокетами у Windows. У прикладі потрібні права адміністратора, щоб змінити інтерфейс:

import socket

# the public network interface
HOST = socket.gethostbyname(socket.gethostname())

# create a raw socket and bind it to the public interface
s = socket.socket(socket.AF_INET, socket.SOCK_RAW, socket.IPPROTO_IP)
s.bind((HOST, 0))

# Include IP headers
s.setsockopt(socket.IPPROTO_IP, socket.IP_HDRINCL, 1)

# receive all packages
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a package
print(s.recvfrom(65565))

# disabled promiscuous mode
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_OFF)

У наступному прикладі показано, як використовувати інтерфейс сокета для зв’язку з мережею CAN за допомогою необробленого протоколу сокета. Щоб замість цього використовувати CAN із протоколом диспетчера трансляції, відкрийте сокет за допомогою:

socket.socket(socket.AF_CAN, socket.SOCK_DGRAM, socket.CAN_BCM)

After binding (CAN_RAW) or connecting (CAN_BCM) the socket, you can use the socket.send(), and the socket.recv() operations (and their counterparts) on the socket object as usual.

Цей останній приклад може вимагати спеціальних привілеїв:

import socket
import struct


# CAN frame packing/unpacking (see 'struct can_frame' in <linux/can.h>)

can_frame_fmt = "=IB3x8s"
can_frame_size = struct.calcsize(can_frame_fmt)

def build_can_frame(can_id, data):
    can_dlc = len(data)
    data = data.ljust(8, b'\x00')
    return struct.pack(can_frame_fmt, can_id, can_dlc, data)

def dissect_can_frame(frame):
    can_id, can_dlc, data = struct.unpack(can_frame_fmt, frame)
    return (can_id, can_dlc, data[:can_dlc])


# create a raw socket and bind it to the 'vcan0' interface
s = socket.socket(socket.AF_CAN, socket.SOCK_RAW, socket.CAN_RAW)
s.bind(('vcan0',))

while True:
    cf, addr = s.recvfrom(can_frame_size)

    print('Received: can_id=%x, can_dlc=%x, data=%s' % dissect_can_frame(cf))

    try:
        s.send(cf)
    except OSError:
        print('Error sending CAN frame')

    try:
        s.send(build_can_frame(0x01, b'\x01\x02\x03'))
    except OSError:
        print('Error sending CAN frame')

Запуск прикладу кілька разів із занадто малою затримкою між виконаннями може призвести до цієї помилки:

OSError: [Errno 98] Address already in use

Це пов’язано з тим, що попереднє виконання залишило сокет у стані TIME_WAIT і не може бути негайно повторно використано.

There is a socket flag to set, in order to prevent this, 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, не чекаючи закінчення його природного часу очікування.

Дивись також

Для ознайомлення з програмуванням сокетів (на C) перегляньте такі документи:

  • Вступний навчальний посібник із взаємодії між процесами 4.3BSD, Стюарт Сехрест

  • Навчальний посібник із розширеного міжпроцесного зв’язку 4.3BSD, Семюел Дж. Леффлер та інші,

обидва в Посібнику програміста UNIX, Додаткові документи 1 (розділи PS1:7 та PS1:8). Довідковий матеріал для певної платформи для різноманітних системних викликів, пов’язаних із сокетами, також є цінним джерелом інформації про деталі семантики сокетів. Для Unix зверніться до сторінок посібника; для Windows дивіться специфікацію WinSock (або Winsock 2). Щодо API, готових до IPv6, читачі можуть звернутися до RFC 3493 під назвою Basic Socket Interface Extensions for IPv6.