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)

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.

property additional: List[RRset]

The additional data section.

property answer: List[RRset]

The answer section.

property authority: List[RRset]

The authority section.

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

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

section, an int section number, a str section name, or one of the section attributes of this message. This specifies the the section of the message to search. 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)

name, a dns.name.Name or str, the name of the RRset.

rdclass, an int or str, the class of the RRset.

rdtype, an int or str, the type of the RRset.

covers, an int or str, the covers value of the RRset. The default is dns.rdatatype.NONE.

deleting, an int, str, or None, the deleting value of the RRset. The default is None.

create, a bool. If True, create the RRset if it is not found. The created RRset is appended to section.

force_unique, a bool. If True and create is also True, create a new RRset regardless of whether a matching RRset exists already. The default is False. This is useful when creating DDNS Update messages, as order matters for them.

idna_codec, a dns.name.IDNACodec, specifies the IDNA encoder/decoder. If None, the default IDNA 2003 encoder/decoder is used.

Raises KeyError if the RRset was not found and create was False.

Returns a dns.rrset.RRset object.

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

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

If the RRset is not found, None is returned.

section, an int section number, a str section name, or one of the section attributes of this message. This specifies the the section of the message to search. For example:

my_message.get_rrset(my_message.answer, name, rdclass, rdtype)
my_message.get_rrset(dns.message.ANSWER, name, rdclass, rdtype)
my_message.get_rrset("ANSWER", name, rdclass, rdtype)

name, a dns.name.Name or str, the name of the RRset.

rdclass, an int or str, the class of the RRset.

rdtype, an int or str, the type of the RRset.

covers, an int or str, the covers value of the RRset. The default is dns.rdatatype.NONE.

deleting, an int, str, or None, the deleting value of the RRset. The default is None.

create, a bool. If True, create the RRset if it is not found. The created RRset is appended to section.

force_unique, a bool. If True and create is also True, create a new RRset regardless of whether a matching RRset exists already. The default is False. This is useful when creating DDNS Update messages, as order matters for them.

idna_codec, a dns.name.IDNACodec, specifies the IDNA encoder/decoder. If None, the default IDNA 2003 encoder/decoder is used.

Returns a dns.rrset.RRset object or None.

is_response(other: Message) → bool

Is other, also a dns.message.Message, a response to this message?

Returns a bool.

opcode() → Opcode

Return the opcode.

Returns a dns.opcode.Opcode.

property question: List[RRset]

The question section.

rcode() → Rcode

Return the rcode.

Returns a dns.rcode.Rcode.

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

Returns the number of records in the specified section.

section, an int section number, a str section name, or one of the section attributes of this message. This specifies the the section of the message to count. 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]

Return the section list associated with the specified section number.

number is a section number int or the text form of a section name.

Raises ValueError if the section isn’t known.

Returns a list.

section_number(section: List[RRset]) → int

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

section is one of the section attributes of this message.

Raises ValueError if the section isn’t known.

Returns an int.

set_opcode(opcode: Opcode) → None

Set the opcode.

opcode, a dns.opcode.Opcode, is the opcode to set.

set_rcode(rcode: Rcode) → None

Set the rcode.

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

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

Convert the message to text.

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

Returns a 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: Dict[str, Any]) → bytes

Return a string containing the message in DNS compressed wire format.

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

origin, a dns.name.Name or None, the origin to be appended to any relative names. If None, and the message has an origin attribute that is not None, then it will be used.

max_size, an int, the maximum size of the wire format output; default is 0, which means “the message’s request payload, if nonzero, or 65535”.

multi, a bool, should be set to True if this message is part of a multiple message sequence.

tsig_ctx, a dns.tsig.HMACTSig or dns.tsig.GSSTSig object, the ongoing TSIG context, used when signing zone transfers.

prepend_length, a bool, should be set to True if the caller wants the message length prepended to the message itself. This is useful for messages sent over TCP, TLS (DoT), or QUIC (DoQ).

prefer_truncation, a bool, should be set to True if the caller wants the message to be truncated if it would otherwise exceed the maximum length. If the truncation occurs before the additional section, the TC bit will be set.

Raises dns.exception.TooBig if max_size was exceeded.

Returns a 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

Configure EDNS behavior.

edns, an int, is the EDNS level to use. Specifying None, False, or -1 means “do not use EDNS”, and in this case the other parameters are ignored. Specifying True is equivalent to specifying 0, i.e. “use EDNS0”.

ednsflags, an int, the EDNS flag values.

payload, an int, is the EDNS sender’s payload field, which is the maximum size of UDP datagram the sender can handle. I.e. how big a response to this message can be.

request_payload, an int, is the EDNS payload size to use when sending this message. If not specified, defaults to the value of payload.

options, a list of dns.edns.Option objects or None, the EDNS options.

pad, a non-negative int. If 0, the default, do not pad; otherwise add padding bytes to make the message size a multiple of pad. Note that if padding is non-zero, an EDNS PADDING option will always be added to the message.

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

When sending, a TSIG signature using the specified key should be added.

key, a dns.tsig.Key is the key to use. If a key is specified, the keyring and algorithm fields are not used.

keyring, a dict, callable or dns.tsig.Key, is either the TSIG keyring or key to use.

The format of a keyring dict is a mapping from TSIG key name, as dns.name.Name to dns.tsig.Key or a TSIG secret, a bytes. If a dict keyring is specified but a keyname is not, the key used will be the first key in the keyring. Note that the order of keys in a dictionary is not defined, so applications should supply a keyname when a dict keyring is used, unless they know the keyring contains only one key. If a callable keyring is specified, the callable will be called with the message and the keyname, and is expected to return a key.

keyname, a dns.name.Name, str or None, the name of this TSIG key to use; defaults to None. If keyring is a dict, the key must be defined in it. If keyring is a dns.tsig.Key, this is ignored.

fudge, an int, the TSIG time fudge.

original_id, an int, the TSIG original id. If None, the message’s id is used.

tsig_error, an int, the TSIG error code.

other_data, a bytes, the TSIG other data.

algorithm, a dns.name.Name or str, the TSIG algorithm to use. This is only used if keyring is a dict, and the key entry is a bytes.

want_dnssec(wanted: bool = True) → None

Enable or disable ‘DNSSEC desired’ flag in requests.

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

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