21.28. ipaddress
- IPv4 / IPv6操作库¶
源代码: Lib / ipaddress.py
ipaddress
提供创建,操作和操作IPv4和IPv6地址和网络的功能。
此模块中的函数和类可以直接处理与IP地址相关的各种任务,包括检查两个主机是否在同一子网上,遍历特定子网中的所有主机,检查字符串是否表示有效IP地址或网络定义等。
这是完整的模块API参考 - 有关概述和简介,请参阅An introduction to the ipaddress module。
版本3.3中的新功能。
21.28.1. Convenience factory functions¶
ipaddress
模块提供了工厂功能,可以方便地创建IP地址,网络和接口:
-
ipaddress.
ip_address
(address)¶ 根据作为参数传递的IP地址,返回
IPv4Address
或IPv6Address
对象。可以提供IPv4或IPv6地址;默认情况下,小于2 ** 32的整数将被视为IPv4。如果地址不表示有效的IPv4或IPv6地址,则会引发ValueError
。>>> ipaddress.ip_address('192.168.0.1') IPv4Address('192.168.0.1') >>> ipaddress.ip_address('2001:db8::') IPv6Address('2001:db8::')
-
ipaddress.
ip_network
(address, strict=True)¶ 根据作为参数传递的IP地址,返回
IPv4Network
或IPv6Network
对象。地址是表示IP网络的字符串或整数。可以提供IPv4或IPv6网络;默认情况下,小于2 ** 32的整数将被视为IPv4。严格传递到IPv4Network
或IPv6Network
构造函数。如果地址不表示有效的IPv4或IPv6地址,或者如果网络已设置主机位,则会引发ValueError
。>>> ipaddress.ip_network('192.168.0.0/28') IPv4Network('192.168.0.0/28')
-
ipaddress.
ip_interface
(address)¶ 根据作为参数传递的IP地址,返回
IPv4Interface
或IPv6Interface
对象。地址是表示IP地址的字符串或整数。可以提供IPv4或IPv6地址;默认情况下,小于2 ** 32的整数将被视为IPv4。如果地址不表示有效的IPv4或IPv6地址,则会引发ValueError
。
这些便利功能的一个缺点是,需要处理IPv4和IPv6格式意味着错误消息提供关于精确错误的最少信息,因为功能不知道IPv4或IPv6格式是否是预期的。可以通过直接调用适当的特定于类的构造函数来获取更详细的错误报告。
21.28.2. IP Addresses¶
21.28.2.1. Address objects¶
IPv4Address
和IPv6Address
对象共享许多常见属性。一些仅对IPv6地址有意义的属性也由IPv4Address
对象实现,以便于更容易编写正确处理两个IP版本的代码。
- class
ipaddress.
IPv4Address
(address)¶ 构造IPv4地址。如果地址不是有效的IPv4地址,则会产生
AddressValueError
。以下构成有效的IPv4地址:
- 以十进制点表示法的字符串,由四个十进制整数组成,包含范围0-255,用点分隔。
192.168.0.1
)。每个整数表示地址中的八位字节(字节)。只有小于8的值才允许前导零(因为这种字符串的十进制和八进制解释之间没有歧义)。 - 适合32位的整数。
- 整数打包成长度为4(最高有效字节优先)的
bytes
对象。
>>> 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')
-
version
¶ 适当的版本号:IPv4的
4
,IPv6的6
。
-
max_prefixlen
¶ 此版本的地址表示中的总位数:IPv4的
32
,IPv6的128
。前缀定义了地址中前导比特的数量,这些比特被比较以确定地址是否是网络的一部分。
-
compressed
¶
-
exploded
¶ 以点分十进制符号表示的字符串。前导零从不包括在表示中。
由于IPv4没有为八位字节设置为零的地址定义速记符号,因此这两个属性对于IPv4地址始终与
str(addr)
相同。暴露这些属性使得编写能够处理IPv4和IPv6地址的显示代码变得更容易。
-
reverse_pointer
¶ IP地址的反向DNS PTR记录的名称,例如:
>>> 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_private
¶ True
如果地址分配给专用网络。请参阅iana-ipv4-special-registry(适用于IPv4)或iana-ipv6-special-registry(适用于IPv6)。
-
is_global
¶ True
如果地址分配给公共网络。请参阅iana-ipv4-special-registry(适用于IPv4)或iana-ipv6-special-registry(适用于IPv6)。版本3.4中的新功能。
-
is_reserved
¶ True
如果地址是其他IETF保留。
- 以十进制点表示法的字符串,由四个十进制整数组成,包含范围0-255,用点分隔。
- class
ipaddress.
IPv6Address
(address)¶ 构造IPv6地址。如果地址不是有效的IPv6地址,则会产生
AddressValueError
。以下构成有效的IPv6地址:
- 一个由八组四个十六进制数字组成的字符串,每组代表16位。这些组由冒号分隔。这描述了分解的(长符)符号。字符串也可以通过各种方法压缩(简写符号)。有关详细信息,请参阅 RFC 4291。例如,
"0000:0000:0000:0000:0000:0abc:0007:0def"
可以压缩为"::abc:7:def"
- 适合128位的整数。
- 整数打包成长度为16,big-endian的
bytes
对象。
>>> ipaddress.IPv6Address('2001:db8::1000') IPv6Address('2001:db8::1000')
-
compressed
¶
地址表示的短形式,其中组中的前导零被省略并且组的最长序列完全由零组成,折叠到单个空组。
这也是
str(addr)
为IPv6地址返回的值。-
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
。
- 一个由八组四个十六进制数字组成的字符串,每组代表16位。这些组由冒号分隔。这描述了分解的(长符)符号。字符串也可以通过各种方法压缩(简写符号)。有关详细信息,请参阅 RFC 4291。例如,
21.28.2.2. Conversion to Strings and Integers¶
要与网络接口(如套接字模块)互操作,地址必须转换为字符串或整数。这是使用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
21.28.2.3. Operators¶
地址对象支持一些操作符。除非另有说明,操作员只能在兼容对象之间应用。IPv4与IPv4,IPv6与IPv6)。
21.28.2.3.1. Comparison operators¶
地址对象可以与通常的一组比较运算符进行比较。一些例子:
>>> 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
21.28.2.3.2. Arithmetic operators¶
整数可以添加到地址对象或从地址对象中减去。一些例子:
>>> 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
21.28.3. IP Network definitions¶
IPv4Network
和IPv6Network
对象提供了一种定义和检查IP网络定义的机制。网络定义由掩码和网络地址组成,因此定义了在使用掩码进行掩码(二进制AND)时等于网络地址的IP地址范围。For example, a network definition with the mask 255.255.255.0
and the network address 192.168.1.0
consists of IP addresses in the inclusive range 192.168.1.0
to 192.168.1.255
.
21.28.3.1. Prefix, net mask and host mask¶
有几种等效的方法来指定IP网络掩码。前缀 /<nbits>
是表示在网络掩码中设置了多少个高阶比特的符号。网络掩码是设置了一些数量的高阶位的IP地址。因此,前缀/24
等效于IPv4中的网络掩码255.255.255.0
或IPv6中的ffff:ff00::
。此外,主机掩码是网络掩码的逻辑反转,并且有时(例如在Cisco访问控制列表中)用于表示网络掩码。IPv4中等效于/24
的主机掩码为0.0.0.255
。
21.28.3.2. Network objects¶
地址对象实现的所有属性也由网络对象实现。此外,网络对象实现附加属性。所有这些在IPv4Network
和IPv6Network
之间是常见的,因此为了避免重复,它们仅记录在IPv4Network
。
- class
ipaddress.
IPv4Network
(address, strict=True)¶ 构造IPv4网络定义。地址可以是以下之一:
由IP地址和可选掩码组成的字符串,以斜杠(
/
)分隔。IP地址是网络地址,掩码可以是单个数字,这意味着它是前缀,也可以是IPv4地址的字符串表示形式。如果是后者,如果它以非零字段开始,则掩码被解释为网络掩码,如果它以零字段开始,则被解释为主机掩码。如果没有提供掩码,它被认为是/32
。例如,以下地址规范是等效的:
192.168.1.0/24
,192.168.1.0/255.255.255.0
和192.168.1.0/0.0.0.255
。适合32位的整数。这相当于单地址网络,网络地址为地址,掩码为
/32
。整数打包成长度为4,big-endian的
bytes
对象。解释类似于整数地址。地址描述和网络掩码的二元组,其中地址描述是字符串,32位整数,4字节打包整数或现有IPv4Address对象;并且网络掩码是表示前缀长度的整数。
24
)或表示前缀掩码的字符串(例如,255.255.255.0
)。
如果地址不是有效的IPv4地址,则会产生
AddressValueError
。如果掩码对IPv4地址无效,则会引发NetmaskValueError
。如果严格为
True
且主机位在提供的地址中设置,则会引发ValueError
。否则,主机位被屏蔽以确定适当的网络地址。除非另有说明,如果参数的IP版本与
self
不兼容,则接受其他网络/地址对象的所有网络方法都将引用TypeError
在版本3.5中已更改:添加了地址构造函数参数的二元组格式。
-
version
¶
-
max_prefixlen
¶ 请参阅
IPv4Address
中的相应属性文档
-
is_multicast
¶
-
is_private
¶
-
is_unspecified
¶
-
is_reserved
¶
-
is_loopback
¶
-
is_link_local
¶ 这些属性对于网络作为整体是真实的,如果它们对于网络地址和广播地址是真的
-
network_address
¶ 网络的网络地址。网络地址和前缀长度一起唯一地定义网络。
-
broadcast_address
¶ 网络的广播地址。发送到广播地址的数据包应该由网络上的每个主机接收。
-
hostmask
¶ 主机掩码,作为字符串。
-
with_prefixlen
¶
-
compressed
¶
-
exploded
¶ 网络的字符串表示,带有前缀符号的掩码。
with_prefixlen
和compressed
始终与str(network)
相同。exploded
使用网络地址的分解形式。
-
with_netmask
¶ 网络的字符串表示,带有网络掩码符号的掩码。
-
with_hostmask
¶ 网络的字符串表示,在主机掩码符号中带有掩码。
-
num_addresses
¶ 网络中的地址总数。
-
prefixlen
¶ 网络前缀的长度(以位为单位)。
-
hosts
()¶ 在网络中的可用主机上返回迭代器。可用主机是属于网络的所有IP地址,除了网络地址本身和网络广播地址。
>>> 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')]
-
overlaps
(other)¶ True
如果此网络部分或全部包含在其他或其他完全包含在此网络中。
-
address_exclude
(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')
-
compare_networks
(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
- class
ipaddress.
IPv6Network
(address, strict=True)¶ 构造IPv6网络定义。地址可以是以下之一:
由IP地址和可选掩码组成的字符串,以斜杠(
/
)分隔。IP地址是网络地址,掩码可以是单个数字,这意味着它是前缀或IPv6地址的字符串表示形式。如果是后者,则掩码被解释为网络掩码。如果没有提供掩码,则认为是/128
。例如,以下地址规范是等效的:
2001:db00::0/24
和2001:db00::0/ffff:ff00::
适合128位的整数。这相当于单地址网络,网络地址为地址,掩码为
/128
。整数打包成长度为16,big-endian的
bytes
对象。解释类似于整数地址。地址描述和网络掩码的二元组,其中地址描述是字符串,128位整数,16字节打包整数或现有的IPv6地址对象;并且网络掩码是表示前缀长度的整数。
如果地址不是有效的IPv6地址,则会产生
AddressValueError
。如果掩码对IPv6地址无效,则会引发NetmaskValueError
。如果严格为
True
且主机位在提供的地址中设置,则会引发ValueError
。否则,主机位被屏蔽以确定适当的网络地址。在版本3.5中已更改:添加了地址构造函数参数的二元组格式。
-
version
¶
-
max_prefixlen
¶
-
is_multicast
¶
-
is_private
¶
-
is_unspecified
¶
-
is_reserved
¶
-
is_loopback
¶
-
is_link_local
¶
-
network_address
¶
-
broadcast_address
¶
-
hostmask
¶
-
with_prefixlen
¶
-
compressed
¶
-
exploded
¶
-
with_netmask
¶
-
with_hostmask
¶
-
num_addresses
¶
-
prefixlen
¶
-
hosts
()¶
-
overlaps
(other)¶
-
address_exclude
(network)¶
-
subnets
(prefixlen_diff=1, new_prefix=None)¶
-
supernet
(prefixlen_diff=1, new_prefix=None)¶
-
compare_networks
(other)¶ 请参阅
IPv4Network
中的相应属性文档
-
is_site_local
¶ 如果对于网络地址和广播地址都是真的,则这些属性对于网络作为整体是真实的
21.28.3.3. Operators¶
网络对象支持一些运算符。除非另有说明,操作员只能在兼容对象之间应用。IPv4与IPv4,IPv6与IPv6)。
21.28.3.3.1. Logical operators¶
网络对象可以与通常的一组逻辑运算符进行比较,类似于地址对象。
21.28.3.3.2. Iteration¶
可以迭代网络对象以列出属于网络的所有地址。对于迭代,会返回所有主机,包括不可用的主机(对于可用主机,请使用hosts()
方法)。一个例子:
>>> 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')
21.28.3.3.3. Networks as containers of addresses¶
网络对象可以充当地址的容器。一些例子:
>>> 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
21.28.4. Interface objects¶
- class
ipaddress.
IPv4Interface
(address)¶ 构造IPv4接口。address的含义与
IPv4Network
的构造函数中的相同,除了始终接受任意主机地址。IPv4Interface
是IPv4Address
的子类,因此它继承了该类的所有属性。此外,还有以下属性可用:-
ip
¶ 没有网络信息的地址(
IPv4Address
)。>>> interface = IPv4Interface('192.0.2.5/24') >>> interface.ip IPv4Address('192.0.2.5')
-
network
¶ 此接口所属的网络(
IPv4Network
)。>>> interface = IPv4Interface('192.0.2.5/24') >>> interface.network IPv4Network('192.0.2.0/24')
-
with_prefixlen
¶ 带有掩码的接口的字符串表示形式,以前缀符号表示。
>>> interface = IPv4Interface('192.0.2.5/24') >>> interface.with_prefixlen '192.0.2.5/24'
-
with_netmask
¶ 与网络的接口的字符串表示作为网络掩码。
>>> interface = IPv4Interface('192.0.2.5/24') >>> interface.with_netmask '192.0.2.5/255.255.255.0'
-
with_hostmask
¶ 以网络作为主机掩码的接口的字符串表示。
>>> interface = IPv4Interface('192.0.2.5/24') >>> interface.with_hostmask '192.0.2.5/0.0.0.255'
-
- class
ipaddress.
IPv6Interface
(address)¶ 构造IPv6接口。地址的含义与
IPv6Network
的构造函数相同,除了始终接受任意主机地址。IPv6Interface
是IPv6Address
的子类,因此它继承了该类的所有属性。此外,还有以下属性可用:-
ip
¶
-
network
¶
-
with_prefixlen
¶
-
with_netmask
¶
-
with_hostmask
¶ 请参阅
IPv4Interface
中的相应属性文档。
-
21.28.5. Other Module Level Functions¶
该模块还提供以下模块级功能:
-
ipaddress.
v4_int_to_packed
(address)¶ 将地址表示为网络(big-endian)顺序中的4个打包字节。address是IPv4 IP地址的整数表示形式。如果整数为负或太大而不是IPv4 IP地址,则会引发
ValueError
。>>> ipaddress.ip_address(3221225985) IPv4Address('192.0.2.1') >>> ipaddress.v4_int_to_packed(3221225985) b'\xc0\x00\x02\x01'
-
ipaddress.
v6_int_to_packed
(address)¶ 将地址表示为网络(big-endian)顺序中的16个打包字节。address是IPv6 IP地址的整数表示形式。如果整数为负或太大而不是IPv6 IP地址,则会引发
ValueError
。
-
ipaddress.
summarize_address_range
(first, last)¶ 返回给定第一个和最后一个IP地址的汇总网络范围的迭代器。first is the first
IPv4Address
orIPv6Address
in the range and last is the lastIPv4Address
orIPv6Address
in the range. 如果第一或最后不是IP地址或不是相同版本,则会引发TypeError
。如果最后不大于第一或如果第一地址版本不是4或6,则会产生ValueError
>>> [ipaddr for ipaddr in ipaddress.summarize_address_range( ... ipaddress.IPv4Address('192.0.2.0'), ... ipaddress.IPv4Address('192.0.2.130'))] [IPv4Network('192.0.2.0/25'), IPv4Network('192.0.2.128/31'), IPv4Network('192.0.2.130/32')]
-
ipaddress.
collapse_addresses
(addresses)¶ 返回折叠的
IPv4Network
或IPv6Network
对象的迭代器。addresses is an iterator ofIPv4Network
orIPv6Network
objects. 如果地址包含混合版本对象,则会引发TypeError
。>>> [ipaddr for ipaddr in ... ipaddress.collapse_addresses([ipaddress.IPv4Network('192.0.2.0/25'), ... ipaddress.IPv4Network('192.0.2.128/25')])] [IPv4Network('192.0.2.0/24')]