0
# DNSPython
1

2
DNSPython is a comprehensive DNS toolkit for Python that supports almost all DNS record types and provides both high-level and low-level access to DNS functionality. It enables queries, zone transfers, dynamic updates, TSIG authenticated messages, and EDNS0 operations with support for DNSSEC validation.
3

4
## Package Information
5

6
- **Package Name**: dnspython
7
- **Language**: Python
8
- **Installation**: `pip install dnspython`
9

10
## Core Imports
11

12
```python
13
import dns
14
```
15

16
Common imports for specific functionality:
17

18
```python
19
import dns.resolver
20
import dns.query
21
import dns.message
22
import dns.name
23
import dns.zone
24
```
25

26
Import specific record types:
27

28
```python
29
from dns import rdatatype, rdataclass
30
```
31

32
## Basic Usage
33

34
```python
35
import dns.resolver
36

37
# High-level DNS resolution
38
resolver = dns.resolver.Resolver()
39
result = dns.resolver.query('example.com', 'A')
40
for rdata in result:
41
    print(f"IP address: {rdata.address}")
42

43
# Query specific record types
44
mx_records = dns.resolver.query('example.com', 'MX')
45
for rdata in mx_records:
46
    print(f"Mail server: {rdata.exchange}, priority: {rdata.preference}")
47

48
# Custom resolver configuration
49
resolver.nameservers = ['8.8.8.8', '8.8.4.4']
50
resolver.timeout = 30
51
resolver.lifetime = 60
52
```
53

54
## Architecture
55

56
DNSPython provides a layered architecture for DNS operations:
57

58
- **High-level**: `dns.resolver` for simple queries with automatic retry and caching
59
- **Mid-level**: `dns.query` for direct message exchange with nameservers
60
- **Low-level**: `dns.message`, `dns.name`, `dns.rdata` for direct protocol manipulation
61
- **Zone operations**: `dns.zone` for zone file parsing and manipulation
62
- **Security**: `dns.dnssec`, `dns.tsig` for authentication and validation
63

64
This design enables everything from simple hostname resolution to complex DNS server implementations and security analysis tools.
65

66
## Capabilities
67

68
### High-Level DNS Resolution
69

70
Simple DNS queries with automatic retry, caching, and error handling. Provides the easiest interface for common DNS lookups and supports all standard record types.
71

72
```python { .api }
73
def query(qname, rdtype='A', rdclass='IN', tcp=False, source=None, 
74
          raise_on_no_answer=True, source_port=0, lifetime=None): ...
75
def zone_for_name(name, rdclass='IN', tcp=False, resolver=None): ...
76
```
77

78
[DNS Resolution](./dns-resolution.md)
79

80
### Low-Level DNS Queries
81

82
Direct DNS message exchange with nameservers using UDP or TCP. Provides fine-grained control over query parameters, timeouts, and response handling.
83

84
```python { .api }
85
def udp(q, where, timeout=None, port=53, af=None, source=None, source_port=0): ...
86
def tcp(q, where, timeout=None, port=53, af=None, source=None, source_port=0): ...
87
def xfr(where, zone, rdtype='AXFR', rdclass='IN', timeout=None, port=53): ...
88
```
89

90
[DNS Queries](./dns-queries.md)
91

92
### DNS Message Manipulation
93

94
Create, parse, and manipulate DNS messages with full protocol support. Handle questions, answers, authority, and additional sections with complete header control.
95

96
```python { .api }
97
def make_query(qname, rdtype, rdclass='IN', use_edns=None, want_dnssec=False): ...
98
def make_response(query, recursion_available=False, our_payload=8192): ...
99
def from_wire(wire, keyring=None, request_mac=b'', xfr=False): ...
100
```
101

102
[DNS Messages](./dns-messages.md)
103

104
### DNS Name Operations
105

106
Parse, manipulate, and format DNS names with full internationalization support. Handle absolute/relative names, wildcards, and IDNA encoding.
107

108
```python { .api }
109
def from_text(text, origin=None, idna_codec=None): ...
110
def from_unicode(text, origin=None, idna_codec=None): ...
111
def from_wire(message, current): ...
112
```
113

114
[DNS Names](./dns-names.md)
115

116
### DNS Zone Management
117

118
Parse, create, and manipulate DNS zones from files or transfers. Support for zone validation, iteration, and modification operations.
119

120
```python { .api }
121
def from_text(text, origin=None, rdclass='IN', relativize=True): ...
122
def from_file(f, origin=None, rdclass='IN', relativize=True): ...
123
def from_xfr(xfr, zone_factory=None, relativize=True): ...
124
```
125

126
[DNS Zones](./dns-zones.md)
127

128
### DNS Record Types and Data
129

130
Comprehensive support for all DNS record types including modern types like TLSA, CAA, and CDS. Handle record parsing, formatting, and validation.
131

132
```python { .api }
133
# Record type constants
134
A = 1
135
NS = 2
136
CNAME = 5
137
SOA = 6
138
MX = 15
139
TXT = 16
140
AAAA = 28
141
SRV = 33
142
TLSA = 52
143
CAA = 257
144
```
145

146
[DNS Records](./dns-records.md)
147

148
### DNSSEC Operations
149

150
Validate DNSSEC signatures, handle keys, and perform cryptographic operations. Support for all DNSSEC record types and validation algorithms.
151

152
```python { .api }
153
def validate(rrset, rrsigset, keys, origin=None, now=None): ...
154
def validate_rrsig(rrset, rrsig, keys, origin=None, now=None): ...
155
def make_ds(name, key, algorithm, origin=None): ...
156
```
157

158
[DNSSEC](./dnssec.md)
159

160
### Dynamic DNS Updates
161

162
Create and send dynamic DNS update messages with authentication. Support for adding, deleting, and replacing resource records.
163

164
```python { .api }
165
def add(name, *args): ...
166
def delete(name, *args): ...
167
def replace(name, *args): ...
168
def present(name, *args): ...
169
def absent(name, *args): ...
170
```
171

172
[DNS Updates](./dns-updates.md)
173

174
### TSIG Authentication
175

176
Transaction signature support for authenticated DNS messages. Handle key management, signature generation, and verification.
177

178
```python { .api }
179
def sign(wire, keyring, keyname, fudge=300, original_id=None, tsig_error=0): ...
180
def validate(wire, keyring, request_mac, now=None, request_fudge=None): ...
181
```
182

183
[TSIG Authentication](./tsig.md)
184

185
### DNS Constants and Enumerations
186

187
Essential constants for DNS record types, classes, message flags, opcodes, and response codes. These constants are fundamental for all DNS operations and message handling.
188

189
```python { .api }
190
# Record types
191
A = 1
192
NS = 2
193
CNAME = 5
194
SOA = 6
195
MX = 15
196
TXT = 16
197
AAAA = 28
198
SRV = 33
199

200
# Record classes  
201
IN = 1      # Internet
202
CH = 3      # Chaos
203
ANY = 255   # Any class
204

205
# Message flags
206
QR = 0x8000   # Query Response
207
AA = 0x0400   # Authoritative Answer
208
TC = 0x0200   # Truncated
209
RD = 0x0100   # Recursion Desired
210
```
211

212
[DNS Constants](./dns-constants.md)
213

214
### Exception Handling
215

216
Comprehensive exception classes for handling DNS errors, timeouts, validation failures, and operational issues. Essential for robust DNS application development.
217

218
```python { .api }
219
class DNSException(Exception): ...
220
class FormError(DNSException): ...
221
class Timeout(DNSException): ...
222
class NXDOMAIN(DNSException): ...
223
class NoAnswer(DNSException): ...
224
class ValidationFailure(DNSException): ...
225
```
226

227
[DNS Exceptions](./dns-exceptions.md)
228

229
### DNS Utilities
230

231
Utility functions for IP address processing, reverse DNS operations, E.164 number handling, and address family detection. Supporting tools for common DNS operations.
232

233
```python { .api }
234
def from_address(text: str) -> dns.name.Name: ...  # IP to reverse DNS
235
def to_address(name: dns.name.Name) -> str: ...    # Reverse DNS to IP
236
def af_for_address(text: str) -> int: ...          # Address family detection
237
def is_multicast(text: str) -> bool: ...           # Multicast detection
238
```
239

240
[DNS Utilities](./dns-utilities.md)
241

242
## Types
243

244
```python { .api }
245
class DNSException(Exception):
246
    """Base class for all DNS exceptions."""
247

248
class Timeout(DNSException):
249
    """DNS operation timed out."""
250

251
class NXDOMAIN(DNSException):
252
    """Query name does not exist."""
253

254
class NoAnswer(DNSException):
255
    """DNS response contains no answer to the question."""
256

257
class Name:
258
    """An immutable DNS name."""
259
    
260
class Resolver:
261
    """High-level DNS resolver with configurable options."""
262
    
263
class Message:
264
    """A DNS message with header and sections."""
265
    
266
class Zone:
267
    """A DNS zone as a mapping from names to nodes."""
268
```