1# The iplib module
2
3The iplib module contains many functions, classes and constants useful to manage IP addresses and netmasks.
4
5You can use this Python module (and the scripts 'ipconv', 'nmconv' and 'cidrinfo') to convert amongst many different notations and to manage couples of address/netmask in the CIDR notation.
6
7iplib was written a long time ago and the code shows its age.
8In June 2018, with the release of version 1.2, it was converted to support both Python 2 and Python 3 (without any other refactoring).
9
10
11# Functions
12
13## Format check
14
15These functions always return True or False (never raise exceptions) and can be called with any kind of arguments (integers, strings and objects with a __str__() method which returns a suitable string):
16
17* is_dot(ip): Return True if the IP address is in dotted decimal notation.
18* is_hex(ip): Return True if the IP address is in hexadecimal notation.
19* is_bin(ip): Return True if the IP address is in binary notation.
20* is_oct(ip): Return True if the IP address is in octal notation.
21* is_dec(ip): Return True if the IP address is in decimal notation.
22* is_dot_nm(nm): Return True if the netmask is in dotted decimal notatation.
23* is_hex_nm(nm): Return True if the netmask is in hexadecimal notatation.
24* is_bin_nm(nm): Return True if the netmask is in binary notatation.
25* is_oct_nm(nm): Return True if the netmask is in octal notatation.
26* is_dec_nm(nm): Return True if the netmask is in decimal notatation.
27* is_bits_nm(nm): Return True if the netmask is in bits notatation.
28* is_wildcard_nm(nm): Return True if the netmask is in wildcard bits notatation.
29
30## Format detection
31
32Functions to detect IP/netmask notation; return IP_UNKNOWN/NM_UNKNOWN if the IP/netmask notation is not detected:
33
34* detect(ip): Try to detect the notation of an IP address.
35* detect_nm(nm): Try to detect the notation of a netmask.
36* p_detect(ip) and p_detect_nm(nm): detect the notation of an IP address (or netmask) and return a nice string ('unknown' if it's not detected).
37* is_notation(ip, notation) and is_notation_nm(nm, notation): return True if the given IP address  (or netmask) is in the specified notation.
38
39## Conversions
40
41Function to convert IP/netmask; can raise a ValueError exception:
42
43* convert(ip, notation=IP_DOT, inotation=IP_UNKNOWN) and convert_nm(nm, notation=IP_DOT, inotation=IP_UNKNOWN): Convert the given IP address (or netmask) to the given notation; the 'notation' argument set the notation of the output; the 'inotation' argument force the input to be considered as an address in the specified notation. When the IP address (or netmask) is an integer, the inotation argument is assumed to be IP_DEC (if not set otherwise).
44
45
46#  Classes
47
48## IPv4Address
49
50* IPv4Address(ip, notation=IP_UNKNOWN): This class represents an IPv4 Internet address.
51
52An IPv4Address object can be used to sum or subtract two IP address; the second argument can also be an integer, so that, if you want to know what's the 1000th IP address after 127.0.0.1, you can:
53
54  >>> import iplib
55  >>> ip = iplib.IPv4Address('127.0.0.1')
56  >>> ip + 1000
57  <IPv4 address 127.0.3.233>
58
59It's also possible to compare two IP addresses (the same is true for netmasks); e.g.:
60
61  >>> iplib.IPv4Address('127.0.0.1') < iplib.IPv4Address('127.0.0.4')
62  True
63
64For both IPv4Address and IPv4NetMask object you can force the notation with the 'notation' option; e.g.:
65
66  >>> iplib.IPv4Address('24323', iplib.IP_OCT)
67  # that's equivalent to:
68  >>> iplib.IPv4Address('24323', 'oct')
69  # and:
70  >>> iplib.IPv4Address('24323', 'octal')
71
72
73## IPv4NetMask
74
75* IPv4NetMask(nm, notation=IP_UNKNOWN): This class represents an IPv4 Internet netmask.
76
77
78## CIDR
79
80* CIDR(ip, netmask=None): The representation of a Classless Inter-Domain Routing (CIDR) address.
81
82From objects instance of this class, you can retrieve informations about the number of usable IP addresses, the first and the last usable address, the broadcast and the netword address.
83The netmask can be omitted, if the ip argument is a string 'ip/nm'; e.g.:
84
85  >>> cidr = iplib.CIDR('127.0.0.1', '8')
86  # is equivalent to:
87  >>> cidr = iplib.CIDR('127.0.0.1/8')
88
89Using the is_valid_ip(self, ip) method you can guess if the provided IP address is amongst the usable addresses; e.g.:
90
91  >>> cidr = iplib.CIDR('127.0.0.1/8')
92  >>> cidr.is_valid_ip('127.4.5.6')
93  True
94
95#  Constants
96
97The following constants are used to define IP/netmask notations:
98
99* IP_DOT and NM_DOT: an IP address (or netmask) in dotted decimal notation (e.g.: 192.168.0.42).
100* IP_HEX and NM_HEX: hexadecimal notation (0xC0A8002A).
101* IP_BIN and NM_BIN: binary notation (11000000101010000000000000101010).
102* IP_OCT and NM_OCT: octal notation (030052000052).
103* IP_DEC and NM_DEC: decimal notation (3232235562).
104* NM_BITS: netmask in bits notation (24).
105* NM_WILDCARD: netmask in wildcard bits notation (0.0.0.255).
106* IP_UNKNOWN and NM_UNKNOWN: an IP address (or netmask) in a unknown notation.
107* NOTATION_MAP: a dictionary that maps notations with a list of strings that can be used instead of the IP_* and NM_* constants.
108* VALID_NETMASKS: a dictionary that maps valid netmask in bits notation with their values in decimal notation.
109
110E.g.: you can call the convert() function in these two equivalent ways:
111
112* iplib.convert('192.168.0.42', notation=iplib.IP_HEX)
113* iplib.convert('192.168.0.42', 'hex')
114
115The following strings can be used instead of constants:
116
117* 'binary', 'bin': IP_BIN/NM_BIN
118* 'octal', 'oct': IP_OCT/NM_OCT
119* 'decimal', 'dec': IP_DEC/NM_DEC
120* 'bits', 'bit', 'cidr': NM_BITS
121* 'wildcard bits', 'wildcard': NM_WILDCARD
122* 'unknown', 'unk': IP_UNKNOWN/NM_UNKNOWN
123
124# License
125
126This code is release under the BSD license.
127
128# Copyright
129
130Copyright 2005-2018 Davide Alberani <da@erlug.linux.it>
131
132