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#
| Attribute | Type | Description |
|---|---|---|
DomainName | type[DomainName] | A validated, lowercase ASCII domain name; a trailing dot makes it fully
qualified, |
Types#
| Type | Definition | Description |
|---|---|---|
DomainNameInput | type DomainNameInput = DomainName | str | |
Host | type Host = IpAddress | ScopedIpv6Literal | DomainName | |
HostInput | type HostInput = Host | IpAddressInput | |
HostPortInput | type HostPortInput = HostPort | str | HostPortParts | |
HostsTable | type HostsTable = Mapping[DomainName, tuple[IpAddress, ...]] |
Classes#
Functions#
is_domain_name#
is_domain_name(value) -> boolWhether value is already a normalized domain name.
| Parameter | Type | Description |
|---|---|---|
value | object |
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| Parameter | Type | Description |
|---|---|---|
value | object |
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]| Parameter | Type | Description |
|---|---|---|
text | str |
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| Parameter | Type | Description |
|---|---|---|
text | str |
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]| Parameter | Type | Description |
|---|---|---|
value | DomainNameInput |
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| Parameter | Type | Description |
|---|---|---|
value | DomainNameInput |
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.
| Parameter | Type | Description |
|---|---|---|
text | str |
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| Parameter | Type | Description |
|---|---|---|
text | str |
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]| Parameter | Type | Description |
|---|---|---|
value | HostInput |
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| Parameter | Type | Description |
|---|---|---|
value | HostInput |
Returns Host
def host_from_input_unsafe(value: HostInput) -> Host:
return host_from_input(value).get_or_raise()format_host#
format_host(host) -> str| Parameter | Type | Description |
|---|---|---|
host | Host |
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| Parameter | Type | Description |
|---|---|---|
name | DomainName |
Returns bool
def is_fully_qualified(name: DomainName) -> bool:
return name.endswith(".")to_fully_qualified#
to_fully_qualified(name) -> DomainName| Parameter | Type | Description |
|---|---|---|
name | DomainName |
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| Parameter | Type | Description |
|---|---|---|
name | DomainName |
Returns DomainName
def to_relative(name: DomainName) -> DomainName:
return DomainName(name[:-1]) if len(name) > 1 and is_fully_qualified(name) else namehost_port#
host_port(host, port) -> Result[HostPort, NetAddressError]| Parameter | Type | Description |
|---|---|---|
host | Host | |
port | int |
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| Parameter | Type | Description |
|---|---|---|
host | Host | |
port | int |
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]| Parameter | Type | Description |
|---|---|---|
text | str |
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| Parameter | Type | Description |
|---|---|---|
text | str |
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": ...}.
| Parameter | Type | Description |
|---|---|---|
value | HostPortInput |
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| Parameter | Type | Description |
|---|---|---|
value | HostPortInput |
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| Parameter | Type | Description |
|---|---|---|
endpoint | HostPort |
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) -> HostsTableA hosts file's addresses by relative name, in file order; lines and names that do not parse are skipped.
| Parameter | Type | Description |
|---|---|---|
text | str |
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()}On This Page
ValuesTypesClassesFunctionsis_domain_nameis_hostdomain_name_from_stringdomain_name_from_string_unsafedomain_name_from_inputdomain_name_from_input_unsafehost_from_stringhost_from_string_unsafehost_from_inputhost_from_input_unsafeformat_hostis_fully_qualifiedto_fully_qualifiedto_relativehost_porthost_port_unsafehost_port_from_stringhost_port_from_string_unsafehost_port_from_inputhost_port_from_input_unsafeformat_host_portparse_hosts_file