GitHub

DnsService

API reference for DnsService.

Host lookups, record queries and reverse lookups. Every result is non-empty and without duplicates; an empty answer fails with NotFound, a name that does not parse with BadName.

Functions

__init__

__init__(_lookup, _resolve, _reverse) -> None
ParameterTypeDescription
_lookupLookup
_resolveResolve
_reverseReverse

lookup

lookup(host: DomainNameInput, *, family: Literal['IPv4']) -> Effect[tuple[IPv4Address, ...], DnsError]
lookup(host: DomainNameInput, *, family: Literal['IPv6']) -> Effect[tuple[IPv6Address, ...], DnsError]
lookup(host: DomainNameInput, *, family: IpFamily | None = None) -> Effect[tuple[IpAddress, ...], DnsError]

The addresses of host, of family when given.

ParameterTypeDescription
host
family= None
@overload
def lookup(
    self, host: DomainNameInput, *, family: Literal["IPv4"]
) -> Effect[tuple[IPv4Address, ...], DnsError]: ...
@overload
def lookup(
    self, host: DomainNameInput, *, family: Literal["IPv6"]
) -> Effect[tuple[IPv6Address, ...], DnsError]: ...
@overload
def lookup(
    self, host: DomainNameInput, *, family: IpFamily | None = None
) -> Effect[tuple[IpAddress, ...], DnsError]: ...
def lookup(
    self, host: DomainNameInput, *, family: IpFamily | None = None
) -> Effect[tuple[IpAddress, ...], DnsError]:
    """The addresses of ``host``, of ``family`` when given."""
    match domain_name_from_input(host):
        case Err(error):
            return fail(DnsError("BadName", "lookup", host, cause=error))
        case Ok(name):
            pass

    def found(addresses: Sequence[IpAddress]) -> Effect[tuple[IpAddress, ...], DnsError]:
        kept = _dedupe(a for a in addresses if family is None or family_of(a) == family)
        return succeed(kept) if kept else fail(_not_found("lookup", name))

    return self._lookup(name, family).flat_map(found)

resolve

resolve[R: DnsRecord](name, record_type) -> Effect[tuple[R, ...], DnsError]

The records of record_type (a record class: dns.Mx) at name.

ParameterTypeDescription
nameDomainNameInput
record_typetype[R]

Returns Effect[tuple[R, ...], DnsError]

def resolve[R: DnsRecord](
    self, name: DomainNameInput, record_type: type[R]
) -> Effect[tuple[R, ...], DnsError]:
    """The records of ``record_type`` (a record class: ``dns.Mx``) at
    ``name``."""
    tag = record_type.tag
    match domain_name_from_input(name):
        case Err(error):
            return fail(DnsError("BadName", "resolve", name, tag, error))
        case Ok(domain):
            pass

    def found(records: Sequence[DnsRecord]) -> Effect[tuple[R, ...], DnsError]:
        kept = _dedupe(r for r in records if isinstance(r, record_type))
        return succeed(kept) if kept else fail(_not_found("resolve", domain, tag))

    return self._resolve(domain, tag).flat_map(found)

reverse

reverse(address) -> Effect[tuple[DomainName, ...], DnsError]

The names of address; only ASCII names are kept (a UTF-8 name would become a different xn-- name).

ParameterTypeDescription
addressIpAddressInput

Returns Effect[tuple[DomainName, ...], DnsError]

def reverse(self, address: IpAddressInput) -> Effect[tuple[DomainName, ...], DnsError]:
    """The names of ``address``; only ASCII names are kept (a UTF-8 name
    would become a different ``xn--`` name)."""
    match ip_from_input(address):
        case Err(error):
            return fail(DnsError("BadName", "reverse", str(address), cause=error))
        case Ok(ip):
            pass
    hostname = format_ip(ip)

    def found(names: Sequence[str]) -> Effect[tuple[DomainName, ...], DnsError]:
        hosts = _dedupe(
            parsed.value
            for name in names
            if _ASCII_NAME.fullmatch(name)
            for parsed in (domain_name_from_input(name),)
            if isinstance(parsed, Ok)
        )
        if hosts:
            return succeed(hosts)
        if names:
            return fail(DnsError("InvalidResponse", "reverse", hostname))
        return fail(_not_found("reverse", hostname))

    return self._reverse(ip).flat_map(found)