Package netaddr :: Module address :: Class CIDR
[hide private]
[frames] | no frames]

Class CIDR

source code

object --+    
         |    
   IPRange --+
             |
            CIDR

Represents blocks of IPv4 and IPv6 addresses using CIDR (Classless Inter-Domain Routing) notation.

CIDR is a method of categorising contiguous blocks of both IPv4 and IPv6 addresses. It is very scalable allowing for the optimal usage of the IP address space. It permits the aggregation of networks via route summarisation (supernetting) where adjacent routes can be combined into a single route easily. This greatly assists in the reduction of routing table sizes and improves network router efficiency.

CIDR blocks are represented by a base network address and a prefix indicating the size of the (variable length) subnet mask. These are separated by a single '/' character. Subnet sizes increase in powers of base 2 aligning to bit boundaries.

It is technically invalid to have non-zero bits in a CIDR address to the right of the implied netmask. For user convenience this is however configurable and can be disabled using a constructor argument.

The constructor accepts CIDRs expressed in one of 4 different ways :-

A) Standard CIDR format :-

IPv4:

   x.x.x.x/y -> 192.0.2.0/24

where the x's represent the network address and y is the netmask prefix between 0 and 32.

IPv6:

   x::/y -> fe80::/10

where the x's represent the network address and y is the netmask prefix between 0 and 128.

B) Abbreviated CIDR format (IPv4 only):

   x       -> 192
   x/y     -> 10/8
   x.x/y   -> 192.168/16
   x.x.x/y -> 192.168.0/24

which are equivalent to:

   x.0.0.0/y   -> 192.0.0.0/24
   x.0.0.0/y   -> 10.0.0.0/8
   x.x.0.0/y   -> 192.168.0.0/16
   x.x.x.0/y   -> 192.168.0.0/24

   - The trailing zeros are implicit.
   - Old classful IP address rules apply if y is omitted.

C) Hybrid CIDR format (prefix replaced by netmask) :-

IPv4:

   x.x.x.x/y.y.y.y -> 192.0.2.0/255.255.255.0

IPv6:

   x::/y:: -> fe80::/ffc0::

where the y's represent a valid netmask.

D) ACL-style CIDR format (prefix is replaced by a hostmask) :-

Akin to Cisco's ACL (Access Control List) bitmasking (reverse netmasks).

IPv4:

   x.x.x.x/y.y.y.y -> 192.0.2.0/0.0.0.255

IPv6:

   x::/y:: -> fe80::/3f:ffff:ffff:ffff:ffff:ffff:ffff:ffff

where the y's represent a valid hostmask.

Reference: RFCs 1338 and 4632.

Instance Methods [hide private]
 
__init__(self, cidr, fmt=<class 'netaddr.address.IP'>, strict=True, expand_abbrev=True)
Constructor.
source code
 
__sub__(self, other)
Subtract another CIDR from this one.
source code
 
__add__(self, other)
Add another CIDR to this one returning a CIDR supernet that will contain both in the smallest possible sized range.
source code
 
previous(self, step=1)
Returns: The immediate (adjacent) predecessor of this CIDR.
source code
 
next(self, step=1)
Returns: The immediate (adjacent) successor of this CIDR.
source code
 
iter_host_addrs(self)
Returns: An iterator object providing access to all valid host IP addresses within the specified CIDR block.
source code
 
supernet(self, prefixlen=0, fmt=None)
Provides a list of supernet CIDRs for the current CIDR between the size of the current prefix and (if specified) the end CIDR prefix.
source code
 
subnet(self, prefixlen, count=None, fmt=None)
A generator that returns CIDR subnets based on the current network base address and provided CIDR prefix and count.
source code
 
cidrs(self)
Returns: A list of a copy of this CIDR object.
source code
 
__str__(self)
str(x)
source code
 
__repr__(self)
Returns: executable Python string to recreate equivalent object.
source code

Inherited from object: __delattr__, __getattribute__, __new__, __reduce__, __reduce_ex__, __setattr__

    Inherited from IPRange
 
__contains__(self, addr)
Returns: True if given address or range falls within this range, False otherwise.
source code
 
__eq__(self, other)
Returns: True if the boundaries of this range are the same as other, False otherwise.
source code
 
__ge__(self, other)
Returns: True if the boundaries of this range are greater or equal to other, False otherwise.
source code
 
__getitem__(self, index)
Returns: The IP address(es) in this address range referenced by index/slice.
source code
 
__gt__(self, other)
Returns: True if the boundaries of this range are greater than other, False otherwise.
source code
 
__hash__(self)
Returns: The hash of this address range.
source code
 
__iadd__(self, i)
Increments start and end addresses of this range by the current size.
source code
 
__isub__(self, i)
Decrements start and end addresses of this range by the current size.
source code
 
__iter__(self)
Returns: An iterator object providing access to all network addresses within this range.
source code
 
__le__(self, other)
Returns: True if the boundaries of this range are less or equal to other, False otherwise.
source code
 
__len__(self)
Returns: The total number of network addresses in this range.
source code
 
__lt__(self, other)
Returns: True if the boundaries of this range are less than other, False otherwise.
source code
 
__ne__(self, other)
Returns: False if the boundaries of this range are the same as other, True otherwise.
source code
 
adjacent(self, other)
Returns: True if other's boundary touches the boundary of this address range, False otherwise.
source code
 
format(self, int_addr, fmt=None)
Returns: a network address in the format returned after passing it through this object's fmt property callable.
source code
 
iprange(self)
Returns: A valid IPRange object for this address range.
source code
 
issubnet(self, other)
Returns: True if other's boundary is equal to or within this range.
source code
 
issupernet(self, other)
Returns: True if other's boundary is equal to or contains this range.
source code
 
overlaps(self, other)
Returns: True if other's boundary crosses the boundary of this address range, False otherwise.
source code
 
size(self)
Returns: The total number of network addresses in this range.
source code
 
tuple(self)
Returns: A 3-element tuple (first, last, addr_type) which represent the basic details of this IPRange object.
source code
 
wildcard(self)
Returns: A Wildcard object equivalent to this CIDR.
source code
Static Methods [hide private]
 
abbrev_to_verbose(abbrev_cidr)
A static method that converts abbreviated IPv4 CIDRs to their more verbose equivalent.
source code
 
span(addrs, fmt=None)
Static method that accepts a sequence of IP addresses and/or CIDRs, Wildcards and IPRanges returning a single CIDR that is large enough to span the lowest and highest IP addresses in the sequence (with a possible overlap on either end).
source code
 
summarize(cidrs, fmt=None)
Static method that accepts a sequence of IP addresses and/or CIDRs returning a summarized sequence of merged CIDRs where possible.
source code
Class Variables [hide private]
  STRATEGIES = ST_IPV4, ST_IPV6
  ADDR_TYPES = AT_UNSPEC, AT_INET, AT_INET6
  strategy = StrategyDescriptor(STRATEGIES)
  addr_type = AddrTypeDescriptor(ADDR_TYPES)
  prefixlen = PrefixLenDescriptor('CIDR')
  fmt = FormatDescriptor(IP)
    Inherited from IPRange
  first = AddrValueDescriptor('first')
  last = AddrValueDescriptor('last')
Properties [hide private]
  network
  broadcast
Please Note: although IPv6 doesn't actually recognise the concept of broadcast addresses per se (as in IPv4), so many other libraries do this that it isn't worth trying to resist the trend just for the sake of making a theoretical point.
  netmask
  hostmask

Inherited from object: __class__

Method Details [hide private]

abbrev_to_verbose(abbrev_cidr)
Static Method

source code 

A static method that converts abbreviated IPv4 CIDRs to their more verbose equivalent.

Parameters:
  • abbrev_cidr - an abbreviated CIDR.

    Uses the old-style classful IP address rules to decide on a default subnet prefix if one is not explicitly provided.

    Only supports IPv4 addresses.

    Examples :

       10                  - 10.0.0.0/8
       10/16               - 10.0.0.0/16
       128                 - 128.0.0.0/16
       128/8               - 128.0.0.0/8
       192.168             - 192.168.0.0/16
    
Returns:
A verbose CIDR from an abbreviated CIDR or old-style classful network address, None if format provided was not recognised or supported.

span(addrs, fmt=None)
Static Method

source code 

Static method that accepts a sequence of IP addresses and/or CIDRs, Wildcards and IPRanges returning a single CIDR that is large enough to span the lowest and highest IP addresses in the sequence (with a possible overlap on either end).

Parameters:
  • addrs - a sequence of IP, CIDR, Wildcard or IPRange objects and/or their string representations.
  • fmt - (optional) callable used on return values. (Default: None - CIDR object) Also accepts str() and unicode().
Returns:
a single CIDR object spanning all addresses.

summarize(cidrs, fmt=None)
Static Method

source code 

Static method that accepts a sequence of IP addresses and/or CIDRs returning a summarized sequence of merged CIDRs where possible. This method doesn't create any CIDR that are inclusive of any addresses other than those found in the original sequence provided.

Parameters:
  • cidrs - a list or tuple of IP and/or CIDR objects.
  • fmt - callable used on return values. (Default: None - CIDR objects). str() and unicode() supported.
Returns:
a possibly smaller list of CIDRs covering sequence passed in.

__init__(self, cidr, fmt=<class 'netaddr.address.IP'>, strict=True, expand_abbrev=True)
(Constructor)

source code 

Constructor.

Parameters:
  • cidr - a valid IPv4/IPv6 CIDR address or abbreviated IPv4 network address.
  • fmt - (optional) callable used on return values. Default: IP class. See nrange() documentations for more details on the various options.
  • strict - (optional) If True and non-zero bits are found to the right of the subnet mask/prefix a ValueError is raised. If False, CIDR returned has these bits automatically truncated. (default: True)
  • expand_abbrev - (optional) If True, enables the abbreviated CIDR expansion routine. If False, abbreviated CIDRs will be considered invalid addresses, raising an AddrFormatError exception. (default: True)
Overrides: object.__init__

__sub__(self, other)
(Subtraction operator)

source code 

Subtract another CIDR from this one.

Parameters:
  • other - a CIDR object that is greater than or equal to self.
Returns:
A list of CIDR objects than remain after subtracting other from self.

__add__(self, other)
(Addition operator)

source code 

Add another CIDR to this one returning a CIDR supernet that will contain both in the smallest possible sized range.

Parameters:
  • other - a CIDR object.
Returns:
A new (potentially larger) CIDR object.

previous(self, step=1)

source code 
Parameters:
  • step - the number of CIDRs between this CIDR and the expected one. Default: 1 - the preceding CIDR.
Returns:
The immediate (adjacent) predecessor of this CIDR.

next(self, step=1)

source code 
Parameters:
  • step - the number of CIDRs between this CIDR and the expected one. Default: 1 - the succeeding CIDR.
Returns:
The immediate (adjacent) successor of this CIDR.

iter_host_addrs(self)

source code 
Returns:
An iterator object providing access to all valid host IP addresses within the specified CIDR block.
  • with IPv4 the network and broadcast addresses are always excluded. Any smaller than 4 hosts yields an emtpy list.
  • with IPv6 only the unspecified address '::' is excluded from the yielded list.

supernet(self, prefixlen=0, fmt=None)

source code 

Provides a list of supernet CIDRs for the current CIDR between the size of the current prefix and (if specified) the end CIDR prefix.

Parameters:
  • prefixlen - (optional) a CIDR prefix for the maximum supernet. Default: 0 - returns all possible supernets.
  • fmt - callable used on return values. Default: None - CIDR objects. str() and unicode() supported.
Returns:
an tuple containing CIDR supernets that contain this one.

subnet(self, prefixlen, count=None, fmt=None)

source code 

A generator that returns CIDR subnets based on the current network base address and provided CIDR prefix and count.

Parameters:
  • prefixlen - a CIDR prefix.
  • count - number of consecutive CIDRs to be returned.
  • fmt - callable used on return values. Default: None - CIDR objects. str() and unicode() supported.
Returns:
an iterator (as lists could potentially be very large) containing CIDR subnets below this CIDR's base address.

cidrs(self)

source code 
Returns:
A list of a copy of this CIDR object. This method is here mainly for compatibility with IPRange interface.
Overrides: IPRange.cidrs

__str__(self)
(Informal representation operator)

source code 

str(x)

Overrides: object.__str__
(inherited documentation)

__repr__(self)
(Representation operator)

source code 

repr(x)

Returns:
executable Python string to recreate equivalent object.
Overrides: object.__repr__

Property Details [hide private]

network

Get Method:
unreachable.network(self) - Returns: The network (first) address in this CIDR block.

broadcast

Please Note: although IPv6 doesn't actually recognise the concept of broadcast addresses per se (as in IPv4), so many other libraries do this that it isn't worth trying to resist the trend just for the sake of making a theoretical point.

Get Method:
unreachable.broadcast(self) - Please Note: although IPv6 doesn't actually recognise the concept of broadcast addresses per se (as in IPv4), so many other libraries do this that it isn't worth trying to resist the trend just for the sake of making a theoretical point.

netmask

Get Method:
unreachable.netmask(self) - Returns: The subnet mask address of this CIDR block.

hostmask

Get Method:
unreachable.hostmask(self) - Returns: The host mask address of this CIDR block.