> **Источник:** https://python-all.ru/3.4/howto/ipaddress.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# Введение в модуль ipaddress

| автор: | Peter Moody |
| --- | --- |
| автор: | Nick Coghlan |

Обзор

Цель этого документа – дать простое введение в модуль [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress). Он предназначен в первую очередь для пользователей, которые ещё не знакомы с терминологией IP-сетей, но также может быть полезен сетевым инженерам, желающим получить обзор того, как [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) представляет концепции IP-адресации.

## Создание объектов адресов/сетей/интерфейсов

Поскольку [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) – это модуль для проверки и управления IP-адресами, первое, что захочется сделать, – создать несколько объектов. С помощью [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) можно создавать объекты из строк и целых чисел.

### Замечание о версиях IP

Для читателей, не особо знакомых с IP-адресацией, важно знать, что в настоящее время происходит переход Интернет-протокола с версии 4 на версию 6. Этот переход происходит главным образом потому, что версия 4 протокола не предоставляет достаточного количества адресов для удовлетворения потребностей всего мира, особенно с учетом растущего числа устройств, имеющих прямое подключение к интернету.

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

### IP-адреса хостов

Адреса, часто называемые «адресами хостов», – это самая базовая единица при работе с IP-адресацией. Самый простой способ создать адрес – использовать фабричную функцию [`ipaddress.ip_address()`](https://python-all.ru/3.4/library/ipaddress.html#ipaddress.ip_address), которая автоматически определяет, создавать ли адрес IPv4 или IPv6, на основе переданного значения:

```python
>>> ipaddress.ip_address('192.0.2.1')
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address('2001:DB8::1')
IPv6Address('2001:db8::1')
```

Адреса также можно создавать непосредственно из целых чисел. Значения, помещающиеся в 32 бита, считаются IPv4-адресами:

```python
>>> ipaddress.ip_address(3221225985)
IPv4Address('192.0.2.1')
>>> ipaddress.ip_address(42540766411282592856903984951653826561)
IPv6Address('2001:db8::1')
```

Чтобы принудительно использовать IPv4 или IPv6 адреса, соответствующие классы можно вызвать напрямую. Это особенно полезно для принудительного создания IPv6 адресов из небольших целых чисел:

```python
>>> ipaddress.ip_address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv4Address(1)
IPv4Address('0.0.0.1')
>>> ipaddress.IPv6Address(1)
IPv6Address('::1')
```

### Определение сетей

Адреса хостов обычно группируются в IP-сети, поэтому [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) предоставляет способ создавать, просматривать и управлять определениями сетей. Объекты IP-сетей создаются из строк, которые определяют диапазон адресов хостов, входящих в эту сеть. Простейшая форма такой информации – пара «адрес сети/префикс сети», где префикс определяет количество старших битов, которые сравниваются для определения, является ли адрес частью сети, а адрес сети определяет ожидаемое значение этих битов.

Как и для адресов, предусмотрена фабричная функция, которая автоматически определяет правильную версию IP:

```python
>>> ipaddress.ip_network('192.0.2.0/24')
IPv4Network('192.0.2.0/24')
>>> ipaddress.ip_network('2001:db8::0/96')
IPv6Network('2001:db8::/96')
```

Объекты сетей не могут иметь установленных битов хоста. Практический эффект этого заключается в том, что `192.0.2.1/24` не описывает сеть. Такие определения называются объектами интерфейсов, поскольку нотация «ip-на-сети» обычно используется для описания сетевых интерфейсов компьютера в заданной сети; они описываются далее в следующем разделе.

По умолчанию попытка создать сетевой объект с установленными битами хоста приведёт к возбуждению [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError). Чтобы вместо этого запросить приведение дополнительных битов к нулю, в конструктор можно передать флаг `strict=False`:

```python
>>> ipaddress.ip_network('192.0.2.1/24')
Traceback (most recent call last):
   ...
ValueError: 192.0.2.1/24 has host bits set
>>> ipaddress.ip_network('192.0.2.1/24', strict=False)
IPv4Network('192.0.2.0/24')
```

Хотя строковая форма предоставляет значительно большую гибкость, сети также можно определять с помощью целых чисел, как и адреса хостов. В этом случае сеть считается содержащей только единственный адрес, заданный целым числом, поэтому префикс сети включает весь сетевой адрес:

```python
>>> ipaddress.ip_network(3221225984)
IPv4Network('192.0.2.0/32')
>>> ipaddress.ip_network(42540766411282592856903984951653826560)
IPv6Network('2001:db8::/128')
```

Как и в случае с адресами, создание сети определённого типа можно принудительно выполнить, вызвав конструктор класса напрямую, а не используя фабричную функцию.

### Интерфейсы хостов

Как уже упоминалось выше, если нужно описать адрес в конкретной сети, ни класс адреса, ни класс сети по отдельности не подходят. Обозначение вида `192.0.2.1/24` обычно используется сетевыми инженерами и разработчиками инструментов для межсетевых экранов и маршрутизаторов как сокращение для «адрес хоста `192.0.2.1` в сети `192.0.2.0/24`». Соответственно, [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) предоставляет набор гибридных классов, которые связывают адрес с конкретной сетью. Интерфейс создания этих объектов идентичен интерфейсу определения сетевых объектов, за исключением того, что часть адреса не обязана быть сетевым адресом.

```python
>>> ipaddress.ip_interface('192.0.2.1/24')
IPv4Interface('192.0.2.1/24')
>>> ipaddress.ip_interface('2001:db8::1/96')
IPv6Interface('2001:db8::1/96')
```

Целочисленные входные данные принимаются (как и для сетей), а использование определённой версии IP можно принудительно задать, напрямую вызвав соответствующий конструктор.

## Просмотр объектов Address/Network/Interface

Вы потрудились создать объект IPv(4|6)(Address|Network|Interface), поэтому, скорее всего, захотите получить о нём информацию. [`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) старается сделать это простым и интуитивно понятным.

Извлечение версии IP:

```python
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr6 = ipaddress.ip_address('2001:db8::1')
>>> addr6.version
6
>>> addr4.version
4
```

Получение сети из интерфейса:

```python
>>> host4 = ipaddress.ip_interface('192.0.2.1/24')
>>> host4.network
IPv4Network('192.0.2.0/24')
>>> host6 = ipaddress.ip_interface('2001:db8::1/96')
>>> host6.network
IPv6Network('2001:db8::/96')
```

Определение количества отдельных адресов в сети:

```python
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> net4.num_addresses
256
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
>>> net6.num_addresses
4294967296
```

Перебор «используемых» адресов в сети:

```python
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> for x in net4.hosts():
...     print(x)  
192.0.2.1
192.0.2.2
192.0.2.3
192.0.2.4
...
192.0.2.252
192.0.2.253
192.0.2.254
```

Получение маски сети (т.е. битов, установленных в соответствии с префиксом сети) или маски хоста (все биты, не входящие в маску сети):

```python
>>> net4 = ipaddress.ip_network('192.0.2.0/24')
>>> net4.netmask
IPv4Address('255.255.255.0')
>>> net4.hostmask
IPv4Address('0.0.0.255')
>>> net6 = ipaddress.ip_network('2001:db8::0/96')
>>> net6.netmask
IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')
>>> net6.hostmask
IPv6Address('::ffff:ffff')
```

Развёртывание или сжатие адреса:

```python
>>> addr6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0001'
>>> addr6.compressed
'2001:db8::1'
>>> net6.exploded
'2001:0db8:0000:0000:0000:0000:0000:0000/96'
>>> net6.compressed
'2001:db8::/96'
```

Хотя IPv4 не поддерживает развёртывание или сжатие, соответствующие объекты всё равно предоставляют соответствующие свойства, чтобы код, не зависящий от версии, мог легко обеспечить использование самой краткой или самой полной формы для IPv6-адресов, при этом корректно обрабатывая IPv4-адреса.

## Сети как списки адресов

Иногда бывает полезно рассматривать сети как списки. Это означает, что их можно индексировать, например, так:

```python
>>> net4[1]
IPv4Address('192.0.2.1')
>>> net4[-1]
IPv4Address('192.0.2.255')
>>> net6[1]
IPv6Address('2001:db8::1')
>>> net6[-1]
IPv6Address('2001:db8::ffff:ffff')
```

Это также означает, что сетевые объекты можно использовать с синтаксисом проверки принадлежности к списку, например, так:

```python
if address in network:
    # выполнить действие
```

Проверка принадлежности выполняется эффективно на основе префикса сети:

```python
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> addr4 in ipaddress.ip_network('192.0.2.0/24')
True
>>> addr4 in ipaddress.ip_network('192.0.3.0/24')
False
```

## Сравнения

[`ipaddress`](https://python-all.ru/3.4/library/ipaddress.html#module-ipaddress) предоставляет несколько простых, надеемся, интуитивных способов сравнения объектов, когда это имеет смысл:

```python
>>> ipaddress.ip_address('192.0.2.1') < ipaddress.ip_address('192.0.2.2')
True
```

Исключение [`TypeError`](https://python-all.ru/3.4/library/exceptions.html#TypeError) возбуждается при попытке сравнить объекты разных версий или разных типов.

## Использование IP-адресов с другими модулями

Другие модули, использующие IP-адреса (например, [`socket`](https://python-all.ru/3.4/library/socket.html#module-socket)), обычно не принимают объекты этого модуля напрямую. Вместо этого их необходимо преобразовать в целое число или строку, которые другой модуль сможет принять:

```python
>>> addr4 = ipaddress.ip_address('192.0.2.1')
>>> str(addr4)
'192.0.2.1'
>>> int(addr4)
3221225985
```

## Получение более подробной информации при сбое создания экземпляра

When creating address/network/interface objects using the version-agnostic factory functions, any errors will be reported as [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) with a generic error message that simply says the passed in value was not recognized as an object of that type. The lack of a specific error is because it’s necessary to know whether the value is *supposed* to be IPv4 or IPv6 in order to provide more detail on why it has been rejected.

Для поддержки случаев, когда полезно иметь доступ к этой дополнительной информации, отдельные конструкторы классов фактически возбуждают подклассы [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) – [`ipaddress.AddressValueError`](https://python-all.ru/3.4/library/ipaddress.html#ipaddress.AddressValueError) и [`ipaddress.NetmaskValueError`](https://python-all.ru/3.4/library/ipaddress.html#ipaddress.NetmaskValueError) – чтобы указать, какая именно часть определения не была разобрана правильно.

Сообщения об ошибках становятся значительно более подробными при прямом использовании конструкторов классов. Например:

```python
>>> ipaddress.ip_address("192.168.0.256")
Traceback (most recent call last):
  ...
ValueError: '192.168.0.256' does not appear to be an IPv4 or IPv6 address
>>> ipaddress.IPv4Address("192.168.0.256")
Traceback (most recent call last):
  ...
ipaddress.AddressValueError: Octet 256 (> 255) not permitted in '192.168.0.256'

>>> ipaddress.ip_network("192.168.0.1/64")
Traceback (most recent call last):
  ...
ValueError: '192.168.0.1/64' does not appear to be an IPv4 or IPv6 network
>>> ipaddress.IPv4Network("192.168.0.1/64")
Traceback (most recent call last):
  ...
ipaddress.NetmaskValueError: '64' is not a valid netmask
```

Однако оба специфических для модуля исключения имеют [`ValueError`](https://python-all.ru/3.4/library/exceptions.html#ValueError) в качестве родительского класса, так что если вас не волнует конкретный тип ошибки, вы по-прежнему можете писать код следующим образом:

```python
try:
    network = ipaddress.IPv4Network(address)
except ValueError:
    print('address/netmask is invalid for IPv4:', address)
```