0
# DNS Utilities
1

2
Utility modules providing helper functions for address processing, reverse DNS operations, internationalization, and common DNS operations. These modules support the core DNS functionality with specialized tools for working with IP addresses, domain names, and text processing.
3

4
## Capabilities
5

6
### Reverse DNS Name Operations
7

8
Convert between IP addresses and their corresponding reverse DNS names for PTR record lookups.
9

10
```python { .api }  
11
def from_address(text: str) -> dns.name.Name:
12
    """
13
    Convert an IPv4 or IPv6 address to reverse-map domain name.
14
    
15
    Args:
16
        text (str): IPv4 or IPv6 address in textual form (e.g. '127.0.0.1', '::1')
17
        
18
    Returns:
19
        dns.name.Name: Reverse-map domain name (e.g. 1.0.0.127.in-addr.arpa.)
20
        
21
    Raises:
22
        dns.exception.SyntaxError: If address is malformed
23
    """
24

25
def to_address(name: dns.name.Name) -> str:
26
    """
27
    Convert reverse-map domain name back to IP address.
28
    
29
    Args:
30
        name (dns.name.Name): Reverse DNS name
31
        
32
    Returns:
33
        str: IP address in textual form
34
        
35
    Raises:
36
        dns.exception.SyntaxError: If name is not a valid reverse name
37
    """
38

39
# Domain constants
40
ipv4_reverse_domain: dns.name.Name  # in-addr.arpa.
41
ipv6_reverse_domain: dns.name.Name  # ip6.arpa.
42
```
43

44
### Internet Address Utilities
45

46
Low-level address conversion and validation functions for IPv4 and IPv6 addresses.
47

48
```python { .api }
49
def inet_pton(family: int, text: str) -> bytes:
50
    """
51
    Convert text representation of address to binary form.
52
    
53
    Args:
54
        family (int): Address family (socket.AF_INET or socket.AF_INET6)
55
        text (str): Address in text form
56
        
57
    Returns:
58
        bytes: Binary representation of address
59
    """
60

61
def inet_ntop(family: int, address: bytes) -> str:
62
    """
63
    Convert binary address representation to text form.
64
    
65
    Args:
66
        family (int): Address family (socket.AF_INET or socket.AF_INET6)
67
        address (bytes): Binary address representation
68
        
69
    Returns:
70
        str: Address in text form
71
    """
72

73
def af_for_address(text: str) -> int:
74
    """
75
    Determine address family for given address text.
76
    
77
    Args:
78
        text (str): IP address in text form
79
        
80
    Returns:
81
        int: socket.AF_INET for IPv4, socket.AF_INET6 for IPv6
82
        
83
    Raises:
84
        ValueError: If address format is invalid
85
    """
86

87
def is_multicast(text: str) -> bool:
88
    """
89
    Check if address is a multicast address.
90
    
91
    Args:
92
        text (str): IP address in text form
93
        
94
    Returns:
95
        bool: True if address is multicast
96
    """
97
```
98

99
### E.164 Telephone Number Utilities
100

101
Convert between E.164 telephone numbers and their ENUM domain representations.
102

103
```python { .api }
104
def from_e164(text: str, origin: dns.name.Name = dns.name.root) -> dns.name.Name:
105
    """
106
    Convert E.164 number to ENUM domain name.
107
    
108
    Args:
109
        text (str): E.164 number (e.g. '+1 555 1212')
110
        origin (dns.name.Name): ENUM domain origin (default: e164.arpa.)
111
        
112
    Returns:
113
        dns.name.Name: ENUM domain name (e.g. 2.1.2.1.5.5.5.1.e164.arpa.)
114
    """
115

116
def to_e164(name: dns.name.Name, origin: dns.name.Name = dns.name.root, 
117
            want_plus_prefix: bool = True) -> str:
118
    """
119
    Convert ENUM domain name to E.164 number.
120
    
121
    Args:
122
        name (dns.name.Name): ENUM domain name
123
        origin (dns.name.Name): ENUM domain origin
124
        want_plus_prefix (bool): Include '+' prefix in result
125
        
126
    Returns:
127
        str: E.164 number (e.g. '+15551212')
128
    """
129
```
130

131
### IPv4 Address Processing
132

133
Specialized functions for IPv4 address validation and manipulation.
134

135
```python { .api }
136
def inet_aton(text: str) -> bytes:
137
    """
138
    Convert IPv4 address from text to 32-bit binary format.
139
    
140
    Args:
141
        text (str): IPv4 address in dotted decimal notation
142
        
143
    Returns:
144
        bytes: 4-byte binary representation
145
        
146
    Raises:
147
        dns.exception.SyntaxError: If address is invalid
148
    """
149

150
def inet_ntoa(address: bytes) -> str:
151
    """
152
    Convert IPv4 address from binary to text format.
153
    
154
    Args:
155
        address (bytes): 4-byte binary representation
156
        
157
    Returns:
158
        str: IPv4 address in dotted decimal notation
159
    """
160
```
161

162
### IPv6 Address Processing
163

164
Specialized functions for IPv6 address validation, manipulation, and format conversion.
165

166
```python { .api }
167
def inet_aton(text: str) -> bytes:
168
    """
169
    Convert IPv6 address from text to 128-bit binary format.
170
    
171
    Args:
172
        text (str): IPv6 address in standard notation
173
        
174
    Returns:
175
        bytes: 16-byte binary representation
176
        
177
    Raises:
178
        dns.exception.SyntaxError: If address is invalid
179
    """
180

181
def inet_ntoa(address: bytes) -> str:
182
    """
183
    Convert IPv6 address from binary to text format.
184
    
185
    Args:
186
        address (bytes): 16-byte binary representation
187
        
188
    Returns:
189
        str: IPv6 address in standard notation
190
    """
191

192
def is_mapped(address: bytes) -> bool:
193
    """
194
    Check if IPv6 address is IPv4-mapped.
195
    
196
    Args:
197
        address (bytes): 16-byte IPv6 address
198
        
199
    Returns:
200
        bool: True if address is IPv4-mapped (::ffff:x.x.x.x)
201
    """
202
```
203

204
### TTL Processing
205

206
Parse and validate DNS TTL (Time To Live) values from text representations.
207

208
```python { .api }
209
def from_text(text: str) -> int:
210
    """
211
    Convert TTL from text to seconds.
212
    
213
    Supports BIND-style suffixes: s (seconds), m (minutes), 
214
    h (hours), d (days), w (weeks).
215
    
216
    Args:
217
        text (str): TTL in text form (e.g. '1h', '300', '1d2h')
218
        
219
    Returns:
220
        int: TTL in seconds
221
        
222
    Raises:
223
        dns.exception.SyntaxError: If TTL format is invalid
224
    """
225

226
MAX_TTL: int  # Maximum allowed TTL value (2^31 - 1)
227
```
228

229
### EDNS Options
230

231
Handle Extended DNS (EDNS) options for modern DNS features and extensions.
232

233
```python { .api }
234
def get_option_class(otype: int) -> type:
235
    """
236
    Get the option class for the specified option type.
237
    
238
    Args:
239
        otype (int): EDNS option type code
240
        
241
    Returns:
242
        type: Option class for handling this option type
243
    """
244

245
def option_from_wire(otype: int, wire: bytes, current: int, 
246
                    olen: int) -> 'Option':
247
    """
248
    Create an option from wire format data.
249
    
250
    Args:
251
        otype (int): Option type
252
        wire (bytes): Wire format data
253
        current (int): Current position in wire data
254
        olen (int): Option length
255
        
256
    Returns:
257
        Option: Parsed EDNS option
258
    """
259

260
class Option:
261
    """Base class for EDNS options."""
262
    
263
    def __init__(self, otype: int): ...
264
    def to_wire(self, file: Any = None) -> bytes: ...
265
    def from_wire(cls, otype: int, wire: bytes, current: int, olen: int): ...
266
```
267

268
## Usage Examples
269

270
### Reverse DNS Operations
271

272
```python
273
import dns.reversename
274

275
# Convert IP addresses to reverse DNS names
276
ipv4_reverse = dns.reversename.from_address('192.168.1.1')
277
print(ipv4_reverse)  # 1.1.168.192.in-addr.arpa.
278

279
ipv6_reverse = dns.reversename.from_address('2001:db8::1')
280
print(ipv6_reverse)  # 1.0.0.0...0.8.b.d.0.1.0.0.2.ip6.arpa.
281

282
# Convert reverse names back to addresses
283
address = dns.reversename.to_address(ipv4_reverse)
284
print(address)  # 192.168.1.1
285
```
286

287
### Address Family Detection and Validation
288

289
```python
290
import dns.inet
291
import socket
292

293
# Determine address family
294
family = dns.inet.af_for_address('192.168.1.1')  # socket.AF_INET
295
family = dns.inet.af_for_address('::1')           # socket.AF_INET6
296

297
# Check for multicast addresses
298
is_multi = dns.inet.is_multicast('224.0.0.1')    # True (IPv4 multicast)
299
is_multi = dns.inet.is_multicast('ff02::1')      # True (IPv6 multicast)
300

301
# Convert between binary and text
302
binary = dns.inet.inet_pton(socket.AF_INET, '192.168.1.1')
303
text = dns.inet.inet_ntop(socket.AF_INET, binary)
304
```
305

306
### E.164 and ENUM Operations
307

308
```python
309
import dns.e164
310

311
# Convert phone number to ENUM domain
312
enum_name = dns.e164.from_e164('+1 555 1212')
313
print(enum_name)  # 2.1.2.1.5.5.5.1.e164.arpa.
314

315
# Convert ENUM domain back to phone number
316
phone = dns.e164.to_e164(enum_name)
317
print(phone)  # +15551212
318
```
319

320
### TTL Processing
321

322
```python
323
import dns.ttl
324

325
# Parse TTL values with units
326
ttl_seconds = dns.ttl.from_text('1h')      # 3600
327
ttl_seconds = dns.ttl.from_text('30m')     # 1800
328
ttl_seconds = dns.ttl.from_text('1d2h')    # 93600
329
ttl_seconds = dns.ttl.from_text('300')     # 300
330

331
# Maximum TTL validation
332
print(dns.ttl.MAX_TTL)  # 2147483647
333
```
334

335
## Types
336

337
```python { .api }
338
# Reverse name constants
339
ipv4_reverse_domain: dns.name.Name = dns.name.from_text('in-addr.arpa.')
340
ipv6_reverse_domain: dns.name.Name = dns.name.from_text('ip6.arpa.')
341

342
# TTL limits
343
MAX_TTL: int = 2147483647
344

345
# EDNS option base class
346
class Option:
347
    """Base class for all EDNS options."""
348
    otype: int
349
    
350
    def __init__(self, otype: int): ...
351
    def to_wire(self, file: Any = None) -> bytes: ...
352
    def from_wire(cls, otype: int, wire: bytes, current: int, olen: int): ...
353
```