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 соответствующей длины (самый старший октет первым). Это 4 байта для IPv4 и 16 байтов для IPv6.

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.13: Исправлены некоторые ложные срабатывания и ложные негативы.

• 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.13: Исправлены некоторые ложные срабатывания и ложные негативы, см. 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.

ipv6_mapped

IPv4Address объект, представляющий IPv4-отображаемый IPv6-адрес. См. RFC 4291.

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

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

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

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

Вычисляет определения сетей, полученные путем удаления заданной сети из этой. Возвращает итератор объектов сети. Вызывает 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; а маска подсети — целое число, представляющее длину префикса.

Если 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 Subnet-Router также включается в результат. Сети с маской 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).