GitHub

API reference for host.

Host names and endpoints (Effect's Host).

A host is an IP address, a scoped IPv6 literal (fe80::1%eth0) or a DomainName: lowercase ASCII, internationalized labels converted to their xn-- form, an optional trailing dot. HostPort pairs a host with a port::

host.host_port_from_string("DB.internal:5432")   # Ok(HostPort("db.internal", 5432))
host.format_host_port(endpoint)                   # "db.internal:5432"

Values

AttributeTypeDescription
DomainNametype[DomainName]

A validated, lowercase ASCII domain name; a trailing dot makes it fully qualified, "." is the root.

Types

TypeDefinitionDescription
DomainNameInputtype DomainNameInput = DomainName | str
Hosttype Host = IpAddress | ScopedIpv6Literal | DomainName
HostInputtype HostInput = Host | IpAddressInput
HostPortInputtype HostPortInput = HostPort | str | HostPortParts
HostsTabletype HostsTable = Mapping[DomainName, tuple[IpAddress, ...]]

Classes

Functions

is_domain_name

is_domain_name(value) -> bool

Whether value is already a normalized domain name.

ParameterTypeDescription
valueobject

Returns bool

def is_domain_name(value: object) -> bool:
    """Whether ``value`` is already a normalized domain name."""
    return (
        isinstance(value, str) and bool(_DOMAIN_TEXT.fullmatch(value)) and _validate(value) is None
    )

is_host

is_host(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_host(value: object) -> bool:
    return (
        isinstance(value, (IPv4Address, IPv6Address))
        or is_scoped_ipv6_literal(value)
        or is_domain_name(value)
    )

domain_name_from_string

domain_name_from_string(text) -> Result[DomainName, NetAddressError]
ParameterTypeDescription
textstr

Returns Result[DomainName, NetAddressError]

def domain_name_from_string(text: str) -> Result[DomainName, NetAddressError]:
    name = _to_ascii(text)
    if name is None:
        return address_error(text, "invalid domain name")
    error = _validate(name)
    return Ok(DomainName(name)) if error is None else address_error(text, error)

domain_name_from_string_unsafe

domain_name_from_string_unsafe(text) -> DomainName
ParameterTypeDescription
textstr

Returns DomainName

def domain_name_from_string_unsafe(text: str) -> DomainName:
    return domain_name_from_string(text).get_or_raise()

domain_name_from_input

domain_name_from_input(value) -> Result[DomainName, NetAddressError]
ParameterTypeDescription
valueDomainNameInput

Returns Result[DomainName, NetAddressError]

def domain_name_from_input(value: DomainNameInput) -> Result[DomainName, NetAddressError]:
    return domain_name_from_string(value)

domain_name_from_input_unsafe

domain_name_from_input_unsafe(value) -> DomainName
ParameterTypeDescription
valueDomainNameInput

Returns DomainName

def domain_name_from_input_unsafe(value: DomainNameInput) -> DomainName:
    return domain_name_from_input(value).get_or_raise()

host_from_string

host_from_string(text) -> Result[Host, NetAddressError]

A scoped IPv6 literal, an IP address or a domain name, by its text.

ParameterTypeDescription
textstr

Returns Result[Host, NetAddressError]

def host_from_string(text: str) -> Result[Host, NetAddressError]:
    """A scoped IPv6 literal, an IP address or a domain name, by its text."""
    if "%" in text:
        scoped: Result[Host, NetAddressError] = scoped_ipv6_literal_from_string(text)
        return scoped
    if ":" in text:
        return ip_from_string(text)
    if _NUMERIC_HOST.fullmatch(text):
        address = ip_from_string(text)
        if isinstance(address, Ok):
            return address
    return domain_name_from_string(text)

host_from_string_unsafe

host_from_string_unsafe(text) -> Host
ParameterTypeDescription
textstr

Returns Host

def host_from_string_unsafe(text: str) -> Host:
    return host_from_string(text).get_or_raise()

host_from_input

host_from_input(value) -> Result[Host, NetAddressError]
ParameterTypeDescription
valueHostInput

Returns Result[Host, NetAddressError]

def host_from_input(value: HostInput) -> Result[Host, NetAddressError]:
    if isinstance(value, str):
        return host_from_string(value)
    return ip_from_input(value)

host_from_input_unsafe

host_from_input_unsafe(value) -> Host
ParameterTypeDescription
valueHostInput

Returns Host

def host_from_input_unsafe(value: HostInput) -> Host:
    return host_from_input(value).get_or_raise()

format_host

format_host(host) -> str
ParameterTypeDescription
hostHost

Returns str

def format_host(host: Host) -> str:
    return host if isinstance(host, str) else format_ip(host)

is_fully_qualified

is_fully_qualified(name) -> bool
ParameterTypeDescription
nameDomainName

Returns bool

def is_fully_qualified(name: DomainName) -> bool:
    return name.endswith(".")

to_fully_qualified

to_fully_qualified(name) -> DomainName
ParameterTypeDescription
nameDomainName

Returns DomainName

def to_fully_qualified(name: DomainName) -> DomainName:
    return name if is_fully_qualified(name) else DomainName(f"{name}.")

to_relative

to_relative(name) -> DomainName
ParameterTypeDescription
nameDomainName

Returns DomainName

def to_relative(name: DomainName) -> DomainName:
    return DomainName(name[:-1]) if len(name) > 1 and is_fully_qualified(name) else name

host_port

host_port(host, port) -> Result[HostPort, NetAddressError]
ParameterTypeDescription
hostHost
portint

Returns Result[HostPort, NetAddressError]

def host_port(host: Host, port: int) -> Result[HostPort, NetAddressError]:
    if not is_host(host):
        return address_error(host, "expected a host")
    if not _is_port(port):
        return address_error(port, "port must be an integer from 0 through 65535")
    return Ok(HostPort(host, port))

host_port_unsafe

host_port_unsafe(host, port) -> HostPort
ParameterTypeDescription
hostHost
portint

Returns HostPort

def host_port_unsafe(host: Host, port: int) -> HostPort:
    return host_port(host, port).get_or_raise()

host_port_from_string

host_port_from_string(text) -> Result[HostPort, NetAddressError]
ParameterTypeDescription
textstr

Returns Result[HostPort, NetAddressError]

def host_port_from_string(text: str) -> Result[HostPort, NetAddressError]:  # noqa: PLR0911
    if text.startswith("["):
        end = text.find("]")
        if end == -1 or text[end + 1 : end + 2] != ":":
            return address_error(text, "expected [IPv6]:port")
        host_text, port_text = text[1:end], text[end + 2 :]
        if ":" not in host_text:
            return address_error(text, "only IPv6 addresses use brackets")
    else:
        separator = text.rfind(":")
        if separator == -1:
            return address_error(text, "expected host:port")
        if text.find(":") != separator:
            return address_error(text, "IPv6 addresses must be bracketed")
        host_text, port_text = text[:separator], text[separator + 1 :]
    port = parse_digits(port_text, unpadded=True)
    if port is None:
        return address_error(text, "port must be an unpadded decimal integer")
    if not _is_port(port):
        return address_error(text, "port must be an integer from 0 through 65535")
    return host_from_string(host_text).map(lambda host: HostPort(host, port))

host_port_from_string_unsafe

host_port_from_string_unsafe(text) -> HostPort
ParameterTypeDescription
textstr

Returns HostPort

def host_port_from_string_unsafe(text: str) -> HostPort:
    return host_port_from_string(text).get_or_raise()

host_port_from_input

host_port_from_input(value) -> Result[HostPort, NetAddressError]

An endpoint, its text, or {"host": ..., "port": ...}.

ParameterTypeDescription
valueHostPortInput

Returns Result[HostPort, NetAddressError]

def host_port_from_input(value: HostPortInput) -> Result[HostPort, NetAddressError]:
    """An endpoint, its text, or ``{"host": ..., "port": ...}``."""
    if isinstance(value, HostPort):
        return Ok(value)
    if isinstance(value, str):
        return host_port_from_string(value)
    port = value["port"]
    return host_from_input(value["host"]).flat_map(lambda host: host_port(host, port))

host_port_from_input_unsafe

host_port_from_input_unsafe(value) -> HostPort
ParameterTypeDescription
valueHostPortInput

Returns HostPort

def host_port_from_input_unsafe(value: HostPortInput) -> HostPort:
    return host_port_from_input(value).get_or_raise()

format_host_port

format_host_port(endpoint) -> str
ParameterTypeDescription
endpointHostPort

Returns str

def format_host_port(endpoint: HostPort) -> str:
    host = format_host(endpoint.host)
    return f"[{host}]:{endpoint.port}" if ":" in host else f"{host}:{endpoint.port}"

parse_hosts_file

parse_hosts_file(text) -> HostsTable

A hosts file's addresses by relative name, in file order; lines and names that do not parse are skipped.

ParameterTypeDescription
textstr

Returns HostsTable

def parse_hosts_file(text: str) -> HostsTable:
    """A hosts file's addresses by relative name, in file order; lines and
    names that do not parse are skipped."""
    hosts: dict[DomainName, list[IpAddress]] = {}
    for line in re.split(r"\r?\n", text):
        fields = line.partition("#")[0].split()
        if not fields:
            continue
        address = ip_from_string(fields[0])
        if not isinstance(address, Ok):
            continue
        for name in fields[1:]:
            domain = domain_name_from_string(name)
            if not isinstance(domain, Ok):
                continue
            addresses = hosts.setdefault(to_relative(domain.value), [])
            if address.value not in addresses:
                addresses.append(address.value)
    return {name: tuple(addresses) for name, addresses in hosts.items()}