ipaddress — библиотека для работы с IPv4/IPv6

Объекты адресов

Объекты IPv4Address и IPv6Address имеют множество общих атрибутов. Некоторые атрибуты, имеющие смысл только для адресов IPv6, также реализованы в объектах IPv4Address, чтобы упростить написание кода, корректно обрабатывающего обе версии IP. Объекты адресов являются хешируемыми, поэтому их можно использовать в качестве ключей словарей.

class ipaddress.IPv4Address(address)

Создаёт адрес IPv4. Если address не является допустимым адресом IPv4, возникает исключение AddressValueError.

Допустимым адресом IPv4 считается:

1. Строка в десятичной точечно-разделённой записи, состоящая из четырёх десятичных целых чисел в диапазоне от 0 до 255 включительно, разделённых точками (например, 192.168.0.1). Каждое целое число представляет октет (байт) адреса. Ведущие нули не допускаются, чтобы избежать путаницы с восьмеричной записью.
2. Целое число, помещающееся в 32 бита.
3. Целое число, упакованное в объект bytes длиной 4 байта (сначала старший октет).

>>> ipaddress.IPv4Address('192.168.0.1')
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(3232235521)
IPv4Address('192.168.0.1')
>>> ipaddress.IPv4Address(b'\xC0\xA8\x00\x01')
IPv4Address('192.168.0.1')

Изменено в версии 3.8: Ведущие нули допускаются, даже в неоднозначных случаях, похожих на восьмеричную запись.

Изменено в версии 3.9.5: Ведущие нули больше не допускаются и считаются ошибкой. Строки адресов IPv4 теперь разбираются так же строго, как в glibc inet_pton().

version

Номер соответствующей версии: 4 для IPv4, 6 для IPv6.

max_prefixlen

Общее количество битов в представлении адреса для этой версии: 32 для IPv4, 128 для IPv6.

Префикс задаёт количество старших битов адреса, которые сравниваются для определения того, принадлежит ли адрес сети.

compressed

exploded

Строковое представление в точечно-разделённой десятичной записи. Ведущие нули в представление не включаются.

Так как в IPv4 не определена сокращённая запись для адресов с нулевыми октетами, для адресов IPv4 значения этих двух атрибутов всегда совпадают со значением str(addr). Наличие этих атрибутов упрощает написание кода отображения, который может обрабатывать как адреса IPv4, так и IPv6.

packed

Двоичное представление этого адреса — объект bytes соответствующей длины (сначала старший октет). Для IPv4 это 4 байта, а для IPv6 — 16 байт.

reverse_pointer

Имя обратной DNS-записи PTR для IP-адреса, например:

>>> ipaddress.ip_address("127.0.0.1").reverse_pointer
'1.0.0.127.in-addr.arpa'
>>> ipaddress.ip_address("2001:db8::1").reverse_pointer
'1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.b.d.0.1.0.0.2.ip6.arpa'

Это имя, которое можно использовать для выполнения PTR-запроса, а не само разрешённое имя узла.

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

is_multicast

True, если адрес зарезервирован для многоадресной рассылки. См. RFC 3171 (для IPv4) или RFC 2373 (для IPv6).

is_private

True, если адрес определён как недоступный глобально согласно специальному реестру IPv4 IANA (для IPv4) или специальному реестру IPv6 IANA (для IPv6), за следующими исключениями:

• is_private имеет значение False для общего адресного пространства (100.64.0.0/10)

• Для адресов IPv4, отображённых в IPv6, значение is_private определяется семантикой соответствующих адресов IPv4, и выполняется следующее условие (см. IPv6Address.ipv4_mapped):

  address.is_private == address.ipv4_mapped.is_private
  

Значение is_private противоположно значению is_global, за исключением общего адресного пространства (диапазон 100.64.0.0/10), в котором оба значения равны False.

Изменено в версии 3.12.4: Исправлены некоторые ложноположительные и ложноотрицательные результаты.

• 192.0.0.0/24 считается частным, за исключением 192.0.0.9/32 и 192.0.0.10/32 (ранее частным считался только поддиапазон 192.0.0.0/29).
• 64:ff9b:1::/48 считается частным.
• 2002::/16 считается частным.
• Внутри 2001::/23 есть исключения (в остальном этот диапазон считается частным): 2001:1::1/128, 2001:1::2/128, 2001:3::/32, 2001:4:112::/48, 2001:20::/28, 2001:30::/28. Эти исключения не считаются частными.

is_global

True, если адрес определён как глобально доступный согласно специальному реестру IPv4 IANA (для IPv4) или специальному реестру IPv6 IANA (для IPv6), за следующим исключением:

Для адресов IPv4, отображённых в IPv6, значение is_private определяется семантикой соответствующих адресов IPv4, и выполняется следующее условие (см. IPv6Address.ipv4_mapped):

address.is_global == address.ipv4_mapped.is_global

Значение is_global противоположно значению is_private, за исключением общего адресного пространства (диапазон 100.64.0.0/10), в котором оба значения равны False.

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

Изменено в версии 3.12.4: Исправлены некоторые ложноположительные и ложноотрицательные результаты; подробности см. в описании is_private.

is_unspecified

True, если адрес не указан. См. RFC 5735 (для IPv4) или RFC 2373 (для IPv6).

is_reserved

True, если адрес зарезервирован IETF по другим причинам.

is_loopback

True, если это адрес обратной петли. См. RFC 3330 (для IPv4) или RFC 2373 (для IPv6).

is_link_local

True, если адрес зарезервирован для локального использования в канале. См. RFC 3927.

IPv4Address.__format__(fmt)

Возвращает строковое представление IP-адреса, формат которого задаётся явной строкой формата. Параметр fmt может принимать одно из следующих значений: 's' — значение по умолчанию, эквивалентное str(); 'b' — двоичная строка с заполнением нулями; 'X' или 'x' — представление в шестнадцатеричном формате с буквами верхнего или нижнего регистра; либо 'n', эквивалентное 'b' для адресов IPv4 и 'x' для IPv6. Для двоичного и шестнадцатеричного представлений доступны спецификатор формата '#' и параметр группировки '_'. __format__ используется в format, str.format и f-строках.

>>> format(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> '{:#b}'.format(ipaddress.IPv4Address('192.168.0.1'))
'0b11000000101010000000000000000001'
>>> f'{ipaddress.IPv6Address("2001:db8::1000"):s}'
'2001:db8::1000'
>>> format(ipaddress.IPv6Address('2001:db8::1000'), '_X')
'2001_0DB8_0000_0000_0000_0000_0000_1000'
>>> '{:#_n}'.format(ipaddress.IPv6Address('2001:db8::1000'))
'0x2001_0db8_0000_0000_0000_0000_0000_1000'

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

class ipaddress.IPv6Address(address)

Создаёт адрес IPv6. Если address не является допустимым адресом IPv6, возникает исключение AddressValueError.

Допустимым адресом IPv6 считается:

1. Строка, состоящая из восьми групп по четыре шестнадцатеричных цифры, каждая группа представляет 16 битов. Группы разделяются двоеточиями. Такая запись называется полной (развёрнутой). Строку также можно сжать (использовать сокращённую запись) несколькими способами. Подробности см. в RFC 4291. Например, "0000:0000:0000:0000:0000:0abc:0007:0def" можно сжать до "::abc:7:def".

   Строка также может содержать необязательный идентификатор зоны области действия, указанный суффиксом %scope_id. Если он присутствует, идентификатор зоны не должен быть пустым и не должен содержать %. Подробности см. в RFC 4007. Например, fe80::1234%1 может обозначать адрес fe80::1234 на первом канале узла.

2. Целое число, помещающееся в 128 бит.
3. Целое число, упакованное в объект bytes длиной 16 байт, в порядке от старшего байта к младшему.

>>> ipaddress.IPv6Address('2001:db8::1000')
IPv6Address('2001:db8::1000')
>>> ipaddress.IPv6Address('ff02::5678%1')
IPv6Address('ff02::5678%1')

compressed

Краткая форма представления адреса: начальные нули в группах опускаются, а самая длинная последовательность групп, состоящих только из нулей, заменяется одной пустой группой.

Для адресов IPv6 это также значение, возвращаемое методом str(addr).

exploded

Полная форма представления адреса, включающая все начальные нули и группы, состоящие только из нулей.

Описание следующих атрибутов и методов см. в соответствующей документации класса IPv4Address:

packed

reverse_pointer

version

max_prefixlen

is_multicast

is_private

is_global

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

is_unspecified

is_reserved

is_loopback

is_link_local

is_site_local

True, если адрес зарезервирован для локального использования в пределах сайта. Обратите внимание, что адресное пространство site-local объявлено устаревшим в RFC 3879. Используйте is_private, чтобы проверить, входит ли адрес в пространство уникальных локальных адресов, определённое в RFC 4193.

ipv4_mapped

Для адресов, которые выглядят как отображённые адреса IPv4 (начинаются с ::FFFF/96), это свойство возвращает встроенный адрес IPv4. Для любого другого адреса это свойство возвращает None.

scope_id

Для адресов с областью действия, определённых в RFC 4007, это свойство в виде строки задаёт конкретную зону области действия, к которой принадлежит адрес. Если зона области действия не указана, свойство возвращает None.

sixtofour

Для адресов, которые выглядят как адреса 6to4 (начинаются с 2002::/16), определённые в RFC 3056, это свойство возвращает встроенный адрес IPv4. Для любого другого адреса это свойство возвращает None.

teredo

Для адресов, которые выглядят как адреса Teredo (начинаются с 2001::/32), определённые в RFC 4380, это свойство возвращает встроенную пару IP-адресов (server, client). Для любого другого адреса это свойство возвращает None.

IPv6Address.__format__(fmt)

См. соответствующее описание метода класса IPv4Address.

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

Преобразование в строки и целые числа

Для взаимодействия с сетевыми интерфейсами, такими как модуль socket, адреса необходимо преобразовывать в строки или целые числа. Для этого используются встроенные функции str() и int():

>>> str(ipaddress.IPv4Address('192.168.0.1'))
'192.168.0.1'
>>> int(ipaddress.IPv4Address('192.168.0.1'))
3232235521
>>> str(ipaddress.IPv6Address('::1'))
'::1'
>>> int(ipaddress.IPv6Address('::1'))
1

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

Операторы

Объекты адресов поддерживают некоторые операторы. Если не указано иное, операторы можно применять только к совместимым объектам (то есть IPv4 с IPv4, IPv6 с IPv6).

>>> IPv4Address('127.0.0.2') > IPv4Address('127.0.0.1')
True
>>> IPv4Address('127.0.0.2') == IPv4Address('127.0.0.1')
False
>>> IPv4Address('127.0.0.2') != IPv4Address('127.0.0.1')
True
>>> IPv6Address('fe80::1234') == IPv6Address('fe80::1234%1')
False
>>> IPv6Address('fe80::1234%1') != IPv6Address('fe80::1234%2')
True

>>> IPv4Address('127.0.0.2') + 3
IPv4Address('127.0.0.5')
>>> IPv4Address('127.0.0.2') - 3
IPv4Address('126.255.255.255')
>>> IPv4Address('255.255.255.255') + 1
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ipaddress.AddressValueError: 4294967296 (>= 2**32) is not permitted as an IPv4 address

Префикс, маска сети и маска узла

Существует несколько эквивалентных способов задать маски IP-сетей. Префикс /<nbits> — это обозначение количества старших битов, установленных в маске сети. Маска сети — это IP-адрес с некоторым количеством установленных старших битов. Таким образом, префикс /24 эквивалентен маске сети 255.255.255.0 в IPv4 или ffff:ff00:: в IPv6. Кроме того, маска узла является логическим отрицанием маски сети и иногда используется (например, в списках контроля доступа Cisco) для обозначения маски сети. Эквивалент маски узла для /24 в IPv4 — 0.0.0.255.

Объекты сетей

Все атрибуты, реализованные объектами адресов, реализованы и объектами сетей. Кроме того, объекты сетей реализуют дополнительные атрибуты. Все эти атрибуты общие для IPv4Network и IPv6Network, поэтому во избежание дублирования они описаны только для IPv4Network. Объекты сетей являются хешируемыми, поэтому их можно использовать в качестве ключей словарей.

class ipaddress.IPv4Network(address, strict=True)

Создаёт определение сети IPv4. address может иметь одно из следующих значений:

1. Строка, состоящая из IP-адреса и необязательной маски, разделённых косой чертой (/). IP-адрес является сетевым адресом, а маска может быть одним числом, обозначающим префикс, или строковым представлением IPv4-адреса. В последнем случае маска интерпретируется как маска сети, если начинается с ненулевого поля, или как маска узла, если начинается с нулевого поля; единственное исключение — маска, состоящая только из нулей, которая считается маской сети. Если маска не указана, предполагается /32.

   Например, следующие варианты задания address эквивалентны: 192.168.1.0/24, 192.168.1.0/255.255.255.0 и 192.168.1.0/0.0.0.255.

2. Целое число, помещающееся в 32 бита. Оно эквивалентно сети с одним адресом, где сетевой адрес — это address, а маска — /32.
3. Целое число в упакованном виде, представленное объектом bytes длиной 4 байта в порядке от старшего байта к младшему. Интерпретация аналогична целочисленному значению address.
4. Двухэлементный кортеж из описания адреса и маски сети, где описание адреса — это строка, 32-битное целое число, целое число, упакованное в 4 байта, или существующий объект IPv4Address; а маска сети — это целое число, представляющее длину префикса (например, 24), или строка, представляющая маску префикса (например, 255.255.255.0).

Если address не является допустимым IPv4-адресом, возникает исключение AddressValueError. Если маска недопустима для IPv4-адреса, возникает исключение NetmaskValueError.

Если strict имеет значение True и в указанном адресе установлены биты узла, возникает исключение ValueError. В противном случае биты узла маскируются, чтобы определить соответствующий сетевой адрес.

Если не указано иное, все методы работы с сетями, принимающие другие объекты сети или адреса, вызывают исключение TypeError, если версия IP аргумента несовместима с self.

Изменено в версии 3.5: Добавлена форма двухэлементного кортежа для параметра конструктора address.

version

max_prefixlen

См. описание соответствующего атрибута в IPv4Address.

is_multicast

is_private

is_unspecified

is_reserved

is_loopback

is_link_local

Эти атрибуты имеют значение True для сети в целом, если они имеют значение True как для сетевого адреса, так и для широковещательного адреса.

network_address

Сетевой адрес сети. Сетевой адрес и длина префикса однозначно определяют сеть.

broadcast_address

Широковещательный адрес сети. Пакеты, отправленные на широковещательный адрес, должны приниматься каждым узлом сети.

hostmask

Маска узла в виде объекта IPv4Address.

netmask

Маска сети в виде объекта IPv4Address.

with_prefixlen

compressed

exploded

Строковое представление сети с маской в нотации префикса.

with_prefixlen и compressed всегда совпадают с str(network). В exploded используется полная форма сетевого адреса.

with_netmask

Строковое представление сети с маской в нотации маски сети.

with_hostmask

Строковое представление сети с маской в нотации маски узла.

num_addresses

Общее количество адресов в сети.

prefixlen

Длина сетевого префикса в битах.

hosts()

Возвращает итератор по доступным узлам сети. Доступными узлами являются все IP-адреса, принадлежащие сети, кроме самого сетевого адреса и широковещательного адреса сети. Для сетей с длиной маски 31 сетевой и широковещательный адреса также включаются в результат. Для сетей с маской 32 возвращается список, содержащий единственный адрес узла.

>>> list(ip_network('192.0.2.0/29').hosts())
[IPv4Address('192.0.2.1'), IPv4Address('192.0.2.2'),
 IPv4Address('192.0.2.3'), IPv4Address('192.0.2.4'),
 IPv4Address('192.0.2.5'), IPv4Address('192.0.2.6')]
>>> list(ip_network('192.0.2.0/31').hosts())
[IPv4Address('192.0.2.0'), IPv4Address('192.0.2.1')]
>>> list(ip_network('192.0.2.1/32').hosts())
[IPv4Address('192.0.2.1')]

overlaps(other)

True, если эта сеть частично или полностью входит в other либо other полностью входит в эту сеть.

address_exclude(network)

Вычисляет определения сетей, получающиеся при удалении заданной network из этой сети. Возвращает итератор объектов сетей. Если network не входит целиком в эту сеть, возникает исключение ValueError.

>>> n1 = ip_network('192.0.2.0/28')
>>> n2 = ip_network('192.0.2.1/32')
>>> list(n1.address_exclude(n2))
[IPv4Network('192.0.2.8/29'), IPv4Network('192.0.2.4/30'),
 IPv4Network('192.0.2.2/31'), IPv4Network('192.0.2.0/32')]

subnets(prefixlen_diff=1, new_prefix=None)

Подсети, из которых состоит текущее определение сети, в зависимости от значений аргументов. prefixlen_diff задаёт величину увеличения длины нашего префикса. new_prefix — это требуемый новый префикс подсетей; он должен быть длиннее нашего префикса. Должен быть задан только один из аргументов: prefixlen_diff или new_prefix. Возвращает итератор объектов сетей.

>>> list(ip_network('192.0.2.0/24').subnets())
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]
>>> list(ip_network('192.0.2.0/24').subnets(prefixlen_diff=2))
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=26))
[IPv4Network('192.0.2.0/26'), IPv4Network('192.0.2.64/26'),
 IPv4Network('192.0.2.128/26'), IPv4Network('192.0.2.192/26')]
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=23))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    raise ValueError('new prefix must be longer')
ValueError: new prefix must be longer
>>> list(ip_network('192.0.2.0/24').subnets(new_prefix=25))
[IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/25')]

supernet(prefixlen_diff=1, new_prefix=None)

Суперсеть, содержащая это определение сети, в зависимости от значений аргументов. prefixlen_diff задаёт величину уменьшения длины нашего префикса. new_prefix — это требуемый новый префикс суперсети; он должен быть короче нашего префикса. Должен быть задан только один из аргументов: prefixlen_diff или new_prefix. Возвращает один объект сети.

>>> ip_network('192.0.2.0/24').supernet()
IPv4Network('192.0.2.0/23')
>>> ip_network('192.0.2.0/24').supernet(prefixlen_diff=2)
IPv4Network('192.0.0.0/22')
>>> ip_network('192.0.2.0/24').supernet(new_prefix=20)
IPv4Network('192.0.0.0/20')

subnet_of(other)

Возвращает True, если эта сеть является подсетью other.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> b.subnet_of(a)
True

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

supernet_of(other)

Возвращает True, если эта сеть является суперсетью other.

>>> a = ip_network('192.168.1.0/24')
>>> b = ip_network('192.168.1.128/30')
>>> a.supernet_of(b)
True

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

compare_networks(other)

Сравнивает эту сеть с other. При сравнении учитываются только сетевые адреса, биты узла не учитываются. Возвращает -1, 0 или 1.

>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.2/32'))
-1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.0/32'))
1
>>> ip_network('192.0.2.1/32').compare_networks(ip_network('192.0.2.1/32'))
0

Устарело с версии 3.7: Используется тот же алгоритм упорядочивания и сравнения, что и для «<», «==» и «>»

class ipaddress.IPv6Network(address, strict=True)

Создаёт определение сети IPv6. address может иметь одно из следующих значений:

1. Строка, состоящая из IP-адреса и необязательной длины префикса, разделённых косой чертой (/). IP-адрес является сетевым адресом, а длина префикса должна быть одним числом — префиксом. Если длина префикса не указана, предполагается /128.

   Обратите внимание, что в настоящее время развёрнутые маски сети не поддерживаются. Это означает, что 2001:db00::0/24 является допустимым аргументом, а 2001:db00::0/ffff:ff00:: — нет.

2. Целое число, помещающееся в 128 бит. Оно эквивалентно сети с одним адресом, где сетевой адрес — это address, а маска — /128.
3. Целое число в упакованном виде, представленное объектом bytes длиной 16 байт в порядке от старшего байта к младшему. Интерпретация аналогична целочисленному значению address.
4. Двухэлементный кортеж из описания адреса и маски сети, где описание адреса — это строка, 128-битное целое число, целое число, упакованное в 16 байт, или существующий объект IPv6Address; а маска сети — целое число, представляющее длину префикса.

Если address не является допустимым IPv6-адресом, возникает исключение AddressValueError. Если маска недопустима для IPv6-адреса, возникает исключение NetmaskValueError.

Если strict имеет значение True и в указанном адресе установлены биты узла, возникает исключение ValueError. В противном случае биты узла маскируются, чтобы определить соответствующий сетевой адрес.

Изменено в версии 3.5: Добавлена форма двухэлементного кортежа для параметра конструктора address.

version

max_prefixlen

is_multicast

is_private

is_unspecified

is_reserved

is_loopback

is_link_local

network_address

broadcast_address

hostmask

netmask

with_prefixlen

compressed

exploded

with_netmask

with_hostmask

num_addresses

prefixlen

hosts()

Возвращает итератор по доступным узлам сети. Доступными узлами являются все IP-адреса, принадлежащие сети, кроме anycast-адреса маршрутизатора подсети. Для сетей с длиной маски 127 anycast-адрес маршрутизатора подсети также включается в результат. Для сетей с маской 128 возвращается список, содержащий единственный адрес узла.

overlaps(other)

address_exclude(network)

subnets(prefixlen_diff=1, new_prefix=None)

supernet(prefixlen_diff=1, new_prefix=None)

subnet_of(other)

supernet_of(other)

compare_networks(other)

См. описание соответствующего атрибута в IPv4Network.

is_site_local

Этот атрибут имеет значение True для сети в целом, если он имеет значение True как для сетевого адреса, так и для широковещательного адреса.

Операторы

Объекты сетей поддерживают некоторые операторы. Если не указано иное, операторы можно применять только к совместимым объектам (то есть IPv4 с IPv4, IPv6 с IPv6).

>>> for addr in IPv4Network('192.0.2.0/28'):
...     addr
...
IPv4Address('192.0.2.0')
IPv4Address('192.0.2.1')
IPv4Address('192.0.2.2')
IPv4Address('192.0.2.3')
IPv4Address('192.0.2.4')
IPv4Address('192.0.2.5')
IPv4Address('192.0.2.6')
IPv4Address('192.0.2.7')
IPv4Address('192.0.2.8')
IPv4Address('192.0.2.9')
IPv4Address('192.0.2.10')
IPv4Address('192.0.2.11')
IPv4Address('192.0.2.12')
IPv4Address('192.0.2.13')
IPv4Address('192.0.2.14')
IPv4Address('192.0.2.15')

>>> IPv4Network('192.0.2.0/28')[0]
IPv4Address('192.0.2.0')
>>> IPv4Network('192.0.2.0/28')[15]
IPv4Address('192.0.2.15')
>>> IPv4Address('192.0.2.6') in IPv4Network('192.0.2.0/28')
True
>>> IPv4Address('192.0.3.6') in IPv4Network('192.0.2.0/28')
False

Операторы

Объекты интерфейсов поддерживают некоторые операторы. Если не указано иное, операторы можно применять только к совместимым объектам (то есть IPv4 с IPv4, IPv6 с IPv6).