Package netaddr :: Module address :: Class CIDR |
[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
__init__(self, cidr, fmt=<class 'netaddr.address.IP'>, strict=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
iter_host_addrs(self) @return: An iterator object providing access to all valid host IP addresses within the specified CIDR block. | 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 `IPRange`: `__contains__`, `__eq__`, `__ge__`, `__getitem__`, `__gt__`, `__hash__`, `__iadd__`, `__isub__`, `__iter__`, `__le__`, `__len__`, `__lt__`, `__ne__`, `adjacent`, `format`, `iprange`, `issubnet`, `issupernet`, `overlaps`, `size`, `wildcard` Inherited from `object`: `__delattr__`, `__getattribute__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`

Static Methods
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

Class Variables
| 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`, `last`

Properties
| network
| broadcast Please Note: although IPv6 doesn't actually recognise the concept of a 'broadcast' address as the last address in a subnet (as in IPv4) so many other libraries do this that it isn't worth trying to resist.
| netmask
| hostmask
Inherited from `object`: `__class__`

Method Details

### 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.

### __init__(self, cidr, fmt=<class 'netaddr.address.IP'>, strict=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) performs a test to ensure there are no non-zero bits to the right of the subnet mask or prefix when it is applied to the base address. (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.

### iter_host_addrs(self) | source code
    @return: 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.

### 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

### 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 a 'broadcast' address as the last address in a subnet (as in IPv4) so many other libraries do this that it isn't worth trying to resist. This issue raises so many user queries that it is easier to dispense with the theory and be pragmatic instead. Get Method: unreachable.broadcast(self) - Please Note: although IPv6 doesn't actually recognise the concept of a 'broadcast' address as the last address in a subnet (as in IPv4) so many other libraries do this that it isn't worth trying to resist.

### 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.