Go to the latest version of this document.

# ``twisted`.`names`.`dns``

module documentation
(source)

DNS protocol implementation.

Future Plans:

- Get rid of some toplevels, maybe.

Interface | `IEncodable` | Interface for something which can be encoded to and decoded to the DNS wire format.
Interface | `IEncodableRecord` | Interface for DNS records that can be encoded and decoded.
Interface | `IRecord` | A single entry in a zone of authority.
Class | `Charstr` | No class docstring; 0/1 instance variable, 3/6 methods documented
Class | `DNSDatagramProtocol` | DNS protocol over UDP.
Class | `DNSMixin` | DNS protocol mixin shared by UDP and TCP implementations.
Class | `DNSProtocol` | DNS protocol over TCP.
Class | `Message` | `Message` contains all the information represented by a single DNS request or response.
Class | `Name` | A name in the domain name system, made up of multiple labels. For example, twistedmatrix.com.
Class | `Query` | Represent a single DNS query.
Class | `Record_A` | An IPv4 host address.
Class | `Record_A6` | An IPv6 address.
Class | `Record_AAAA` | An IPv6 host address.
Class | `Record_AFSDB` | Map from a domain name to the name of an AFS cell database server.
Class | `Record_CNAME` | The canonical name for an alias.
Class | `Record_DNAME` | A non-terminal DNS name redirection.
Class | `Record_HINFO` | Host information.
Class | `Record_MB` | A mailbox domain name.
Class | `Record_MD` | A mail destination.
Class | `Record_MF` | A mail forwarder.
Class | `Record_MG` | A mail group member.
Class | `Record_MINFO` | Mailbox or mail list information.
Class | `Record_MR` | A mail rename domain name.
Class | `Record_MX` | Mail exchange.
Class | `Record_NAPTR` | The location of the server(s) for a specific protocol and domain.
Class | `Record_NS` | An authoritative nameserver.
Class | `Record_NULL` | A null record.
Class | `Record_PTR` | A domain name pointer.
Class | `Record_RP` | The responsible person for a domain.
Class | `Record_SOA` | Marks the start of a zone of authority.
Class | `Record_SPF` | Structurally, freeform text. Semantically, a policy definition, formatted as defined in rfc 4408.
Class | `Record_SRV` | The location of the server(s) for a specific protocol and domain.
Class | `Record_SSHFP` | A record containing the fingerprint of an SSH key.
Class | `Record_TSIG` | A transaction signature, encapsulated in a RR, as described in RFC 2845.
Class | `Record_TXT` | Freeform text.
Class | `Record_WKS` | A well known service description.
Class | `RRHeader` | A resource record header.
Class | `SimpleRecord` | A Resource Record which consists of a single RFC 1035 domain-name.
Class | `UnknownRecord` | Encapsulate the wire data for unknown record types so that they can pass through the system unchanged.
Exception | `DNSDecodeError` | Raised when a DNS message cannot be decoded because it violates a protocol-level safety limit.
Function | `domainString` | Coerce a domain name string to bytes.
Function | `randomSource` | Wrapper around `twisted.python.randbytes.RandomFactory.secureRandom` to return 2 random bytes.
Function | `readPrecisely` | Undocumented
Function | `str2time` | Parse a string description of an interval into an integer number of seconds.
Constant | `A6` | Undocumented
Constant | `AAAA` | Undocumented
Constant | `ANY` | Undocumented
Constant | `DNAME` | Undocumented
Constant | `EBADVERSION` | Undocumented
Constant | `EXT_QUERIES` | Undocumented
Constant | `NAPTR` | Undocumented
Constant | `OP_NOTIFY` | Undocumented
Constant | `OP_UPDATE` | Undocumented
Constant | `OPT` | Undocumented
Constant | `PORT` | Undocumented
Constant | `QUERY_CLASSES` | Undocumented
Constant | `QUERY_TYPES` | Undocumented
Constant | `REV_CLASSES` | Undocumented
Constant | `REV_TYPES` | Undocumented
Constant | `SPF` | Undocumented
Constant | `SRV` | Undocumented
Constant | `SSHFP` | Undocumented
Constant | `TKEY` | Undocumented
Constant | `TSIG` | Undocumented
Variable | `A` | Undocumented
Variable | `AFSDB` | Undocumented
Variable | `ALL_RECORDS` | Undocumented
Variable | `AXFR` | Undocumented
Variable | `CH` | Undocumented
Variable | `CNAME` | Undocumented
Variable | `CS` | Undocumented
Variable | `EBADKEY` | Undocumented
Variable | `EBADSIG` | Undocumented
Variable | `EBADTIME` | Undocumented
Variable | `EFORMAT` | Undocumented
Variable | `ENAME` | Undocumented
Variable | `ENOTIMP` | Undocumented
Variable | `EREFUSED` | Undocumented
Variable | `ESERVER` | Undocumented
Variable | `HINFO` | Undocumented
Variable | `HS` | Undocumented
Variable | `IN` | Undocumented
Variable | `IXFR` | Undocumented
Variable | `MAILA` | Undocumented
Variable | `MAILB` | Undocumented
Variable | `MB` | Undocumented
Variable | `MD` | Undocumented
Variable | `MF` | Undocumented
Variable | `MG` | Undocumented
Variable | `MINFO` | Undocumented
Variable | `MR` | Undocumented
Variable | `MX` | Undocumented
Variable | `NS` | Undocumented
Variable | `NULL` | Undocumented
Variable | `OK` | Undocumented
Variable | `OP_INVERSE` | Undocumented
Variable | `OP_QUERY` | Undocumented
Variable | `OP_STATUS` | Undocumented
Variable | `PTR` | Undocumented
Variable | `RP` | Undocumented
Variable | `SOA` | Undocumented
Variable | `TXT` | Undocumented
Variable | `WKS` | Undocumented
Class | `_DecodeContext` | Mutable state shared between the `IEncodable` decoders invoked while reading a single DNS message.
Class | `_EDNSMessage` | An EDNS message.
Class | `_OPTHeader` | An OPT record header.
Class | `_OPTVariableOption` | A class to represent OPT record variable options.
Function | `_compactRepr` | Return a `str` representation of `obj` which only shows fields with non-default values, flags which are True and sections which have been explicitly set.
Function | `_getDisplayableArguments` | Inspect the function signature of `obj`'s constructor, and get a list of which arguments should be displayed. This is a helper function for `_compactRepr`.
Function | `_installDecodeContext` | Install `context` on `_decodeContextVar` for the duration of the `with` block and restore the previous value on exit.
Function | `_isSubdomainOf` | Test whether `descendantName` is equal to or is a subdomain of `ancestorName`.
Function | `_nameToLabels` | Split a domain name into its constituent labels.
Function | `_nicebytes` | Represent a mostly textful bytes object in a way suitable for presentation to an end user.
Function | `_nicebyteslist` | Represent a list of mostly textful bytes objects in a way suitable for presentation to an end user.
Function | `_ord2bytes` | Construct a bytes object representing a single byte with the given ordinal value.
Function | `_responseFromMessage` | Generate a `Message` like instance suitable for use as the response to `message`.
Function | `_str2time` | mypy doesn't like type-punning str | bytes | int | None into a str so we have this helper function.
Variable | `_decodeContextVar` | Undocumented

def domainString(domain: `str | bytes`) -> `bytes`: (source)

Coerce a domain name string to bytes.

`twisted.names` represents domain names as `bytes`, but many interfaces accept `bytes` or a text string (`unicode` on Python 2, `str` on Python 3). This function coerces text strings using IDNA encoding --- see `encodings.idna`.

Note that DNS is case insensitive but case preserving. This function doesn't normalize case, so you'll still need to do that whenever comparing the strings it returns.

Parameters
domain:`bytes` or `str` | A domain name. If passed as a text string it will be `idna` encoded.

Returns
`bytes` | `bytes` suitable for network transmission.

Present Since
Twisted 20.3.0

def randomSource(): (source)

Wrapper around `twisted.python.randbytes.RandomFactory.secureRandom` to return 2 random bytes.

Returns
`bytes` | Undocumented

def readPrecisely(file, l): (source)

Undocumented

@overload
def str2time(s: `str | bytes | int`) -> `int`:
@overload
def str2time(s: `None`):
(source)

Parse a string description of an interval into an integer number of seconds.

Parameters

s:text string (`bytes` or `str`) for parsing; anything else for passthrough.

An interval definition constructed as an interval duration followed by an interval unit. An interval duration is a base ten representation of an integer. An interval unit is one of the following letters: S (seconds), M (minutes), H (hours), D (days), W (weeks), or Y (years). For example: `"3S"` indicates an interval of three seconds; `"5D"` indicates an interval of five days. Alternatively, `s` may be any non-string and it will be returned unmodified.

Returns
`int | None` | an `int` giving the interval represented by the string `s`, or whatever `s` is if it is not a string.

A6: `int` = (source)

Undocumented

Value

    38

AAAA: `int` = (source)

Undocumented

Value

    28

ANY: `int` = (source)

Undocumented

Value

    255

DNAME: `int` = (source)

Undocumented

Value

    39

EBADVERSION: `int` = (source)

Undocumented

Value

    16

EXT_QUERIES = (source)

Undocumented

Value

    {IXFR: 'IXFR',
     AXFR: 'AXFR',
     MAILB: 'MAILB',
     MAILA: 'MAILA',
     ALL_RECORDS: 'ALL_RECORDS'}

NAPTR: `int` = (source)

Undocumented

Value

    35

OP_NOTIFY: `int` = (source)

Undocumented

Value

    4

OP_UPDATE: `int` = (source)

Undocumented

Value

    5

OPT: `int` = (source)

Undocumented

Value

    41

PORT: `int` = (source)

Undocumented

Value

    53

QUERY_CLASSES = (source)

Undocumented

Value

    {IN: 'IN', CS: 'CS', CH: 'CH', HS: 'HS', ANY: 'ANY'}

QUERY_TYPES = (source)

Undocumented

Value

    {A: 'A',
     NS: 'NS',
     MD: 'MD',
     MF: 'MF',
     CNAME: 'CNAME',
     SOA: 'SOA',
     MB: 'MB',
    ...

REV_CLASSES = (source)

Undocumented

Value

    {v: k for k, v in QUERY_CLASSES.items()}

REV_TYPES = (source)

Undocumented

Value

    {v: k for k, v in chain(QUERY_TYPES.items(), EXT_QUERIES.items())}

SPF: `int` = (source)

Undocumented

Value

    99

SRV: `int` = (source)

Undocumented

Value

    33

SSHFP: `int` = (source)

Undocumented

Value

    44

TKEY: `int` = (source)

Undocumented

Value

    249

TSIG: `int` = (source)

Undocumented

Value

    250

A = (source)

Undocumented

AFSDB = (source)

Undocumented

ALL_RECORDS = (source)

Undocumented

AXFR = (source)

Undocumented

CH = (source)

Undocumented

CNAME = (source)

Undocumented

CS = (source)

Undocumented

EBADKEY = (source)

Undocumented

EBADSIG = (source)

Undocumented

EBADTIME = (source)

Undocumented

EFORMAT = (source)

Undocumented

ENAME = (source)

Undocumented

ENOTIMP = (source)

Undocumented

EREFUSED = (source)

Undocumented

ESERVER = (source)

Undocumented

HINFO = (source)

Undocumented

HS = (source)

Undocumented

IN = (source)

Undocumented

IXFR = (source)

Undocumented

MAILA = (source)

Undocumented

MAILB = (source)

Undocumented

MB = (source)

Undocumented

MD = (source)

Undocumented

MF = (source)

Undocumented

MG = (source)

Undocumented

MINFO = (source)

Undocumented

MR = (source)

Undocumented

MX = (source)

Undocumented

NS = (source)

Undocumented

NULL = (source)

Undocumented

OK = (source)

Undocumented

OP_INVERSE = (source)

Undocumented

OP_QUERY = (source)

Undocumented

OP_STATUS = (source)

Undocumented

PTR = (source)

Undocumented

RP = (source)

Undocumented

SOA = (source)

Undocumented

TXT = (source)

Undocumented

WKS = (source)

Undocumented

def _compactRepr(obj: `object`, alwaysShow: `Sequence[str] | None` = None, flagNames: `Sequence[str] | None` = None, fieldNames: `Sequence[str] | None` = None, sectionNames: `Sequence[str] | None` = None) -> `str`: (source)

Return a `str` representation of `obj` which only shows fields with non-default values, flags which are True and sections which have been explicitly set.

Parameters
obj:`object` | The instance whose repr is being generated.
alwaysShow:`Sequence[str] | None` | A `list` of field names which should always be shown.
flagNames:`Sequence[str] | None` | A `list` of flag attribute names which should be shown if they are `True`.
fieldNames:`Sequence[str] | None` | A `list` of field attribute names which should be shown if they have non-default values.
sectionNames:`Sequence[str] | None` | A `list` of section attribute names which should be shown if they have been assigned a value.

Returns
`str` | A `str` representation of `obj`.

def _getDisplayableArguments(obj, alwaysShow, fieldNames): (source)

Inspect the function signature of `obj`'s constructor, and get a list of which arguments should be displayed. This is a helper function for `_compactRepr`.

Parameters
obj | The instance whose repr is being generated.
alwaysShow | A `list` of field names which should always be shown.
fieldNames | A `list` of field attribute names which should be shown if they have non-default values.

Returns
A `list` of displayable arguments.

@contextmanager
def _installDecodeContext(context: `_DecodeContext`) -> `Generator[_DecodeContext]`: (source)

Install `context` on `_decodeContextVar` for the duration of the `with` block and restore the previous value on exit.

This wraps the `contextvars.ContextVar.set` / `contextvars.ContextVar.reset` token dance so call sites can use a plain `with` statement.

Parameters
context:`_DecodeContext` | The `_DecodeContext` to install as the active context.

Returns
`Generator[_DecodeContext]` | Undocumented

def _isSubdomainOf(descendantName, ancestorName): (source)

Test whether `descendantName` is equal to or is a subdomain of `ancestorName`.

The names are compared case-insensitively.

The names are treated as byte strings containing one or more DNS labels separated by ..

`descendantName` is considered equal if its sequence of labels exactly matches the labels of `ancestorName`.

`descendantName` is considered a subdomain if its sequence of labels ends with the labels of `ancestorName`.

Parameters
descendantName:`bytes` | The DNS subdomain name.
ancestorName:`bytes` | The DNS parent or ancestor domain name.

Returns
`True` if `descendantName` is equal to or if it is a subdomain of `ancestorName`. Otherwise returns `False`.

def _nameToLabels(name): (source)

Split a domain name into its constituent labels.

Parameters
name:`bytes` | A fully qualified domain name (with or without a trailing dot).

Returns
`list` of `bytes` | A `list` of labels ending with an empty label representing the DNS root zone.

def _nicebytes(bytes): (source)

Represent a mostly textful bytes object in a way suitable for presentation to an end user.

Parameters
bytes | The bytes to represent.

Returns
`str` | Undocumented

def _nicebyteslist(list): (source)

Represent a list of mostly textful bytes objects in a way suitable for presentation to an end user.

Parameters
list | The list of bytes to represent.

Returns
`str` | Undocumented

def _ord2bytes(ordinal): (source)

Construct a bytes object representing a single byte with the given ordinal value.

Parameters
ordinal:`int` | Undocumented

Returns
`bytes` | Undocumented

def _responseFromMessage(responseConstructor, message, **kwargs): (source)

Generate a `Message` like instance suitable for use as the response to `message`.

The `queries`, `id` attributes will be copied from `message` and the `answer` flag will be set to `True`.

Parameters
responseConstructor:`callable` | A response message constructor with an initializer signature matching `dns.Message.__init__`.
message:`Message` | A request message.
**kwargs:`dict` | Keyword arguments which will be passed to the initialiser of the response message.

Returns
`responseConstructor` | A `Message` like response instance.

def _str2time(s: `str`) -> `int`: (source)

mypy doesn't like type-punning str | bytes | int | None into a str so we have this helper function.

_decodeContextVar: `contextvars.ContextVar[_DecodeContext | None]` = (source)

Undocumented