`socket` — Low-level networking interface¶

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

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

Примітка

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

Availability: not Emscripten, not WASI.

This module does not work or is not available on WebAssembly platforms wasm32-emscripten and wasm32-wasi. See WebAssembly platforms for more information.

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 тепер приймається.

Пара (хост, порт) використовується для родини адрес AF_INET, де хост — це рядок, який представляє або ім’я хоста в нотації домену Інтернету, як-от 'daring.cwi.nl' або адреса IPv4, наприклад '100.50.200.5'', і порт є цілим числом.
- Для адрес 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.

Added in version 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.

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

Availability: Linux >= 3.9

See vsock(7)

Added in version 3.7.
AF_PACKET is a low-level interface directly to network devices. The addresses are represented by the tuple (ifname, proto[, pkttype[, hatype[, addr]]]) where:
- ifname - Рядок, що визначає назву пристрою.
- proto - The Ethernet protocol number. May be ETH_P_ALL to capture all protocols, one of the ETHERTYPE_* constants or any other Ethernet protocol number.
- pkttype - додаткове ціле число, що вказує тип пакета:
  - PACKET_HOST (за замовчуванням) - пакет, адресований локальному хосту.
  - PACKET_BROADCAST - широкомовний пакет фізичного рівня.
  - PACKET_MULTICAST - 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.

Added in version 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

Added in version 3.9.
AF_HYPERV is a Windows-only socket based interface for communicating with Hyper-V hosts and guests. The address family is represented as a (vm_id, service_id) tuple where the vm_id and service_id are UUID strings.

The vm_id is the virtual machine identifier or a set of known VMID values if the target is not a specific virtual machine. Known VMID constants defined on socket are:
- HV_GUID_ZERO
- HV_GUID_BROADCAST
- HV_GUID_WILDCARD - Used to bind on itself and accept connections from all partitions.
- HV_GUID_CHILDREN - Used to bind on itself and accept connection from child partitions.
- HV_GUID_LOOPBACK - Used as a target to itself.
- HV_GUID_PARENT - When used as a bind accepts connection from the parent partition. When used as an address target it will connect to the parent partition.
The service_id is the service identifier of the registered service.

Added in version 3.12.

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

Усі помилки викликають винятки. Можна викликати звичайні винятки для недійсних типів аргументів і умов браку пам’яті. Помилки, пов’язані із семантикою сокета чи адреси, викликають OSError або один із його підкласів.

Неблокуючий режим підтримується через 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¶

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

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

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

Змінено в версії 3.10: Цей клас отримав псевдонім TimeoutError.

Константи¶

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

Added in version 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.AF_UNSPEC¶: AF_UNSPEC means that getaddrinfo() should return socket addresses for any address family (either IPv4, IPv6, or any other) that can be used.

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.

Availability: Linux >= 2.6.27.

Added in version 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 підтримує режим виконання.

Змінено в версії 3.10: IP_RECVTOS було додано. Додано TCP_KEEPALIVE. У MacOS цю константу можна використовувати так само, як TCP_KEEPIDLE використовується в Linux.

Змінено в версії 3.11: Added TCP_CONNECTION_INFO. On MacOS this constant can be used in the same way that TCP_INFO is used on Linux and BSD.

Змінено в версії 3.12: Added SO_RTABLE and SO_USER_COOKIE. On OpenBSD and FreeBSD respectively those constants can be used in the same way that SO_MARK is used on Linux. Also added missing TCP socket options from Linux: TCP_MD5SIG, TCP_THIN_LINEAR_TIMEOUTS, TCP_THIN_DUPACK, TCP_REPAIR, TCP_REPAIR_QUEUE, TCP_QUEUE_SEQ, TCP_REPAIR_OPTIONS, TCP_TIMESTAMP, TCP_CC_INFO, TCP_SAVE_SYN, TCP_SAVED_SYN, TCP_REPAIR_WINDOW, TCP_FASTOPEN_CONNECT, TCP_ULP, TCP_MD5SIG_EXT, TCP_FASTOPEN_KEY, TCP_FASTOPEN_NO_COOKIE, TCP_ZEROCOPY_RECEIVE, TCP_INQ, TCP_TX_DELAY. Added IP_PKTINFO, IP_UNBLOCK_SOURCE, IP_BLOCK_SOURCE, IP_ADD_SOURCE_MEMBERSHIP, IP_DROP_SOURCE_MEMBERSHIP.

socket.AF_CAN¶
socket.PF_CAN¶
SOL_CAN_*
CAN_*: Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

Availability: Linux >= 2.6.25, NetBSD >= 8.

Added in version 3.3.

Змінено в версії 3.11: NetBSD support was added.

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

Availability: Linux >= 2.6.25.

Примітка

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

Added in version 3.4.

socket.CAN_RAW_FD_FRAMES¶

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

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

Availability: Linux >= 3.6.

Added in version 3.5.

socket.CAN_RAW_JOIN_FILTERS¶

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

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

Availability: Linux >= 4.1.

Added in version 3.9.

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

Availability: Linux >= 2.6.25.

Added in version 3.7.

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

Availability: Linux >= 5.4.

Added in version 3.9.

socket.AF_DIVERT¶
socket.PF_DIVERT¶: These two constants, documented in the FreeBSD divert(4) manual page, are also defined in the socket module.

Availability: FreeBSD >= 14.0.

Added in version 3.12.

socket.AF_PACKET¶
socket.PF_PACKET¶
PACKET_*: Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

Availability: Linux >= 2.2.

socket.ETH_P_ALL¶

ETH_P_ALL can be used in the socket constructor as proto for the AF_PACKET family in order to capture every packet, regardless of protocol.

For more information, see the packet(7) manpage.

Availability: Linux.

Added in version 3.12.

socket.AF_RDS¶
socket.PF_RDS¶
socket.SOL_RDS¶
RDS_*: Багато констант цих форм, задокументованих у документації Linux, також визначені в модулі сокета.

Availability: Linux >= 2.6.30.

Added in version 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.

Availability: Linux >= 2.6.38.

Added in version 3.6.

socket.AF_VSOCK¶
socket.IOCTL_VM_SOCKETS_GET_LOCAL_CID¶
VMADDR*
SO_VM*: Константи для зв’язку хост/гость Linux.

Availability: Linux >= 4.8.

Added in version 3.7.

socket.AF_LINK¶: Availability: BSD, macOS.

Added in version 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, який використовується для зв’язку з віддаленими процесорами, що надають послуги.

Availability: Linux >= 4.7.

socket.SCM_CREDS2¶
socket.LOCAL_CREDS¶
socket.LOCAL_CREDS_PERSISTENT¶: LOCAL_CREDS and LOCAL_CREDS_PERSISTENT can be used with SOCK_DGRAM, SOCK_STREAM sockets, equivalent to Linux/DragonFlyBSD SO_PASSCRED, while LOCAL_CREDS sends the credentials at first read, LOCAL_CREDS_PERSISTENT sends for each read, SCM_CREDS2 must be then used for the latter for the message type.

Added in version 3.11.

Availability: FreeBSD.

socket.SO_INCOMING_CPU¶: Constant to optimize CPU locality, to be used in conjunction with SO_REUSEPORT.

Added in version 3.11.

Availability: Linux >= 3.9

socket.AF_HYPERV¶
socket.HV_PROTOCOL_RAW¶
socket.HVSOCKET_CONNECT_TIMEOUT¶
socket.HVSOCKET_CONNECT_TIMEOUT_MAX¶
socket.HVSOCKET_CONNECTED_SUSPEND¶
socket.HVSOCKET_ADDRESS_FLAG_PASSTHRU¶
socket.HV_GUID_ZERO¶
socket.HV_GUID_WILDCARD¶
socket.HV_GUID_BROADCAST¶
socket.HV_GUID_CHILDREN¶
socket.HV_GUID_LOOPBACK¶
socket.HV_GUID_PARENT¶: Constants for Windows Hyper-V sockets for host/guest communications.

Availability: Windows.

Added in version 3.12.

socket.ETHERTYPE_ARP¶
socket.ETHERTYPE_IP¶
socket.ETHERTYPE_IPV6¶
socket.ETHERTYPE_VLAN¶: IEEE 802.3 protocol number. constants.

Availability: Linux, FreeBSD, macOS.

Added in version 3.12.

socket.SHUT_RD¶
socket.SHUT_WR¶
socket.SHUT_RDWR¶: These constants are used by the shutdown() method of socket objects.

Availability: not WASI.

Функції¶

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

Усі наступні функції створюють об’єкти 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.

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

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=GLOBAL_DEFAULT, source_address=None, *, all_errors=False)¶

Підключіться до служби TCP, яка прослуховує адресу в Інтернеті (2-кортеж (хост, порт)) і поверніть об’єкт сокета. Це функція вищого рівня, ніж socket.connect(): якщо host є нечисловим ім’ям хоста, вона намагатиметься вирішити його як для AF_INET, так і для AF_INET6, а потім спробуйте підключитися до всіх можливих адрес по черзі, доки підключення не вдасться. Це полегшує написання клієнтів, сумісних як з IPv4, так і з IPv6.

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

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

When a connection cannot be created, an exception is raised. By default, it is the exception from the last address in the list. If all_errors is True, it is an ExceptionGroup containing the errors of all attempts.

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

Змінено в версії 3.11: all_errors was added.

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 returns the socket object.

family should be either AF_INET or AF_INET6. backlog is the queue size passed to socket.listen(); if not specified , 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.

Added in version 3.8.

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

Added in version 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(). Передбачається, що розетка знаходиться в режимі блокування.

Availability: Windows.

Added in version 3.3.

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

Інші функції¶

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

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

Added in version 3.7.

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

This function wraps the C function getaddrinfo of the underlying system.

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

The family, type and proto arguments can be optionally specified in order to provide options and limit the list of addresses returned. Pass their default values (AF_UNSPEC, 0, and 0, respectively) to not limit the results. See the note below for details.

The flags argument can be one or several of the AI_* constants, and will influence how results are computed and returned. For example, AI_NUMERICHOST will disable domain name resolution and will raise an error if host is a domain name.

Функція повертає список із 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.

Примітка

If you intend to use results from getaddrinfo() to create a socket (rather than, for example, retrieve canonname), consider limiting the results by type (e.g. SOCK_STREAM or SOCK_DGRAM) and/or proto (e.g. IPPROTO_TCP or IPPROTO_UDP) that your application can handle.

The behavior with default values of family, type, proto and flags is system-specific.

Many systems (for example, most Linux configurations) will return a sorted list of all matching addresses. These addresses should generally be tried in order until a connection succeeds (possibly tried in parallel, for example, using a Happy Eyeballs algorithm). In these cases, limiting the type and/or proto can help eliminate unsuccessful or unusable connection attempts.

Some systems will, however, only return a single address. (For example, this was reported on Solaris and AIX configurations.) On these systems, limiting the type and/or proto helps ensure that this address is usable.

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

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

>>> socket.getaddrinfo("example.org", 80, proto=socket.IPPROTO_TCP)
[(socket.AF_INET6, socket.SOCK_STREAM,
 6, '', ('2606:2800:220:1:248:1893:25c8:1946', 80, 0, 0)),
 (socket.AF_INET, socket.SOCK_STREAM,
 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.

Availability: not WASI.

socket.gethostbyname_ex(hostname)¶

Translate a host name to IPv4 address format, extended interface. Return a 3-tuple (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.

Availability: not WASI.

socket.gethostname()¶

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

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

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

Availability: not WASI.

socket.gethostbyaddr(ip_address)¶

Return a 3-tuple (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.

Availability: not WASI.

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.

Availability: not WASI.

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.

Availability: not WASI.

socket.getservbyname(servicename[, protocolname])¶

Перекладіть назву інтернет-сервісу та назву протоколу на номер порту для цієї служби. Додаткова назва протоколу, якщо її вказано, має бути 'tcp' або 'udp', інакше будь-який протокол збігатиметься.

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

Availability: not WASI.

socket.getservbyport(port[, protocolname])¶

Перекладіть номер інтернет-порту та назву протоколу на назву служби для цієї служби. Додаткова назва протоколу, якщо її вказано, має бути 'tcp' або 'udp', інакше будь-який протокол збігатиметься.

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

Availability: not WASI.

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

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

Змінено в версії 3.10: Викликає OverflowError, якщо x не вміщується в 16-бітне ціле число без знаку.

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

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

Змінено в версії 3.10: Викликає OverflowError, якщо x не вміщується в 16-бітне ціле число без знаку.

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 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 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 in_addr (similar to inet_aton()) or in6_addr.

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

Availability: Unix, 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 in_addr (similar to inet_ntoa()) or in6_addr.

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

Availability: Unix, Windows.

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

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

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

Availability: Unix, not Emscripten, not WASI.

Most Unix platforms.

Added in version 3.3.

socket.CMSG_SPACE(length)¶

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

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

Availability: Unix, not Emscripten, not WASI.

most Unix platforms.

Added in version 3.3.

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

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

socket.sethostname(name)¶

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

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

Availability: Unix.

Added in version 3.3.

socket.if_nameindex()¶

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

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 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, якщо не існує інтерфейсу з вказаною назвою.

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 3.3.

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

Дивись також

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

socket.if_indextoname(if_index)¶: Повертає назву мережевого інтерфейсу, що відповідає номеру індексу інтерфейсу. OSError, якщо не існує інтерфейсу з даним індексом.

Availability: Unix, Windows, not Emscripten, not WASI.

Added in version 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, Windows, not Emscripten, not WASI.

Unix platforms supporting sendmsg() and SCM_RIGHTS mechanism.

Added in version 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, Windows, not Emscripten, not WASI.

Unix platforms supporting sendmsg() and SCM_RIGHTS mechanism.

Added in version 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.

Availability: not WASI.

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

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

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

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

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

Availability: not WASI.

socket.connect_ex(address)¶

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

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

Availability: not WASI.

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

Added in version 3.2.

socket.dup()¶

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

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

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

Availability: not WASI.

socket.fileno()¶

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

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

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

Added in version 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).

Availability: not WASI.

socket.getblocking()¶

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

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

Added in version 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); він визначає кількість неприйнятих підключень, які система дозволить перед тим, як відхилити нові підключення. Якщо не вказано, вибирається розумне значення за умовчанням.

Availability: not WASI.

Змінено в версії 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', 'b', or a combination of those.

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

Закриття файлового об’єкта, який повертає 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. A returned empty bytes object indicates that the client has disconnected. 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: Unix.

Most Unix platforms.

Added in version 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: Unix.

Most Unix platforms.

Added in version 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 longer 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: Unix, not WASI.

Most Unix platforms.

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

Added in version 3.3.

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

socket.sendmsg_afalg([msg, ]*, op[, iv[, assoclen[, flags]]])¶: Спеціалізована версія sendmsg() для AF_ALG сокета. Установіть довжину пов’язаних даних режиму, IV, AEAD і прапорці для сокета AF_ALG.

Availability: Linux >= 2.6.38.

Added in version 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. Неблокуючі сокети не підтримуються.

Added in version 3.5.

socket.set_inheritable(inheritable)¶: Установіть inheritable flag дескриптора файлу сокета або дескриптора сокета.

Added in version 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 this module (SO_* etc. <socket-unix-constants>). 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).

Availability: not WASI.

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

Availability: not WASI.

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

Availability: Windows.

Added in version 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 module 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 all the 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 packets
s.ioctl(socket.SIO_RCVALL, socket.RCVALL_ON)

# receive a packet
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 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.

`socket` — Low-level networking interface¶

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

Зміст модуля¶

Винятки¶

Константи¶

Функції¶

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

Інші функції¶

Об’єкти Socket¶

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

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

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

приклад¶

Table of Contents

Попередній розділ

Наступна тема

Ця сторінка

socket — Low-level networking interface¶

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

Зміст модуля¶

Винятки¶

Константи¶

Функції¶

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

Інші функції¶

Об’єкти Socket¶

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

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

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

приклад¶

`socket` — Low-level networking interface¶

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

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