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.11.10: Исправлены некоторые ложноположительные и ложноотрицательные результаты.

• 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.11.10: Исправлены некоторые ложноположительные и ложноотрицательные результаты; подробности см. в 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

is_unspecified

is_reserved

is_loopback

is_link_local

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

is_site_local

True, если адрес зарезервирован для локального использования на сайте. Обратите внимание: адресное пространство локальных адресов сайта объявлено устаревшим в 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-адреса Subnet-Router. Для сетей с маской длиной 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).