README.rst
1IPy - class and tools for handling of IPv4 and IPv6 addresses and networks.
2
3Website: https://github.com/autocracy/python-ipy/
4
5Presentation of the API
6=======================
7
8The IP class allows a comfortable parsing and handling for most
9notations in use for IPv4 and IPv6 addresses and networks. It was
10greatly inspired by RIPE's Perl module NET::IP's interface but
11doesn't share the implementation. It doesn't share non-CIDR netmasks,
12so funky stuff like a netmask of 0xffffff0f can't be done here. ::
13
14 >>> from IPy import IP
15 >>> ip = IP('127.0.0.0/30')
16 >>> for x in ip:
17 ... print(x)
18 ...
19 127.0.0.0
20 127.0.0.1
21 127.0.0.2
22 127.0.0.3
23 >>> ip2 = IP('0x7f000000/30')
24 >>> ip == ip2
25 1
26 >>> ip.reverseNames()
27 ['0.0.0.127.in-addr.arpa.', '1.0.0.127.in-addr.arpa.', '2.0.0.127.in-addr.arpa.', '3.0.0.127.in-addr.arpa.']
28 >>> ip.reverseName()
29 '0-3.0.0.127.in-addr.arpa.'
30 >>> ip.iptype()
31 'LOOPBACK'
32
33
34Supports most IP address formats
35================================
36
37It can detect about a dozen different ways of expressing IP addresses
38and networks, parse them and distinguish between IPv4 and IPv6 addresses: ::
39
40 >>> IP('10.0.0.0/8').version()
41 4
42 >>> IP('::1').version()
43 6
44
45IPv4 addresses
46--------------
47
48::
49
50 >>> print(IP(0x7f000001))
51 127.0.0.1
52 >>> print(IP('0x7f000001'))
53 127.0.0.1
54 >>> print(IP('127.0.0.1'))
55 127.0.0.1
56 >>> print(IP('10'))
57 10.0.0.0
58
59IPv6 addresses
60--------------
61
62::
63
64 >>> print(IP('1080:0:0:0:8:800:200C:417A'))
65 1080::8:800:200c:417a
66 >>> print(IP('1080::8:800:200C:417A'))
67 1080::8:800:200c:417a
68 >>> print(IP('::1'))
69 ::1
70 >>> print(IP('::13.1.68.3'))
71 ::d01:4403
72
73Network mask and prefixes
74-------------------------
75
76::
77
78 >>> print(IP('127.0.0.0/8'))
79 127.0.0.0/8
80 >>> print(IP('127.0.0.0/255.0.0.0'))
81 127.0.0.0/8
82 >>> print(IP('127.0.0.0-127.255.255.255'))
83 127.0.0.0/8
84
85
86Derive network address
87===========================
88
89IPy can transform an IP address into a network address by applying the given
90netmask: ::
91
92 >>> print(IP('127.0.0.1/255.0.0.0', make_net=True))
93 127.0.0.0/8
94
95This can also be done for existing IP instances: ::
96
97 >>> print(IP('127.0.0.1').make_net('255.0.0.0'))
98 127.0.0.0/8
99
100
101Convert address to string
102=========================
103
104Nearly all class methods which return a string have an optional
105parameter 'wantprefixlen' which controls if the prefixlen or netmask
106is printed. Per default the prefilen is always shown if the network
107contains more than one address: ::
108
109 wantprefixlen == 0 / None don't return anything 1.2.3.0
110 wantprefixlen == 1 /prefix 1.2.3.0/24
111 wantprefixlen == 2 /netmask 1.2.3.0/255.255.255.0
112 wantprefixlen == 3 -lastip 1.2.3.0-1.2.3.255
113
114You can also change the defaults on an per-object basis by fiddling with
115the class members:
116
117- NoPrefixForSingleIp
118- WantPrefixLen
119
120Examples of string conversions: ::
121
122 >>> IP('10.0.0.0/32').strNormal()
123 '10.0.0.0'
124 >>> IP('10.0.0.0/24').strNormal()
125 '10.0.0.0/24'
126 >>> IP('10.0.0.0/24').strNormal(0)
127 '10.0.0.0'
128 >>> IP('10.0.0.0/24').strNormal(1)
129 '10.0.0.0/24'
130 >>> IP('10.0.0.0/24').strNormal(2)
131 '10.0.0.0/255.255.255.0'
132 >>> IP('10.0.0.0/24').strNormal(3)
133 '10.0.0.0-10.0.0.255'
134 >>> ip = IP('10.0.0.0')
135 >>> print(ip)
136 10.0.0.0
137 >>> ip.NoPrefixForSingleIp = None
138 >>> print(ip)
139 10.0.0.0/32
140 >>> ip.WantPrefixLen = 3
141 >>> print(ip)
142 10.0.0.0-10.0.0.0
143
144Work with multiple networks
145===========================
146
147Simple addition of neighboring netblocks that can be aggregated will yield
148a parent network of both, but more complex range mapping and aggregation
149requires is available with the ``IPSet`` class which will hold any number of
150unique address ranges and will aggregate overlapping ranges. ::
151
152 >>> from IPy import IP, IPSet
153 >>> IP('10.0.0.0/22') - IP('10.0.2.0/24')
154 IPSet([IP('10.0.0.0/23'), IP('10.0.3.0/24')])
155 >>> IPSet([IP('10.0.0.0/23'), IP('10.0.3.0/24'), IP('10.0.2.0/24')])
156 IPSet([IP('10.0.0.0/22')])
157 >>> s = IPSet([IP('10.0.0.0/22')])
158 >>> s.add(IP('192.168.1.0/29'))
159 >>> s
160 IPSet([IP('10.0.0.0/22'), IP('192.168.1.0/29')])
161 >>> s.discard(IP('192.168.1.2'))
162 >>> s
163 IPSet([IP('10.0.0.0/22'), IP('192.168.1.0/31'), IP('192.168.1.3'), IP('192.168.1.4/30')])
164
165``IPSet`` supports the ``set`` method ``isdisjoint``: ::
166
167 >>> s.isdisjoint(IPSet([IP('192.168.0.0/16')]))
168 False
169 >>> s.isdisjoint(IPSet([IP('172.16.0.0/12')]))
170 True
171
172``IPSet`` supports intersection: ::
173
174 >>> s & IPSet([IP('10.0.0.0/8')])
175 IPSet([IP('10.0.0.0/22')])
176
177Compatibility and links
178=======================
179
180IPy 1.01 works on Python version 2.6 - 3.7.
181
182The IP module should work in Python 2.5 as long as the subtraction operation
183is not used. IPSet requires features of the collecitons class which appear
184in Python 2.6, though they can be backported.
185
186Eratta
187======
188
189When using IPv6 addresses, it is best to compare using ``IP().len()``
190instead of ``len(IP)``. Addresses with an integer value > 64 bits can break
191the 2nd method. See http://stackoverflow.com/questions/15650878 for more
192info.
193
194Fuzz testing for ``IPSet`` will throw spurious errors when the ``IPSet`` module
195combines two smaller prefixes into a larger prefix that matches the random
196prefix tested against.
197
198This Python module is under BSD license: see COPYING file.
199
200Further Information might be available at:
201https://github.com/autocracy/python-ipy
202