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 не определяет краткую запись для адресов с октетами, равными нулю, эти два атрибута всегда совпадают с str(addr) для IPv4-адресов. Предоставление этих атрибутов упрощает написание кода отображения, который может обрабатывать как IPv4, так и IPv6-адреса.

packed

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

reverse_pointer

Имя записи PTR обратного DNS для 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 если адрес определён как не доступный глобально по iana-ipv4-special-registry (для IPv4) или iana-ipv6-special-registry (для 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 если адрес определен как доступный глобально по iana-ipv4-special-registry (для IPv4) или iana-ipv6-special-registry (для 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-адрес. AddressValueError генерируется, если address не является корректным IPv6-адресом.

Следующее представляет собой корректный 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 байт, в формате big-endian.

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

compressed

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

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

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 если адрес зарезервирован для использования в локальной сети. Обратите внимание, что адресное пространство для локальной сети устарело согласно 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, это свойство сообщит пару вложенных (server, client) IP-адресов. Для любого другого адреса это свойство будет None.

IPv6Address.__format__(fmt)

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

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

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

Для взаимодействия с сетевыми интерфейсами, такими как модуль сокетов, адреса должны быть преобразованы в строки или целые числа. Это выполняется с помощью встроенных функций 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 байта, в формате big-endian. Интерпретация аналогична целому числу 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

Эти атрибуты истинны для всей сети в целом, если они истинны как для адреса сети, так и для адреса широковещания.

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 из этой. Возвращает итератор объектов сети. Генерирует исключение ValueError, если network не полностью содержится в этой сети.

>>> 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-адрес — это адрес сети, а длина префикса должна быть единственным числом, prefix. Если длина префикса не указана, она считается /128.

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

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

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

Если 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).