The dns.message.Message Class

This is the base class for all messages, and the class used for any DNS opcodes that do not have a more specific class.

class dns.message.Message(id: int | None = None)[source]

A DNS message.

id

An int, the query id; the default is a randomly chosen id.

flags

An int, the DNS flags of the message.

sections

A list of lists of dns.rrset.RRset objects.

edns

An int, the EDNS level to use. The default is -1, no EDNS.

ednsflags

An int, the EDNS flags.

payload

An int, the EDNS payload size. The default is 0.

options

The EDNS options, a list of dns.edns.Option objects. The default is the empty list.

request_payload

The associated request’s EDNS payload size. This field is meaningful in response messages, and if set to a non-zero value, will limit the size of the response to the specified size. The default is 0, which means “use the default limit” which is currently 65535.

keyring

A dns.tsig.Key, the TSIG key. The default is None.

keyname

The TSIG keyname to use, a dns.name.Name. The default is None.

keyalgorithm

A dns.name.Name, the TSIG algorithm to use. Defaults to dns.tsig.default_algorithm. Constants for TSIG algorithms are defined the in dns.tsig module.

request_mac

A bytes, the TSIG MAC of the request message associated with this message; used when validating TSIG signatures.

fudge

An int, the TSIG time fudge. The default is 300 seconds.

original_id

An int, the TSIG original id; defaults to the message’s id.

tsig_error

An int, the TSIG error code. The default is 0.

other_data

A bytes, the TSIG “other data”. The default is the empty bytes.

mac

A bytes, the TSIG MAC for this message.

xfr

A bool. This attribute is true when the message being used for the results of a DNS zone transfer. The default is False.

origin

A dns.name.Name. The origin of the zone in messages which are used for zone transfers or for DNS dynamic updates. The default is None.

tsig_ctx

An hmac.HMAC, the TSIG signature context associated with this message. The default is None.

had_tsig

A bool, which is True if the message had a TSIG signature when it was decoded from wire format.

multi

A bool, which is True if this message is part of a multi-message sequence. The default is False. This attribute is used when validating TSIG signatures on messages which are part of a zone transfer.

first

A bool, which is True if this message is stand-alone, or the first of a multi-message sequence. The default is True. This variable is used when validating TSIG signatures on messages which are part of a zone transfer.

index

A dict, an index of RRsets in the message. The index key is (section, name, rdclass, rdtype, covers, deleting). The default is {}. Indexing improves the performance of finding RRsets. Indexing can be disabled by setting the index to None.

wire

A bytes or None, the encoded wire format data used to create this message with dns.message.from_wire() or the output most recently generated by to_wire().

property additional: list[RRset]

The additional data section.

property answer: list[RRset]

The answer section.

property authority: list[RRset]

The authority section.

extended_errors() → list[EDEOption][source]

Return the list of Extended DNS Error (EDE) options in the message

find_rrset(section: int | str | list[RRset], name: Name, rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, deleting: RdataClass | None = None, create: bool = False, force_unique: bool = False, idna_codec: IDNACodec | None = None) → RRset[source]

Find the RRset with the given attributes in the specified section.

section may be an int section number, a str section name, or one of the section list attributes of this message. For example:

my_message.find_rrset(my_message.answer, name, rdclass, rdtype)
my_message.find_rrset(dns.message.ANSWER, name, rdclass, rdtype)
my_message.find_rrset("ANSWER", name, rdclass, rdtype)
Parameters:
Raises:

KeyError – If the RRset was not found and create is False.

Return type:

dns.rrset.RRset

get_options(otype: OptionType) → list[Option][source]

Return the list of options of the specified type.

get_rrset(section: int | str | list[RRset], name: Name, rdclass: RdataClass, rdtype: RdataType, covers: RdataType = RdataType.TYPE0, deleting: RdataClass | None = None, create: bool = False, force_unique: bool = False, idna_codec: IDNACodec | None = None) → RRset | None[source]

Get the RRset with the given attributes in the specified section.

Like find_rrset() but returns None instead of raising KeyError when the RRset is not found.

section may be an int section number, a str section name, or one of the section list attributes of this message.

Parameters:
Returns:

The matching RRset, or None if not found.

Return type:

dns.rrset.RRset or None

is_response(other: Message) → bool[source]

Is other a response to this message?

Parameters:

other (dns.message.Message) – The message to check.

Return type:

bool

opcode() → Opcode[source]

Return the opcode.

Return type:

dns.opcode.Opcode

property question: list[RRset]

The question section.

rcode() → Rcode[source]

Return the rcode.

Return type:

dns.rcode.Rcode

section_count(section: int | str | list[RRset]) → int[source]

Returns the number of records in the specified section.

Parameters:

section –

An int section number, a str section name, or one of the section attributes of this message. For example:

my_message.section_count(my_message.answer)
my_message.section_count(dns.message.ANSWER)
my_message.section_count("ANSWER")

section_from_number(number: int) → list[RRset][source]

Return the section list associated with the specified section number.

Parameters:

number – A section number (int) or text name of a section.

Raises:

ValueError – If the section is not known.

Return type:

list

section_number(section: list[RRset]) → int[source]

Return the “section number” of the specified section for use in indexing.

Parameters:

section – One of the section attributes of this message.

Raises:

ValueError – If the section is not known.

Return type:

int

set_opcode(opcode: Opcode) → None[source]

Set the opcode.

Parameters:

opcode (dns.opcode.Opcode) – The opcode to set.

set_rcode(rcode: Rcode) → None[source]

Set the rcode.

rcode, a dns.rcode.Rcode, is the rcode to set.

to_styled_text(style: MessageStyle) → str[source]

Convert the message to styled text.

Parameters:

style (dns.message.MessageStyle) – The style to use for formatting.

Return type:

str

to_text(origin: Name | None = None, relativize: bool = True, style: MessageStyle | None = None, **kw: Any) → str[source]

Convert the message to text.

The origin, relativize, and any other keyword arguments are passed to the RRset to_text() method.

Parameters:

style (dns.rdataset.RdatasetStyle or None) – If specified, overrides origin and relativize.

Return type:

str

to_wire(origin: Name | None = None, max_size: int = 0, multi: bool = False, tsig_ctx: Any | None = None, prepend_length: bool = False, prefer_truncation: bool = False, **kw: Any) → bytes[source]

Return the message in DNS compressed wire format.

Additional keyword arguments are passed to the RRset to_wire() method.

Parameters:

  • origin (dns.name.Name or None) – Origin to append to relative names. If None, the message’s own origin (if any) is used.

  • max_size (int) – Maximum wire format size; 0 means use the request payload or 65535.

  • multi (bool) – True if this message is part of a multi-message sequence.

  • tsig_ctx – Ongoing TSIG context for zone transfer signing.

  • prepend_length (bool) – If True, prepend the 2-byte message length (useful for TCP/TLS/QUIC).

  • prefer_truncation (bool) – If True, truncate instead of raising when the message exceeds max_size. Sets TC if truncation is before the additional section.

Raises:

dns.exception.TooBig – If max_size is exceeded and prefer_truncation is False.

Return type:

bytes

use_edns(edns: int | bool | None = 0, ednsflags: int = 0, payload: int = 1232, request_payload: int | None = None, options: list[Option] | None = None, pad: int = 0) → None[source]

Configure EDNS behavior.

Parameters:

  • edns (int or None) – The EDNS level to use. Specifying None, False, or -1 means “do not use EDNS” (other parameters are ignored). Specifying True is equivalent to specifying 0 (use EDNS0).

  • ednsflags (int) – The EDNS flag values.

  • payload (int) – The EDNS sender’s payload field — the maximum UDP datagram size the sender can handle (i.e. how big a response can be).

  • request_payload (int or None) – The EDNS payload size to use when sending. Defaults to the value of payload.

  • options (list of dns.edns.Option or None) – The EDNS options.

  • pad (int) – If 0 (the default), do not pad; otherwise add padding bytes to make the message size a multiple of pad. When nonzero, an EDNS PADDING option is always added.

use_tsig(keyring: Any, keyname: Name | str | None = None, fudge: int = 300, original_id: int | None = None, tsig_error: int = 0, other_data: bytes = b'', algorithm: Name | str = <DNS name hmac-sha256.>) → None[source]

Arrange for a TSIG signature to be added when sending.

Parameters:

  • keyring (dict, callable, or dns.tsig.Key) – The TSIG keyring or key. A dict maps dns.name.Name keys to dns.tsig.Key objects or bytes secrets. If a dict is given without keyname, the first key in the dict is used. A callable is invoked with the message and keyname and must return a key.

  • keyname (dns.name.Name, str, or None) – The TSIG key name. Ignored if keyring is a dns.tsig.Key. Defaults to None.

  • fudge (int) – The TSIG time fudge.

  • original_id (int or None) – The TSIG original id. Defaults to the message id.

  • tsig_error (int) – The TSIG error code.

  • other_data (bytes) – The TSIG other data.

  • algorithm (dns.name.Name or str) – The TSIG algorithm. Only used when keyring is a dict and the key entry is bytes.

want_dnssec(wanted: bool = True) → None[source]

Enable or disable ‘DNSSEC desired’ flag in requests.

Parameters:

wanted (bool) – If True, DNSSEC data is desired in the response, EDNS is enabled if required, and the DO bit is set. If False, the DO bit is cleared if EDNS is enabled.

class dns.message.MessageStyle(omit_final_dot: bool = False, idna_codec: IDNACodec | None = None, origin: Name | None = None, relativize: bool = False, txt_is_utf8: bool = False, base64_chunk_size: int = 32, base64_chunk_separator: str = ' ', hex_chunk_size: int = 128, hex_chunk_separator: str = ' ', truncate_crypto: bool = False, override_rdclass: RdataClass | None = None, want_comments: bool = False, omit_rdclass: bool = False, omit_ttl: bool = False, want_generic: bool = False, deduplicate_names: bool = False, first_name_is_duplicate: bool = False, default_ttl: int | None = None, name_just: int = 0, ttl_just: int = 0, rdclass_just: int = 0, rdtype_just: int = 0)[source]

Message text styles.

A MessageStyle is also a dns.name.NameStyle and a dns.rdata.RdataStyle, and a dns.rdataset.RdatasetStyle. See those classes for a description of their options.

There are currently no message-specific style options, but if that changes they will be documented here.

The following constants may be used to specify sections in the find_rrset() and get_rrset() methods:

dns.message.QUESTION = MessageSection.QUESTION

Message sections

dns.message.ANSWER = MessageSection.ANSWER

Message sections

dns.message.AUTHORITY = MessageSection.AUTHORITY

Message sections

dns.message.ADDITIONAL = MessageSection.ADDITIONAL

Message sections