git.samba.org - third_party/dnspython/blob - 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.6.0.
  26
  27 New since 1.5.0:
  28         Added dns.inet.is_multicast().
  29
  30 Bugs fixed since 1.5.0:
  31
  32         If select() raises an exception due to EINTR, we should just
  33         select() again.
  34
  35         If the queried address is a multicast address, then don't
  36         check that the address of the response is the same as the
  37         address queried.
  38
  39         NAPTR comparisons didn't compare the preference field due to a
  40         typo.
  41
  42         Testing of whether a Windows NIC is enabled now works on Vista
  43         thanks to code contributed by Paul Marks.
  44
  45 New since 1.4.0:
  46
  47         Answer objects now support more of the python sequence
  48         protocol, forwarding the requests to the answer rrset.
  49         E.g. "for a in answer" is equivalent to "for a in
  50         answer.rrset", "answer[i]" is equivalent to "answer.rrset[i]",
  51         and "answer[i:j]" is equivalent to "answer.rrset[i:j]".
  52
  53         Making requests using EDNS, including indicating DNSSEC awareness,
  54         is now easier.  For example, you can now say:
  55
  56            q = dns.message.make_query('www.dnspython.org', 'MX',
  57                                       want_dnssec=True)
  58
  59         dns.query.xfr() can now be used for IXFR.
  60
  61         Support has been added for the DHCID, IPSECKEY, and SPF RR types.
  62
  63         UDP messages from unexpected sources can now be ignored by
  64         setting ignore_unexpected to True when calling dns.query.udp.
  65
  66 Bugs fixed since 1.4.0:
  67
  68         If /etc/resolv.conf didn't exist, we raised an exception
  69         instead of simply using the default resolver configuration.
  70
  71         In dns.resolver.Resolver._config_win32_fromkey(), we were
  72         passing the wrong variable to self._config_win32_search().
  73
  74 New since 1.3.5:
  75
  76         You can now convert E.164 numbers to/from their ENUM name
  77         forms:
  78
  79               >>> import dns.e164
  80               >>> n = dns.e164.from_e164("+1 555 1212")
  81               >>> n
  82               <DNS name 2.1.2.1.5.5.5.1.e164.arpa.>
  83               >>> dns.e164.to_e164(n)
  84               '+15551212'
  85
  86         You can now convert IPv4 and IPv6 address to/from their
  87         corresponding DNS reverse map names:
  88
  89               >>> import dns.reversename
  90               >>> n = dns.reversename.from_address("127.0.0.1")
  91               >>> n
  92               <DNS name 1.0.0.127.in-addr.arpa.>
  93               >>> dns.reversename.to_address(n)
  94               '127.0.0.1'
  95
  96         You can now convert between Unicode strings and their IDN ACE
  97         form:
  98
  99               >>> n = dns.name.from_text(u'les-\u00e9l\u00e8ves.example.')
 100               >>> n
 101               <DNS name xn--les-lves-50ai.example.>
 102               >>> n.to_unicode()
 103               u'les-\xe9l\xe8ves.example.'
 104
 105         The origin parameter to dns.zone.from_text() and dns.zone.to_text()
 106         is now optional.  If not specified, the origin will be taken from
 107         the first $ORIGIN statement in the master file.
 108
 109         Sanity checking of a zone can be disabled; this is useful when
 110         working with files which are zone fragments.
 111
 112 Bugs fixed since 1.3.5:
 113
 114         The correct delimiter was not used when retrieving the
 115         list of nameservers from the registry in certain versions of
 116         windows.
 117
 118         The floating-point version of latitude and longitude in LOC RRs
 119         (float_latitude and float_longitude) had incorrect signs for
 120         south latitudes and west longitudes.
 121
 122         BIND 8 TTL syntax is now accepted in all TTL-like places (i.e.
 123         SOA fields refresh, retry, expire, and minimum; SIG/RRSIG
 124         field original_ttl).
 125
 126         TTLs are now bounds checked when their text form is parsed,
 127         and their values must be in the closed interval [0, 2^31 - 1].
 128
 129 New since 1.3.4:
 130
 131         In the resolver, if time goes backward a little bit, ignore
 132         it.
 133
 134         zone_for_name() has been added to the resolver module.  It
 135         returns the zone which is authoritative for the specified
 136         name, which is handy for dynamic update.  E.g.
 137
 138               import dns.resolver
 139               print dns.resolver.zone_for_name('www.dnspython.org')
 140
 141         will output "dnspython.org." and
 142
 143               print dns.resolver.zone_for_name('a.b.c.d.e.f.example.')
 144
 145         will output ".".
 146
 147         The default resolver can be fetched with the
 148         get_default_resolver() method.
 149
 150         You can now get the parent (immediate superdomain) of a name
 151         by using the parent() method.
 152
 153         Zone.iterate_rdatasets() and Zone.iterate_rdatas() now have
 154         a default rdtype of dns.rdatatype.ANY like the documentation
 155         says.
 156
 157         A Dynamic DNS example, ddns.py, has been added.
 158
 159 New since 1.3.3:
 160
 161         The source address and port may now be specified when calling
 162         dns.query.{udp,tcp,xfr}.
 163
 164         The resolver now does exponential backoff each time it runs
 165         through all of the nameservers.
 166
 167         Rcodes which indicate a nameserver is likely to be a
 168         "permanent failure" for a query cause the nameserver to be removed
 169         from the mix for that query.
 170
 171 New since 1.3.2:
 172
 173         dns.message.Message.find_rrset() now uses an index, vastly
 174         improving the from_wire() performance of large messages such
 175         as zone transfers.
 176
 177         Added dns.message.make_response(), which creates a skeletal
 178         response for the specified query.
 179
 180         Added opcode() and set_opcode() convenience methods to the
 181         dns.message.Message class.  Added the request_payload
 182         attribute to the Message class.
 183
 184         The 'file' parameter of dns.name.Name.to_wire() is now
 185         optional; if omitted, the wire form will be returned as the
 186         value of the function.
 187
 188         dns.zone.from_xfr() in relativization mode incorrectly set
 189         zone.origin to the empty name.
 190
 191         The masterfile parser incorrectly rejected TXT records where a
 192         value was not quoted.
 193
 194 New since 1.3.1:
 195
 196         The NSEC format doesn't allow specifying types by number, so
 197         we shouldn't either.  (Using the unknown type format is still
 198         OK though.)
 199
 200         The resolver wasn't catching dns.exception.Timeout, so a timeout
 201         erroneously caused the whole resolution to fail instead of just
 202         going on to the next server.
 203
 204         The renderer module didn't import random, causing an exception
 205         to be raised if a query id wasn't provided when a Renderer was
 206         created.
 207
 208         The conversion of LOC milliseconds values from text to binary was
 209         incorrect if the length of the milliseconds string was not 3.
 210
 211 New since 1.3.0:
 212
 213         Added support for the SSHFP type.
 214
 215 New since 1.2.0:
 216
 217         Added support for new DNSSEC types RRSIG, NSEC, and DNSKEY.
 218
 219 This release fixes all known bugs.
 220
 221 See the ChangeLog file for more detailed information on changes since
 222 the prior release.
 223
 224
 225 REQUIREMENTS
 226
 227 Python 2.2 or later.
 228
 229
 230 INSTALLATION
 231
 232 To build and install dnspython, type
 233
 234         python setup.py install
 235
 236
 237 HOME PAGE
 238
 239 For the latest in releases, documentation, and information, visit the
 240 dnspython home page at
 241
 242         http://www.dnspython.org/
 243
 244
 245
 246 DOCUMENTATION
 247
 248 Documentation is sparse at the moment.  Use pydoc, or read the HTML
 249 documentation at the dnspython home page, or download the HTML
 250 documentation.
 251
 252
 253 BUG REPORTS
 254
 255 Bug reports may be sent to bugs@dnspython.org
 256
 257
 258 MAILING LISTS
 259
 260 A number of mailing lists are available.  Visit the dnspython home
 261 page to subscribe or unsubscribe.