GitHub

ip_interface

API reference for ip_interface.

An address on a network, with its prefix length (Effect's IpInterface): the standard library's ipaddress.IPv4Interface / IPv6Interface, host bits kept.

from_string("192.0.2.1/24") parses strictly (an unpadded decimal prefix, Effect's address rules); a bare address takes the full-width prefix unless prefix="required". format writes address/prefix with format_ip's canonical address.

Types

TypeDefinitionDescription
IpInterfacetype IpInterface = IPv4Interface | IPv6Interface
Prefixtype Prefix = Literal['required', 'optional']
IpInterfaceInputtype IpInterfaceInput = IpInterface | str | IpInterfaceParts[IpAddressInput]
Ipv4InterfaceInputtype Ipv4InterfaceInput = IPv4Interface | str | IpInterfaceParts[Ipv4AddressInput]
Ipv6InterfaceInputtype Ipv6InterfaceInput = IPv6Interface | str | IpInterfaceParts[Ipv6AddressInput]

Classes

Functions

make

make(address: IPv4Address, prefix_length: int) -> Result[IPv4Interface, NetAddressError]
make(address: IPv6Address, prefix_length: int) -> Result[IPv6Interface, NetAddressError]
make(address: IpAddress, prefix_length: int) -> Result[IpInterface, NetAddressError]
ParameterTypeDescription
address
prefix_length
@overload
def make(address: IPv4Address, prefix_length: int) -> Result[IPv4Interface, NetAddressError]: ...
@overload
def make(address: IPv6Address, prefix_length: int) -> Result[IPv6Interface, NetAddressError]: ...
@overload
def make(address: IpAddress, prefix_length: int) -> Result[IpInterface, NetAddressError]: ...
def make(address: IpAddress, prefix_length: int) -> Result[IpInterface, NetAddressError]:
    top = width(address)
    if not 0 <= prefix_length <= top:
        return address_error(address, f"prefix length must be an integer from 0 through {top}")
    if isinstance(address, IPv4Address):
        return Ok(IPv4Interface((address, prefix_length)))
    return Ok(IPv6Interface((address, prefix_length)))

make_unsafe

make_unsafe(address: IPv4Address, prefix_length: int) -> IPv4Interface
make_unsafe(address: IPv6Address, prefix_length: int) -> IPv6Interface
make_unsafe(address: IpAddress, prefix_length: int) -> IpInterface
ParameterTypeDescription
address
prefix_length
@overload
def make_unsafe(address: IPv4Address, prefix_length: int) -> IPv4Interface: ...
@overload
def make_unsafe(address: IPv6Address, prefix_length: int) -> IPv6Interface: ...
@overload
def make_unsafe(address: IpAddress, prefix_length: int) -> IpInterface: ...
def make_unsafe(address: IpAddress, prefix_length: int) -> IpInterface:
    return make(address, prefix_length).get_or_raise()

split_prefix

split_prefix(text: str, prefix: Literal['required']) -> Result[tuple[str, int], NetAddressError]
split_prefix(text: str, prefix: Prefix) -> Result[tuple[str, int | None], NetAddressError]

address/prefix split; the prefix None when optional and absent.

ParameterTypeDescription
text
prefix
@overload
def split_prefix(
    text: str, prefix: Literal["required"]
) -> Result[tuple[str, int], NetAddressError]: ...
@overload
def split_prefix(text: str, prefix: Prefix) -> Result[tuple[str, int | None], NetAddressError]: ...
def split_prefix(text: str, prefix: Prefix) -> Result[tuple[str, int | None], NetAddressError]:
    """``address/prefix`` split; the prefix ``None`` when optional and
    absent."""
    slash = text.find("/")
    if slash == -1 and prefix != "required":
        return Ok((text, None))
    if slash <= 0 or slash != text.rfind("/") or slash == len(text) - 1:
        return address_error(text, "expected an address and prefix length separated by one slash")
    digits = text[slash + 1 :]
    length = parse_digits(digits, unpadded=True)
    if length is None:
        return address_error(text, "prefix length must be an unpadded ASCII decimal integer")
    return Ok((text[:slash], length))

ipv4_from_string

ipv4_from_string(text, *, prefix='optional') -> Result[IPv4Interface, NetAddressError]
ParameterTypeDescription
textstr
prefixPrefix = 'optional'

Returns Result[IPv4Interface, NetAddressError]

def ipv4_from_string(
    text: str, *, prefix: Prefix = "optional"
) -> Result[IPv4Interface, NetAddressError]:
    return _parse(text, prefix, parse_ipv4).flat_map(lambda p: make(p[0], p[1]))

ipv6_from_string

ipv6_from_string(text, *, prefix='optional') -> Result[IPv6Interface, NetAddressError]
ParameterTypeDescription
textstr
prefixPrefix = 'optional'

Returns Result[IPv6Interface, NetAddressError]

def ipv6_from_string(
    text: str, *, prefix: Prefix = "optional"
) -> Result[IPv6Interface, NetAddressError]:
    return _parse(text, prefix, parse_ipv6).flat_map(lambda p: make(p[0], p[1]))

from_string

from_string(text, *, prefix='optional') -> Result[IpInterface, NetAddressError]
ParameterTypeDescription
textstr
prefixPrefix = 'optional'

Returns Result[IpInterface, NetAddressError]

def from_string(text: str, *, prefix: Prefix = "optional") -> Result[IpInterface, NetAddressError]:
    return _parse(text, prefix, ip_from_string).flat_map(lambda p: make(p[0], p[1]))

from_string_unsafe

from_string_unsafe(text, *, prefix='optional') -> IpInterface
ParameterTypeDescription
textstr
prefixPrefix = 'optional'

Returns IpInterface

def from_string_unsafe(text: str, *, prefix: Prefix = "optional") -> IpInterface:
    return from_string(text, prefix=prefix).get_or_raise()

from_input

from_input(value, *, prefix='optional') -> Result[IpInterface, NetAddressError]
ParameterTypeDescription
valueIpInterfaceInput
prefixPrefix = 'optional'

Returns Result[IpInterface, NetAddressError]

def from_input(
    value: IpInterfaceInput, *, prefix: Prefix = "optional"
) -> Result[IpInterface, NetAddressError]:
    match value:
        case IPv4Interface() | IPv6Interface():
            return Ok(value)
        case str():
            return from_string(value, prefix=prefix)
        case _:
            return _parts(value, ip_from_input).flat_map(lambda p: make(p[0], p[1]))

from_input_unsafe

from_input_unsafe(value, *, prefix='optional') -> IpInterface
ParameterTypeDescription
valueIpInterfaceInput
prefixPrefix = 'optional'

Returns IpInterface

def from_input_unsafe(value: IpInterfaceInput, *, prefix: Prefix = "optional") -> IpInterface:
    return from_input(value, prefix=prefix).get_or_raise()

ipv4_from_input

ipv4_from_input(value, *, prefix='optional') -> Result[IPv4Interface, NetAddressError]
ParameterTypeDescription
valueIpv4InterfaceInput
prefixPrefix = 'optional'

Returns Result[IPv4Interface, NetAddressError]

def ipv4_from_input(
    value: Ipv4InterfaceInput, *, prefix: Prefix = "optional"
) -> Result[IPv4Interface, NetAddressError]:
    match value:
        case IPv4Interface():
            return Ok(value)
        case str():
            return ipv4_from_string(value, prefix=prefix)
        case _:
            return _parts(value, ipv4_address_from_input).flat_map(lambda p: make(p[0], p[1]))

ipv6_from_input

ipv6_from_input(value, *, prefix='optional') -> Result[IPv6Interface, NetAddressError]
ParameterTypeDescription
valueIpv6InterfaceInput
prefixPrefix = 'optional'

Returns Result[IPv6Interface, NetAddressError]

def ipv6_from_input(
    value: Ipv6InterfaceInput, *, prefix: Prefix = "optional"
) -> Result[IPv6Interface, NetAddressError]:
    match value:
        case IPv6Interface():
            return Ok(value)
        case str():
            return ipv6_from_string(value, prefix=prefix)
        case _:
            return _parts(value, ipv6_address_from_input).flat_map(lambda p: make(p[0], p[1]))

format

format(interface) -> str

address/prefix with the canonical address text.

ParameterTypeDescription
interfaceIpInterface

Returns str

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