Esta documentação é de uma versão antiga do Python que não é mais atualizada. Você deveria atualizar e ler a Documentação do Python para versão estável atual.

# Uma introdução ao módulo ipaddress

autor

  Peter Moody

autor

  Nick Coghlan

Visão Geral

Este documento tem como objetivo prover uma suave introdução ao módulo `ipaddress`. Ele é direcionado primeiramente para usuários que ainda não são familiarizados com a terminologia de rede IP, mas também pode ser útil para engenheiros de rede que querem uma visão geral de como `ipaddress` representa os conceitos de endereçamento de rede IP.

## Criando objetos de Endereço/Rede/Interface

Como `ipaddress` é um módulo para inspecionar e manipular endereços IP, a primeira coisa que você deseja fazer é criar alguns objetos. Você pode usar `ipaddress` para criar objetos a partir de strings e inteiros.

### Uma observação sobre versões do IP

For readers that aren’t particularly familiar with IP addressing, it’s important to know that the Internet Protocol is currently in the process of moving from version 4 of the protocol to version 6. This transition is occurring largely because version 4 of the protocol doesn’t provide enough addresses to handle the needs of the whole world, especially given the increasing number of devices with direct connections to the internet.

Explicar os detalhes das diferenças entre as duas versões do protocolo está além do escopo desta introdução, mas os leitores precisam pelo menos estar cientes de que essas duas versões existem, e às vezes será necessário forçar o uso de uma versão ou do outro.

### Endereços IP de host

Os endereços, muitas vezes chamados de “endereços de host”, são a unidade mais básica ao trabalhar com endereçamento IP. A maneira mais simples de criar endereços é usar a função de fábrica `ipaddress.ip_address()`, que determina automaticamente se deve ser criado um endereço IPv4 ou IPv6 com base no valor passado:

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

Os endereços também podem ser criados diretamente a partir de números inteiros. Os valores que cabem em 32 bits são considerados endereços IPv4:

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

Para forçar o uso de endereços IPv4 ou IPv6, as classes relevantes podem ser invocadas diretamente. Isto é particularmente útil para forçar a criação de endereços IPv6 para números inteiros pequenos:

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

### Definindo redes

Endereços de host geralmente são agrupados em redes IP, então `ipaddress` fornece uma maneira de criar, inspecionar e manipular definições de rede. Os objetos de rede IP são construídos a partir de strings que definem o intervalo de endereços de host que fazem parte dessa rede. A forma mais simples para essa informação é um par de “endereço de rede/prefixo de rede”, onde o prefixo define o número de bits iniciais que são comparados para determinar se um endereço faz ou não parte da rede e o endereço de rede define o valor esperado daqueles bits.

Quanto aos endereços, é fornecida uma função de fábrica que determina automaticamente a versão correta do IP:

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

Os objetos de rede não podem ter nenhum bit de host definido. O efeito prático disso é que `192.0.2.1/24` não descreve uma rede. Tais definições são chamadas de objetos interface, uma vez que a notação “ip-em-uma-rede” é comumente usada para descrever interfaces de rede de um computador em uma determinada rede e é descrita mais detalhadamente na próxima seção.

Por padrão, tentar criar um objeto rede com bits de host definidos resultará na exceção `ValueError` ser levantada. Para solicitar que os bits adicionais sejam forçados a zero, o sinalizador `strict=False` pode ser passada para o construtor:

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

Embora o formato string ofereça significativamente mais flexibilidade, as redes também podem ser definidas com números inteiros, assim como os endereços de host. Neste caso, considera-se que a rede contém apenas o endereço único identificado pelo número inteiro, portanto o prefixo da rede inclui todo o endereço da rede:

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

Tal como acontece com os endereços, a criação de um tipo específico de rede pode ser forçada chamando diretamente o construtor da classe em vez de usar a função de fábrica.

### Interfaces do host

Conforme mencionado acima, se você precisar descrever um endereço em uma rede específica, nem o endereço nem as classes de rede serão suficientes. Notação como `192.0.2.1/24` é comumente usada por engenheiros de rede e pessoas que escrevem ferramentas para firewalls e roteadores como uma abreviação para “o host `192.0.2.1` na rede `192.0.2.0/24`”, Consequentemente, `ipaddress` fornece um conjunto de classes híbridas que associam um endereço a uma rede específica. A interface para criação é idêntica àquela para definição de objetos de rede, exceto que a parte do endereço não está restrita a ser um endereço de rede.

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

Entradas de inteiros são aceitas (como acontece com redes), e o uso de uma versão IP específica pode ser forçado chamando diretamente o construtor relevante.

## Inspecionando objetos endereço/rede/interface

Você se deu ao trabalho de criar um objeto IPv(4|6)(Address|Network|Interface) e provavelmente deseja obter informações sobre ele. `ipaddress` tenta tornar isso fácil e intuitivo.

Extraindo a versão do IP:

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

Obtendo a rede de uma interface:

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

Descobrindo quantos endereços individuais estão em uma rede:

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

Iterando através dos endereços “utilizáveis” em uma rede:

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

Obtendo a máscara de rede (ou seja, definir bits correspondentes ao prefixo da rede) ou a máscara de host (qualquer bit que não faça parte da máscara de rede):

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

Explodindo ou compactando o endereço:

    >>> 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'

Embora o IPv4 não tenha suporte a explosão ou compactação, os objetos associados ainda fornecem as propriedades relevantes para que o código de versão neutra possa facilmente garantir que o formato mais conciso ou mais detalhado seja usado para endereços IPv6, ao mesmo tempo que manipula corretamente os endereços IPv4.

## Redes como listas de Addresses

Às vezes é útil tratar redes como listas. Isso significa que é possível indexá-las assim:

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

Isso também significa que os objetos de rede se prestam ao uso da sintaxe de teste de pertinência de lista como esta:

    if address in network:
        # do something

O teste de contenção é feito de forma eficiente com base no prefixo de rede:

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

## Comparações

`ipaddress` fornece algumas maneiras simples e, esperançosamente, intuitivas de comparar objetos, onde faz sentido:

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

Uma exceção `TypeError` é levantada se você tentar comparar objetos de versões ou tipos diferentes.

## Usando endereços IP com outros módulos

Outros módulos que usam endereços IP (como `socket`) geralmente não aceitam objetos deste módulo diretamente. Em vez disso, eles devem ser convertidos para um inteiro ou string que o outro módulo aceitará:

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

## Obtendo mais detalhes quando a criação da instância falha

Ao criar objetos de endereço/rede/interface usando as funções de fábrica agnósticas de versão, quaisquer erros serão relatados como `ValueError` com uma mensagem de erro genérica que simplesmente diz que o valor passado não foi reconhecido como um objeto daquele tipo. A falta de um erro específico é porque é necessário saber se o valor supõe ser IPv4 ou IPv6 para fornecer mais detalhes sobre o motivo de sua rejeição.

Para dar suporte a casos de uso em que é útil ter acesso a esse detalhe adicional, os construtores de classe individuais na verdade geram as subclasses `ValueError` `ipaddress.AddressValueError` e `ipaddress.NetmaskValueError` para indicar exatamente qual parte da definição falhou ao ser analisada corretamente.

As mensagens de erro são significativamente mais detalhadas ao usar os construtores de classe diretamente. Por exemplo:

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

Entretanto, ambas as exceções específicas do módulo têm `ValueError` como classe pai, então se você não estiver preocupado com o tipo específico de erro, você ainda pode escrever código como o seguinte:

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