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.