GitHub

API reference for dns.

DNS (Effect's Dns): the Dns service, its records and errors.

Dns looks up hosts, queries records by class and reverse-resolves addresses::

dns = yield from Dns()
mail = yield from dns.resolve("example.com", Mx)   # tuple[Mx, ...]

make builds the service from a lookup (and optionally a resolver and reverse lookup); layer_static answers from a fixed zone, for tests; layer_system asks the operating system. Records are validated frozen dataclasses; make_record builds one as a Result.

Values

AttributeTypeDescription
record_classestuple[type[DnsRecord], ...]
record_typestuple[RecordType, ...]

Types

TypeDefinitionDescription
DnsErrorReasontype DnsErrorReason = Literal['NotFound', 'Timeout', 'Temporary', 'Refused', 'ServerFailure', 'BadName', 'InvalidResponse', 'Unsupported', 'Unknown']
DnsMethodtype DnsMethod = Literal['lookup', 'resolve', 'reverse']
DnsRecordtype DnsRecord = A | Aaaa | Caa | Cname | Mx | Naptr | Ns | Ptr | Soa | Srv | Tlsa | Txt
RecordTypetype RecordType = Literal['A', 'AAAA', 'CAA', 'CNAME', 'MX', 'NAPTR', 'NS', 'PTR', 'SOA', 'SRV', 'TLSA', 'TXT']
Lookuptype Lookup = Callable[[DomainName, IpFamily | None], Effect[Sequence[IpAddress], DnsError]]
Resolvetype Resolve = Callable[[DomainName, RecordType], Effect[Sequence[DnsRecord], DnsError]]
Reversetype Reverse = Callable[[IpAddress], Effect[Sequence[str], DnsError]]

Classes

Functions

format_record

format_record(record) -> str

The record in DNS presentation format (MX 10 mail.example.com).

ParameterTypeDescription
recordDnsRecord

Returns str

def format_record(record: DnsRecord) -> str:  # noqa: PLR0911
    """The record in DNS presentation format (``MX 10 mail.example.com``)."""
    match record:
        case A() | Aaaa():
            return f"{record.tag} {format_ip(record.address)}"
        case Caa():
            return f"CAA {128 if record.critical else 0} {record.tag_name} {_quote(record.value)}"
        case Cname():
            return f"CNAME {record.target}"
        case Mx():
            return f"MX {record.priority} {record.exchange}"
        case Naptr():
            return (
                f"NAPTR {record.order} {record.preference} {_quote(record.flags)} "
                f"{_quote(record.service)} {_quote(record.regexp)} {record.replacement}"
            )
        case Ns():
            return f"NS {record.host}"
        case Ptr():
            return f"PTR {_format_name(record.host)}"
        case Soa():
            timers = " ".join(
                _seconds(t) for t in (record.refresh, record.retry, record.expire, record.minimum)
            )
            return f"SOA {record.primary} {_format_name(record.admin)} {record.serial} {timers}"
        case Srv():
            return f"SRV {record.priority} {record.weight} {record.port} {record.target}"
        case Tlsa():
            return (
                f"TLSA {record.cert_usage} {record.selector} {record.matching_type} "
                f"{record.data.hex().upper()}"
            )
        case Txt():
            return "TXT " + " ".join(_quote(chunk) for chunk in record.chunks)

is_record_type

is_record_type(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_record_type(value: object) -> bool:
    return value in record_types

make_record

make_record[R: DnsRecord](record_type, **fields) -> Result[R, NetAddressError]

Build a record, as its constructor does, giving the rejection as an Err instead of raising it.

ParameterTypeDescription
record_typetype[R]
fieldsAny = {}

Returns Result[R, NetAddressError]

def make_record[R: DnsRecord](record_type: type[R], /, **fields: Any) -> Result[R, NetAddressError]:
    """Build a record, as its constructor does, giving the rejection as an
    ``Err`` instead of raising it."""
    try:
        return Ok(record_type(**fields))
    except NetAddressError as error:
        return Err(error)
    except TypeError as cause:
        return Err(NetAddressError(f"invalid {record_type.tag} record", fields, cause))

reverse_name

reverse_name(address) -> DomainName

The in-addr.arpa / ip6.arpa name a PTR lookup queries.

ParameterTypeDescription
addressIpAddress

Returns DomainName

def reverse_name(address: IpAddress) -> DomainName:
    """The ``in-addr.arpa`` / ``ip6.arpa`` name a PTR lookup queries."""
    if isinstance(address, IPv4Address):
        return DomainName(
            ".".join(str(o) for o in reversed(ipv4_to_octets(address))) + ".in-addr.arpa"
        )
    nibbles = [f"{n:x}" for octet in ipv6_to_octets(address) for n in (octet >> 4, octet & 0xF)]
    return DomainName(".".join(reversed(nibbles)) + ".ip6.arpa")

layer_static

layer_static(hosts=None, records=None) -> Layer[Dns, NetAddressError]

A Dns layer answering from a fixed zone.

ParameterTypeDescription
hostsMapping[str, Sequence[IpAddressInput]] | None = None
recordsMapping[str, Sequence[DnsRecord]] | None = None

Returns Layer[Dns, NetAddressError]

def layer_static(
    hosts: Mapping[str, Sequence[IpAddressInput]] | None = None,
    records: Mapping[str, Sequence[DnsRecord]] | None = None,
) -> Layer[Dns, NetAddressError]:
    """A ``Dns`` layer answering from a fixed zone."""
    return layer_effect(Dns, from_result(make_static(hosts, records)))

make

make(lookup, resolve=None, reverse=None) -> DnsService

A DNS service from its primitives. Without resolve, record queries fail with Unsupported; without reverse, reverse lookups query PTR records.

ParameterTypeDescription
lookupLookup
resolveResolve | None = None
reverseReverse | None = None

Returns DnsService

def make(
    lookup: Lookup, resolve: Resolve | None = None, reverse: Reverse | None = None
) -> DnsService:
    """A DNS service from its primitives. Without ``resolve``, record
    queries fail with ``Unsupported``; without ``reverse``, reverse lookups
    query PTR records."""

    def unsupported(
        name: DomainName, record_type: RecordType
    ) -> Effect[Sequence[DnsRecord], DnsError]:
        return fail(DnsError("Unsupported", "resolve", name, record_type))

    resolve_records = resolve or unsupported

    def reverse_by_ptr(address: IpAddress) -> Effect[Sequence[str], DnsError]:
        def rename(error: DnsError) -> DnsError:
            return DnsError(error.reason, "reverse", format_ip(address), cause=error.cause)

        return (
            resolve_records(reverse_name(address), "PTR")
            .map(lambda records: [r.host for r in records if isinstance(r, Ptr)])
            .map_error(rename)
        )

    return DnsService(lookup, resolve_records, reverse or reverse_by_ptr)

make_static

make_static(hosts=None, records=None) -> Result[DnsService, NetAddressError]

A DNS service answering from a fixed zone: addresses by host name, records by name.

ParameterTypeDescription
hostsMapping[str, Sequence[IpAddressInput]] | None = None
recordsMapping[str, Sequence[DnsRecord]] | None = None

Returns Result[DnsService, NetAddressError]

def make_static(
    hosts: Mapping[str, Sequence[IpAddressInput]] | None = None,
    records: Mapping[str, Sequence[DnsRecord]] | None = None,
) -> Result[DnsService, NetAddressError]:
    """A DNS service answering from a fixed zone: addresses by host name,
    records by name."""
    entries: dict[str, _Entry] = {}

    def entry(name: str) -> Result[_Entry, NetAddressError]:
        return domain_name_from_input(name).map(
            lambda domain: entries.setdefault(_zone_key(domain), _Entry([], []))
        )

    for name, inputs in (hosts or {}).items():
        match entry(name):
            case Err() as error:
                return error
            case Ok(current):
                for value in inputs:
                    match ip_from_input(value):
                        case Err() as error:
                            return error
                        case Ok(address):
                            current.addresses.append(address)
    for name, values in (records or {}).items():
        match entry(name):
            case Err() as error:
                return error
            case Ok(current):
                for record in values:
                    if not isinstance(record, record_classes):
                        return Err(NetAddressError("expected a DNS record", record))
                    current.records.append(record)

    def records_at(name: str) -> list[DnsRecord]:
        found = entries.get(_zone_key(name))
        return [] if found is None else found.records

    def lookup(host: DomainName, _family: IpFamily | None) -> Effect[Sequence[IpAddress], DnsError]:
        def answer() -> Sequence[IpAddress]:
            found = entries.get(_zone_key(host))
            direct = [] if found is None else found.addresses
            return [*direct, *(r.address for r in records_at(host) if isinstance(r, (A, Aaaa)))]

        return sync(answer)

    def resolve(name: DomainName, _type: RecordType) -> Effect[Sequence[DnsRecord], DnsError]:
        return sync(lambda: records_at(name))

    def reverse(address: IpAddress) -> Effect[Sequence[str], DnsError]:
        def answer() -> Sequence[str]:
            named = [name for name, current in entries.items() if address in current.addresses]
            pointed = [r.host for r in records_at(reverse_name(address)) if isinstance(r, Ptr)]
            return [*named, *pointed]

        return sync(answer)

    return Ok(make(lookup, resolve, reverse))

name_server_from_input

name_server_from_input(value) -> Result[InetAddress, NetAddressError]

A name server address from text, parts with a port, or an IP address (port 53).

ParameterTypeDescription
valueIpAddressInput | InetAddressInput

Returns Result[InetAddress, NetAddressError]

def name_server_from_input(
    value: IpAddressInput | InetAddressInput,
) -> Result[InetAddress, NetAddressError]:
    """A name server address from text, parts with a port, or an IP address
    (port 53)."""
    if isinstance(value, str):
        return name_server_from_string(value)
    if isinstance(value, (Mapping, InetAddressV4, InetAddressV6)):
        return inet_address_from_input(value)
    return ip_from_input(value).map(lambda address: inet_address_unsafe(address, 53))

name_server_from_string

name_server_from_string(text) -> Result[InetAddress, NetAddressError]

A name server address; port 53 unless given.

ParameterTypeDescription
textstr

Returns Result[InetAddress, NetAddressError]

def name_server_from_string(text: str) -> Result[InetAddress, NetAddressError]:
    """A name server address; port 53 unless given."""
    if text.startswith("[") or _HOST_PORT.fullmatch(text):
        return parse_inet(text)
    return parse_inet(f"[{text}]:53" if ":" in text else f"{text}:53")

dns_error_from_cause

dns_error_from_cause(cause, method, hostname) -> DnsError

The DnsError of a resolver failure, by its error code.

ParameterTypeDescription
causeOSError
methodDnsMethod
hostnamestr

Returns DnsError

def dns_error_from_cause(cause: OSError, method: DnsMethod, hostname: str) -> DnsError:
    """The ``DnsError`` of a resolver failure, by its error code."""
    if isinstance(cause, socket.herror):
        return DnsError("NotFound", method, hostname, cause=cause)
    reason = _REASONS.get(cause.errno, "Unknown") if cause.errno is not None else "Unknown"
    return DnsError(reason, method, hostname, cause=cause)

layer_system

layer_system(name_servers=()) -> Layer[Dns]

Dns answered by the operating system's resolver.

ParameterTypeDescription
name_serversSequence[InetAddress] = ()

Returns Layer[Dns]

def layer_system(name_servers: Sequence[InetAddress] = ()) -> Layer[Dns]:
    """``Dns`` answered by the operating system's resolver."""
    return layer_succeed(Dns, make_system(name_servers))

make_system

make_system(name_servers=()) -> DnsService

The system resolver as a DnsService; PTR queries and reverse lookups ask name_servers (from dns.name_server_from_input) instead of the system's name servers when given.

ParameterTypeDescription
name_serversSequence[InetAddress] = ()

Returns DnsService

def make_system(name_servers: Sequence[InetAddress] = ()) -> DnsService:
    """The system resolver as a ``DnsService``; PTR queries and reverse
    lookups ask ``name_servers`` (from ``dns.name_server_from_input``) instead
    of the system's name servers when given."""
    return make(_lookup, _resolver(name_servers))