GitHub

ip_network

API reference for ip_network.

CIDR networks (Effect's IpNetwork): the standard library's ipaddress.IPv4Network / IPv6Network, always canonical (no host bits).

make rejects an address with host bits; from_address clears them. from_string parses strict CIDR text. first_address, last_address, address_count, contains, contains_network and overlaps compare only networks of one family; across families they are False.

Re-exports

Types

TypeDefinitionDescription
IpNetworktype IpNetwork = IPv4Network | IPv6Network
IpNetworkPartstype IpNetworkParts[A = IpAddressInput] = IpInterfaceParts[A]
IpNetworkInputtype IpNetworkInput = IpNetwork | str | IpInterfaceParts[IpAddressInput]
Ipv4NetworkInputtype Ipv4NetworkInput = IPv4Network | str | IpInterfaceParts[Ipv4AddressInput]
Ipv6NetworkInputtype Ipv6NetworkInput = IPv6Network | str | IpInterfaceParts[Ipv6AddressInput]

Functions

make

make(address: IPv4Address, prefix_length: int) -> Result[IPv4Network, NetAddressError]
make(address: IPv6Address, prefix_length: int) -> Result[IPv6Network, NetAddressError]
make(address: IpAddress, prefix_length: int) -> Result[IpNetwork, NetAddressError]

The network address/prefix_length; an address with host bits set is rejected.

ParameterTypeDescription
address
prefix_length
@overload
def make(address: IPv4Address, prefix_length: int) -> Result[IPv4Network, NetAddressError]: ...
@overload
def make(address: IPv6Address, prefix_length: int) -> Result[IPv6Network, NetAddressError]: ...
@overload
def make(address: IpAddress, prefix_length: int) -> Result[IpNetwork, NetAddressError]: ...
def make(address: IpAddress, prefix_length: int) -> Result[IpNetwork, NetAddressError]:
    """The network ``address/prefix_length``; an address with host bits set
    is rejected."""

    def check(value: IpInterface) -> Result[IpNetwork, NetAddressError]:
        network = _network(address, value.network.prefixlen)
        if network.network_address != address:
            return address_error(address, "address has non-zero host bits")
        return Ok(network)

    return ip_interface.make(address, prefix_length).flat_map(check)

make_unsafe

make_unsafe(address: IPv4Address, prefix_length: int) -> IPv4Network
make_unsafe(address: IPv6Address, prefix_length: int) -> IPv6Network
make_unsafe(address: IpAddress, prefix_length: int) -> IpNetwork
ParameterTypeDescription
address
prefix_length
@overload
def make_unsafe(address: IPv4Address, prefix_length: int) -> IPv4Network: ...
@overload
def make_unsafe(address: IPv6Address, prefix_length: int) -> IPv6Network: ...
@overload
def make_unsafe(address: IpAddress, prefix_length: int) -> IpNetwork: ...
def make_unsafe(address: IpAddress, prefix_length: int) -> IpNetwork:
    return make(address, prefix_length).get_or_raise()

from_address

from_address(address: IPv4Address, prefix_length: int) -> Result[IPv4Network, NetAddressError]
from_address(address: IPv6Address, prefix_length: int) -> Result[IPv6Network, NetAddressError]
from_address(address: IpAddress, prefix_length: int) -> Result[IpNetwork, NetAddressError]

The network containing address with prefix_length: host bits cleared.

ParameterTypeDescription
address
prefix_length
@overload
def from_address(
    address: IPv4Address, prefix_length: int
) -> Result[IPv4Network, NetAddressError]: ...
@overload
def from_address(
    address: IPv6Address, prefix_length: int
) -> Result[IPv6Network, NetAddressError]: ...
@overload
def from_address(address: IpAddress, prefix_length: int) -> Result[IpNetwork, NetAddressError]: ...
def from_address(address: IpAddress, prefix_length: int) -> Result[IpNetwork, NetAddressError]:
    """The network containing ``address`` with ``prefix_length``: host bits
    cleared."""
    return ip_interface.make(address, prefix_length).map(
        lambda value: _network(address, value.network.prefixlen)
    )

from_address_unsafe

from_address_unsafe(address: IPv4Address, prefix_length: int) -> IPv4Network
from_address_unsafe(address: IPv6Address, prefix_length: int) -> IPv6Network
from_address_unsafe(address: IpAddress, prefix_length: int) -> IpNetwork
ParameterTypeDescription
address
prefix_length
@overload
def from_address_unsafe(address: IPv4Address, prefix_length: int) -> IPv4Network: ...
@overload
def from_address_unsafe(address: IPv6Address, prefix_length: int) -> IPv6Network: ...
@overload
def from_address_unsafe(address: IpAddress, prefix_length: int) -> IpNetwork: ...
def from_address_unsafe(address: IpAddress, prefix_length: int) -> IpNetwork:
    return from_address(address, prefix_length).get_or_raise()

from_interface

from_interface(interface) -> IpNetwork

The canonical network an interface address is on.

ParameterTypeDescription
interfaceIpInterface

Returns IpNetwork

def from_interface(interface: IpInterface) -> IpNetwork:
    """The canonical network an interface address is on."""
    return interface.network

ipv4_from_string

ipv4_from_string(text) -> Result[IPv4Network, NetAddressError]
ParameterTypeDescription
textstr

Returns Result[IPv4Network, NetAddressError]

def ipv4_from_string(text: str) -> Result[IPv4Network, NetAddressError]:
    return _parse(text, parse_ipv4).flat_map(lambda p: make(p[0], p[1]))

ipv6_from_string

ipv6_from_string(text) -> Result[IPv6Network, NetAddressError]
ParameterTypeDescription
textstr

Returns Result[IPv6Network, NetAddressError]

def ipv6_from_string(text: str) -> Result[IPv6Network, NetAddressError]:
    return _parse(text, parse_ipv6).flat_map(lambda p: make(p[0], p[1]))

from_string

from_string(text) -> Result[IpNetwork, NetAddressError]

Strict CIDR: address/prefix with no host bits.

ParameterTypeDescription
textstr

Returns Result[IpNetwork, NetAddressError]

def from_string(text: str) -> Result[IpNetwork, NetAddressError]:
    """Strict CIDR: ``address/prefix`` with no host bits."""
    return _parse(text, ip_from_string).flat_map(lambda p: make(p[0], p[1]))

from_string_unsafe

from_string_unsafe(text) -> IpNetwork
ParameterTypeDescription
textstr

Returns IpNetwork

def from_string_unsafe(text: str) -> IpNetwork:
    return from_string(text).get_or_raise()

from_input

from_input(value) -> Result[IpNetwork, NetAddressError]
ParameterTypeDescription
valueIpNetworkInput

Returns Result[IpNetwork, NetAddressError]

def from_input(value: IpNetworkInput) -> Result[IpNetwork, NetAddressError]:
    match value:
        case IPv4Network() | IPv6Network():
            return Ok(value)
        case str():
            return from_string(value)
        case _:
            return _parts(value, ip_from_input).flat_map(lambda p: make(p[0], p[1]))

from_input_unsafe

from_input_unsafe(value) -> IpNetwork
ParameterTypeDescription
valueIpNetworkInput

Returns IpNetwork

def from_input_unsafe(value: IpNetworkInput) -> IpNetwork:
    return from_input(value).get_or_raise()

ipv4_from_input

ipv4_from_input(value) -> Result[IPv4Network, NetAddressError]
ParameterTypeDescription
valueIpv4NetworkInput

Returns Result[IPv4Network, NetAddressError]

def ipv4_from_input(value: Ipv4NetworkInput) -> Result[IPv4Network, NetAddressError]:
    match value:
        case IPv4Network():
            return Ok(value)
        case str():
            return ipv4_from_string(value)
        case _:
            return _parts(value, ipv4_address_from_input).flat_map(lambda p: make(p[0], p[1]))

ipv6_from_input

ipv6_from_input(value) -> Result[IPv6Network, NetAddressError]
ParameterTypeDescription
valueIpv6NetworkInput

Returns Result[IPv6Network, NetAddressError]

def ipv6_from_input(value: Ipv6NetworkInput) -> Result[IPv6Network, NetAddressError]:
    match value:
        case IPv6Network():
            return Ok(value)
        case str():
            return ipv6_from_string(value)
        case _:
            return _parts(value, ipv6_address_from_input).flat_map(lambda p: make(p[0], p[1]))

format

format(network) -> str

address/prefix with the canonical address text.

ParameterTypeDescription
networkIpNetwork

Returns str

def format(network: IpNetwork) -> str:
    """``address/prefix`` with the canonical address text."""
    return f"{format_ip(network.network_address)}/{network.prefixlen}"

first_address

first_address(network: IPv4Network) -> IPv4Address
first_address(network: IPv6Network) -> IPv6Address
ParameterTypeDescription
network
@overload
def first_address(network: IPv4Network) -> IPv4Address: ...
@overload
def first_address(network: IPv6Network) -> IPv6Address: ...
def first_address(network: IpNetwork) -> IpAddress:
    return network.network_address

last_address

last_address(network: IPv4Network) -> IPv4Address
last_address(network: IPv6Network) -> IPv6Address
ParameterTypeDescription
network
@overload
def last_address(network: IPv4Network) -> IPv4Address: ...
@overload
def last_address(network: IPv6Network) -> IPv6Address: ...
def last_address(network: IpNetwork) -> IpAddress:
    return network.broadcast_address

address_count

address_count(network) -> int
ParameterTypeDescription
networkIpNetwork

Returns int

def address_count(network: IpNetwork) -> int:
    return network.num_addresses

contains

contains(network, address) -> bool

Whether address is in network (never across families).

ParameterTypeDescription
networkIpNetwork
addressIpAddress

Returns bool

def contains(network: IpNetwork, address: IpAddress) -> bool:
    """Whether ``address`` is in ``network`` (never across families)."""
    return network.version == address.version and address in network

contains_network

contains_network(network, other) -> bool

Whether every address of other is in network.

ParameterTypeDescription
networkIpNetwork
otherIpNetwork

Returns bool

def contains_network(network: IpNetwork, other: IpNetwork) -> bool:
    """Whether every address of ``other`` is in ``network``."""
    return network.prefixlen <= other.prefixlen and contains(network, other.network_address)

overlaps

overlaps(network, other) -> bool

Whether the two networks share an address.

ParameterTypeDescription
networkIpNetwork
otherIpNetwork

Returns bool

def overlaps(network: IpNetwork, other: IpNetwork) -> bool:
    """Whether the two networks share an address."""
    if network.prefixlen <= other.prefixlen:
        return contains(network, other.network_address)
    return contains(other, network.network_address)