lib/dnspython/README

   1 dnspython
   2
   3 INTRODUCTION
   4
   5 dnspython is a DNS toolkit for Python. It supports almost all record
   6 types. It can be used for queries, zone transfers, and dynamic
   7 updates.  It supports TSIG authenticated messages and EDNS0.
   8
   9 dnspython provides both high and low level access to DNS. The high
  10 level classes perform queries for data of a given name, type, and
  11 class, and return an answer set.  The low level classes allow direct
  12 manipulation of DNS zones, messages, names, and records.
  13
  14 To see a few of the ways dnspython can be used, look in the examples/
  15 directory.
  16
  17 dnspython originated at Nominum where it was developed to facilitate
  18 the testing of DNS software.  Nominum has generously allowed it to be
  19 open sourced under a BSD-style license, and helps support its future
  20 development by continuing to employ the author :).
  21
  22
  23 ABOUT THIS RELEASE
  24
  25 This is dnspython 1.8.0
  26
  27 New since 1.7.1:
  28
  29         Support for hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384
  30         and hmac-sha512 has been contributed by Kevin Chen.
  31
  32         The tokenizer's tokens are now Token objects instead of (type,
  33         value) tuples.
  34
  35 Bugs fixed since 1.7.1:
  36
  37         Escapes in masterfiles now work correctly.  Previously they
  38         were only working correctly when the text involved was part of
  39         a domain name.
  40
  41         When constructing a DDNS update, if the present() method was
  42         used with a single rdata, a zero TTL was not added.
  43
  44         The entropy pool needed locking to be thread safe.
  45
  46         The entropy pool's reading of /dev/random could cause
  47         dnspython to block.
  48
  49         The entropy pool did buffered reads, potentially consuming more
  50         randomness than we needed.
  51
  52         The entropy pool did not seed with high quality randomness on
  53         Windows.
  54
  55         SRV records were compared incorrectly.
  56
  57         In the e164 query function, the resolver parameter was not
  58         used.
  59
  60 New since 1.7.0:
  61
  62         Nothing
  63
  64 Bugs fixed since 1.7.0:
  65
  66         The 1.7.0 kitting process inadventently omitted the code for the
  67         DLV RR.
  68
  69         Negative DDNS prerequisites are now handled correctly.
  70
  71 New since 1.6.0:
  72
  73         Rdatas now have a to_digestable() method, which returns the
  74         DNSSEC canonical form of the rdata, suitable for use in
  75         signature computations.
  76
  77         The NSEC3, NSEC3PARAM, DLV, and HIP RR types are now supported.
  78
  79         An entropy module has been added and is used to randomize query ids.
  80
  81         EDNS0 options are now supported.
  82
  83         UDP IXFR is now supported.
  84
  85         The wire format parser now has a 'one_rr_per_rrset' mode, which
  86         suppresses the usual coalescing of all RRs of a given type into a
  87         single RRset.
  88
  89         Various helpful DNSSEC-related constants are now defined.
  90
  91         The resolver's query() method now has an optional 'source' parameter,
  92         allowing the source IP address to be specified.
  93
  94 Bugs fixed since 1.6.0:
  95
  96         On Windows, the resolver set the domain incorrectly.
  97
  98         DS RR parsing only allowed one Base64 chunk.
  99
 100         TSIG validation didn't always use absolute names.
 101
 102         NSEC.to_text() only printed the last window.
 103
 104         We did not canonicalize IPv6 addresses before comparing them; we
 105         would thus treat equivalent but different textual forms, e.g.
 106         "1:00::1" and "1::1" as being non-equivalent.
 107
 108         If the peer set a TSIG error, we didn't raise an exception.
 109
 110         Some EDNS bugs in the message code have been fixed (see the ChangeLog
 111         for details).
 112
 113 New since 1.5.0:
 114         Added dns.inet.is_multicast().
 115
 116 Bugs fixed since 1.5.0:
 117
 118         If select() raises an exception due to EINTR, we should just
 119         select() again.
 120
 121         If the queried address is a multicast address, then don't
 122         check that the address of the response is the same as the
 123         address queried.
 124
 125         NAPTR comparisons didn't compare the preference field due to a
 126         typo.
 127
 128         Testing of whether a Windows NIC is enabled now works on Vista
 129         thanks to code contributed by Paul Marks.
 130
 131 New since 1.4.0:
 132
 133         Answer objects now support more of the python sequence
 134         protocol, forwarding the requests to the answer rrset.
 135         E.g. "for a in answer" is equivalent to "for a in
 136         answer.rrset", "answer[i]" is equivalent to "answer.rrset[i]",
 137         and "answer[i:j]" is equivalent to "answer.rrset[i:j]".
 138
 139         Making requests using EDNS, including indicating DNSSEC awareness,
 140         is now easier.  For example, you can now say:
 141
 142            q = dns.message.make_query('www.dnspython.org', 'MX',
 143                                       want_dnssec=True)
 144
 145         dns.query.xfr() can now be used for IXFR.
 146
 147         Support has been added for the DHCID, IPSECKEY, and SPF RR types.
 148
 149         UDP messages from unexpected sources can now be ignored by
 150         setting ignore_unexpected to True when calling dns.query.udp.
 151
 152 Bugs fixed since 1.4.0:
 153
 154         If /etc/resolv.conf didn't exist, we raised an exception
 155         instead of simply using the default resolver configuration.
 156
 157         In dns.resolver.Resolver._config_win32_fromkey(), we were
 158         passing the wrong variable to self._config_win32_search().
 159
 160 New since 1.3.5:
 161
 162         You can now convert E.164 numbers to/from their ENUM name
 163         forms:
 164
 165               >>> import dns.e164
 166               >>> n = dns.e164.from_e164("+1 555 1212")
 167               >>> n
 168               <DNS name 2.1.2.1.5.5.5.1.e164.arpa.>
 169               >>> dns.e164.to_e164(n)
 170               '+15551212'
 171
 172         You can now convert IPv4 and IPv6 address to/from their
 173         corresponding DNS reverse map names:
 174
 175               >>> import dns.reversename
 176               >>> n = dns.reversename.from_address("127.0.0.1")
 177               >>> n
 178               <DNS name 1.0.0.127.in-addr.arpa.>
 179               >>> dns.reversename.to_address(n)
 180               '127.0.0.1'
 181
 182         You can now convert between Unicode strings and their IDN ACE
 183         form:
 184
 185               >>> n = dns.name.from_text(u'les-\u00e9l\u00e8ves.example.')
 186               >>> n
 187               <DNS name xn--les-lves-50ai.example.>
 188               >>> n.to_unicode()
 189               u'les-\xe9l\xe8ves.example.'
 190
 191         The origin parameter to dns.zone.from_text() and dns.zone.to_text()
 192         is now optional.  If not specified, the origin will be taken from
 193         the first $ORIGIN statement in the master file.
 194
 195         Sanity checking of a zone can be disabled; this is useful when
 196         working with files which are zone fragments.
 197
 198 Bugs fixed since 1.3.5:
 199
 200         The correct delimiter was not used when retrieving the
 201         list of nameservers from the registry in certain versions of
 202         windows.
 203
 204         The floating-point version of latitude and longitude in LOC RRs
 205         (float_latitude and float_longitude) had incorrect signs for
 206         south latitudes and west longitudes.
 207
 208         BIND 8 TTL syntax is now accepted in all TTL-like places (i.e.
 209         SOA fields refresh, retry, expire, and minimum; SIG/RRSIG
 210         field original_ttl).
 211
 212         TTLs are now bounds checked when their text form is parsed,
 213         and their values must be in the closed interval [0, 2^31 - 1].
 214
 215 New since 1.3.4:
 216
 217         In the resolver, if time goes backward a little bit, ignore
 218         it.
 219
 220         zone_for_name() has been added to the resolver module.  It
 221         returns the zone which is authoritative for the specified
 222         name, which is handy for dynamic update.  E.g.
 223
 224               import dns.resolver
 225               print dns.resolver.zone_for_name('www.dnspython.org')
 226
 227         will output "dnspython.org." and
 228
 229               print dns.resolver.zone_for_name('a.b.c.d.e.f.example.')
 230
 231         will output ".".
 232
 233         The default resolver can be fetched with the
 234         get_default_resolver() method.
 235
 236         You can now get the parent (immediate superdomain) of a name
 237         by using the parent() method.
 238
 239         Zone.iterate_rdatasets() and Zone.iterate_rdatas() now have
 240         a default rdtype of dns.rdatatype.ANY like the documentation
 241         says.
 242
 243         A Dynamic DNS example, ddns.py, has been added.
 244
 245 New since 1.3.3:
 246
 247         The source address and port may now be specified when calling
 248         dns.query.{udp,tcp,xfr}.
 249
 250         The resolver now does exponential backoff each time it runs
 251         through all of the nameservers.
 252
 253         Rcodes which indicate a nameserver is likely to be a
 254         "permanent failure" for a query cause the nameserver to be removed
 255         from the mix for that query.
 256
 257 New since 1.3.2:
 258
 259         dns.message.Message.find_rrset() now uses an index, vastly
 260         improving the from_wire() performance of large messages such
 261         as zone transfers.
 262
 263         Added dns.message.make_response(), which creates a skeletal
 264         response for the specified query.
 265
 266         Added opcode() and set_opcode() convenience methods to the
 267         dns.message.Message class.  Added the request_payload
 268         attribute to the Message class.
 269
 270         The 'file' parameter of dns.name.Name.to_wire() is now
 271         optional; if omitted, the wire form will be returned as the
 272         value of the function.
 273
 274         dns.zone.from_xfr() in relativization mode incorrectly set
 275         zone.origin to the empty name.
 276
 277         The masterfile parser incorrectly rejected TXT records where a
 278         value was not quoted.
 279
 280 New since 1.3.1:
 281
 282         The NSEC format doesn't allow specifying types by number, so
 283         we shouldn't either.  (Using the unknown type format is still
 284         OK though.)
 285
 286         The resolver wasn't catching dns.exception.Timeout, so a timeout
 287         erroneously caused the whole resolution to fail instead of just
 288         going on to the next server.
 289
 290         The renderer module didn't import random, causing an exception
 291         to be raised if a query id wasn't provided when a Renderer was
 292         created.
 293
 294         The conversion of LOC milliseconds values from text to binary was
 295         incorrect if the length of the milliseconds string was not 3.
 296
 297 New since 1.3.0:
 298
 299         Added support for the SSHFP type.
 300
 301 New since 1.2.0:
 302
 303         Added support for new DNSSEC types RRSIG, NSEC, and DNSKEY.
 304
 305 This release fixes all known bugs.
 306
 307 See the ChangeLog file for more detailed information on changes since
 308 the prior release.
 309
 310
 311 REQUIREMENTS
 312
 313 Python 2.2 or later.
 314
 315
 316 INSTALLATION
 317
 318 To build and install dnspython, type
 319
 320         python setup.py install
 321
 322
 323 HOME PAGE
 324
 325 For the latest in releases, documentation, and information, visit the
 326 dnspython home page at
 327
 328         http://www.dnspython.org/
 329
 330
 331
 332 DOCUMENTATION
 333
 334 Documentation is sparse at the moment.  Use pydoc, or read the HTML
 335 documentation at the dnspython home page, or download the HTML
 336 documentation.
 337
 338
 339 BUG REPORTS
 340
 341 Bug reports may be sent to bugs@dnspython.org
 342
 343
 344 MAILING LISTS
 345
 346 A number of mailing lists are available.  Visit the dnspython home
 347 page to subscribe or unsubscribe.