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
```