67c952d3cc51016d1fc1ad89fb4a6ca2f9c2c153
[bbaumbach/samba-autobuild/.git] / lib / dnspython / dns / zone.py
1 # Copyright (C) 2003-2007, 2009-2011 Nominum, Inc.
2 #
3 # Permission to use, copy, modify, and distribute this software and its
4 # documentation for any purpose with or without fee is hereby granted,
5 # provided that the above copyright notice and this permission notice
6 # appear in all copies.
7 #
8 # THE SOFTWARE IS PROVIDED "AS IS" AND NOMINUM DISCLAIMS ALL WARRANTIES
9 # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL NOMINUM BE LIABLE FOR
11 # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
14 # OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15
16 """DNS Zones."""
17
18 from __future__ import generators
19
20 import sys
21
22 import dns.exception
23 import dns.name
24 import dns.node
25 import dns.rdataclass
26 import dns.rdatatype
27 import dns.rdata
28 import dns.rrset
29 import dns.tokenizer
30 import dns.ttl
31
32 class BadZone(dns.exception.DNSException):
33     """The zone is malformed."""
34     pass
35
36 class NoSOA(BadZone):
37     """The zone has no SOA RR at its origin."""
38     pass
39
40 class NoNS(BadZone):
41     """The zone has no NS RRset at its origin."""
42     pass
43
44 class UnknownOrigin(BadZone):
45     """The zone's origin is unknown."""
46     pass
47
48 class Zone(object):
49     """A DNS zone.
50
51     A Zone is a mapping from names to nodes.  The zone object may be
52     treated like a Python dictionary, e.g. zone[name] will retrieve
53     the node associated with that name.  The I{name} may be a
54     dns.name.Name object, or it may be a string.  In the either case,
55     if the name is relative it is treated as relative to the origin of
56     the zone.
57
58     @ivar rdclass: The zone's rdata class; the default is class IN.
59     @type rdclass: int
60     @ivar origin: The origin of the zone.
61     @type origin: dns.name.Name object
62     @ivar nodes: A dictionary mapping the names of nodes in the zone to the
63     nodes themselves.
64     @type nodes: dict
65     @ivar relativize: should names in the zone be relativized?
66     @type relativize: bool
67     @cvar node_factory: the factory used to create a new node
68     @type node_factory: class or callable
69     """
70
71     node_factory = dns.node.Node
72
73     __slots__ = ['rdclass', 'origin', 'nodes', 'relativize']
74
75     def __init__(self, origin, rdclass=dns.rdataclass.IN, relativize=True):
76         """Initialize a zone object.
77
78         @param origin: The origin of the zone.
79         @type origin: dns.name.Name object
80         @param rdclass: The zone's rdata class; the default is class IN.
81         @type rdclass: int"""
82
83         self.rdclass = rdclass
84         self.origin = origin
85         self.nodes = {}
86         self.relativize = relativize
87
88     def __eq__(self, other):
89         """Two zones are equal if they have the same origin, class, and
90         nodes.
91         @rtype: bool
92         """
93
94         if not isinstance(other, Zone):
95             return False
96         if self.rdclass != other.rdclass or \
97            self.origin != other.origin or \
98            self.nodes != other.nodes:
99             return False
100         return True
101
102     def __ne__(self, other):
103         """Are two zones not equal?
104         @rtype: bool
105         """
106
107         return not self.__eq__(other)
108
109     def _validate_name(self, name):
110         if isinstance(name, (str, unicode)):
111             name = dns.name.from_text(name, None)
112         elif not isinstance(name, dns.name.Name):
113             raise KeyError("name parameter must be convertable to a DNS name")
114         if name.is_absolute():
115             if not name.is_subdomain(self.origin):
116                 raise KeyError("name parameter must be a subdomain of the zone origin")
117             if self.relativize:
118                 name = name.relativize(self.origin)
119         return name
120
121     def __getitem__(self, key):
122         key = self._validate_name(key)
123         return self.nodes[key]
124
125     def __setitem__(self, key, value):
126         key = self._validate_name(key)
127         self.nodes[key] = value
128
129     def __delitem__(self, key):
130         key = self._validate_name(key)
131         del self.nodes[key]
132
133     def __iter__(self):
134         return self.nodes.iterkeys()
135
136     def iterkeys(self):
137         return self.nodes.iterkeys()
138
139     def keys(self):
140         return self.nodes.keys()
141
142     def itervalues(self):
143         return self.nodes.itervalues()
144
145     def values(self):
146         return self.nodes.values()
147
148     def iteritems(self):
149         return self.nodes.iteritems()
150
151     def items(self):
152         return self.nodes.items()
153
154     def get(self, key):
155         key = self._validate_name(key)
156         return self.nodes.get(key)
157
158     def __contains__(self, other):
159         return other in self.nodes
160
161     def find_node(self, name, create=False):
162         """Find a node in the zone, possibly creating it.
163
164         @param name: the name of the node to find
165         @type name: dns.name.Name object or string
166         @param create: should the node be created if it doesn't exist?
167         @type create: bool
168         @raises KeyError: the name is not known and create was not specified.
169         @rtype: dns.node.Node object
170         """
171
172         name = self._validate_name(name)
173         node = self.nodes.get(name)
174         if node is None:
175             if not create:
176                 raise KeyError
177             node = self.node_factory()
178             self.nodes[name] = node
179         return node
180
181     def get_node(self, name, create=False):
182         """Get a node in the zone, possibly creating it.
183
184         This method is like L{find_node}, except it returns None instead
185         of raising an exception if the node does not exist and creation
186         has not been requested.
187
188         @param name: the name of the node to find
189         @type name: dns.name.Name object or string
190         @param create: should the node be created if it doesn't exist?
191         @type create: bool
192         @rtype: dns.node.Node object or None
193         """
194
195         try:
196             node = self.find_node(name, create)
197         except KeyError:
198             node = None
199         return node
200
201     def delete_node(self, name):
202         """Delete the specified node if it exists.
203
204         It is not an error if the node does not exist.
205         """
206
207         name = self._validate_name(name)
208         if self.nodes.has_key(name):
209             del self.nodes[name]
210
211     def find_rdataset(self, name, rdtype, covers=dns.rdatatype.NONE,
212                       create=False):
213         """Look for rdata with the specified name and type in the zone,
214         and return an rdataset encapsulating it.
215
216         The I{name}, I{rdtype}, and I{covers} parameters may be
217         strings, in which case they will be converted to their proper
218         type.
219
220         The rdataset returned is not a copy; changes to it will change
221         the zone.
222
223         KeyError is raised if the name or type are not found.
224         Use L{get_rdataset} if you want to have None returned instead.
225
226         @param name: the owner name to look for
227         @type name: DNS.name.Name object or string
228         @param rdtype: the rdata type desired
229         @type rdtype: int or string
230         @param covers: the covered type (defaults to None)
231         @type covers: int or string
232         @param create: should the node and rdataset be created if they do not
233         exist?
234         @type create: bool
235         @raises KeyError: the node or rdata could not be found
236         @rtype: dns.rrset.RRset object
237         """
238
239         name = self._validate_name(name)
240         if isinstance(rdtype, (str, unicode)):
241             rdtype = dns.rdatatype.from_text(rdtype)
242         if isinstance(covers, (str, unicode)):
243             covers = dns.rdatatype.from_text(covers)
244         node = self.find_node(name, create)
245         return node.find_rdataset(self.rdclass, rdtype, covers, create)
246
247     def get_rdataset(self, name, rdtype, covers=dns.rdatatype.NONE,
248                      create=False):
249         """Look for rdata with the specified name and type in the zone,
250         and return an rdataset encapsulating it.
251
252         The I{name}, I{rdtype}, and I{covers} parameters may be
253         strings, in which case they will be converted to their proper
254         type.
255
256         The rdataset returned is not a copy; changes to it will change
257         the zone.
258
259         None is returned if the name or type are not found.
260         Use L{find_rdataset} if you want to have KeyError raised instead.
261
262         @param name: the owner name to look for
263         @type name: DNS.name.Name object or string
264         @param rdtype: the rdata type desired
265         @type rdtype: int or string
266         @param covers: the covered type (defaults to None)
267         @type covers: int or string
268         @param create: should the node and rdataset be created if they do not
269         exist?
270         @type create: bool
271         @rtype: dns.rrset.RRset object
272         """
273
274         try:
275             rdataset = self.find_rdataset(name, rdtype, covers, create)
276         except KeyError:
277             rdataset = None
278         return rdataset
279
280     def delete_rdataset(self, name, rdtype, covers=dns.rdatatype.NONE):
281         """Delete the rdataset matching I{rdtype} and I{covers}, if it
282         exists at the node specified by I{name}.
283
284         The I{name}, I{rdtype}, and I{covers} parameters may be
285         strings, in which case they will be converted to their proper
286         type.
287
288         It is not an error if the node does not exist, or if there is no
289         matching rdataset at the node.
290
291         If the node has no rdatasets after the deletion, it will itself
292         be deleted.
293
294         @param name: the owner name to look for
295         @type name: DNS.name.Name object or string
296         @param rdtype: the rdata type desired
297         @type rdtype: int or string
298         @param covers: the covered type (defaults to None)
299         @type covers: int or string
300         """
301
302         name = self._validate_name(name)
303         if isinstance(rdtype, (str, unicode)):
304             rdtype = dns.rdatatype.from_text(rdtype)
305         if isinstance(covers, (str, unicode)):
306             covers = dns.rdatatype.from_text(covers)
307         node = self.get_node(name)
308         if not node is None:
309             node.delete_rdataset(self.rdclass, rdtype, covers)
310             if len(node) == 0:
311                 self.delete_node(name)
312
313     def replace_rdataset(self, name, replacement):
314         """Replace an rdataset at name.
315
316         It is not an error if there is no rdataset matching I{replacement}.
317
318         Ownership of the I{replacement} object is transferred to the zone;
319         in other words, this method does not store a copy of I{replacement}
320         at the node, it stores I{replacement} itself.
321
322         If the I{name} node does not exist, it is created.
323
324         @param name: the owner name
325         @type name: DNS.name.Name object or string
326         @param replacement: the replacement rdataset
327         @type replacement: dns.rdataset.Rdataset
328         """
329
330         if replacement.rdclass != self.rdclass:
331             raise ValueError('replacement.rdclass != zone.rdclass')
332         node = self.find_node(name, True)
333         node.replace_rdataset(replacement)
334
335     def find_rrset(self, name, rdtype, covers=dns.rdatatype.NONE):
336         """Look for rdata with the specified name and type in the zone,
337         and return an RRset encapsulating it.
338
339         The I{name}, I{rdtype}, and I{covers} parameters may be
340         strings, in which case they will be converted to their proper
341         type.
342
343         This method is less efficient than the similar
344         L{find_rdataset} because it creates an RRset instead of
345         returning the matching rdataset.  It may be more convenient
346         for some uses since it returns an object which binds the owner
347         name to the rdata.
348
349         This method may not be used to create new nodes or rdatasets;
350         use L{find_rdataset} instead.
351
352         KeyError is raised if the name or type are not found.
353         Use L{get_rrset} if you want to have None returned instead.
354
355         @param name: the owner name to look for
356         @type name: DNS.name.Name object or string
357         @param rdtype: the rdata type desired
358         @type rdtype: int or string
359         @param covers: the covered type (defaults to None)
360         @type covers: int or string
361         @raises KeyError: the node or rdata could not be found
362         @rtype: dns.rrset.RRset object
363         """
364
365         name = self._validate_name(name)
366         if isinstance(rdtype, (str, unicode)):
367             rdtype = dns.rdatatype.from_text(rdtype)
368         if isinstance(covers, (str, unicode)):
369             covers = dns.rdatatype.from_text(covers)
370         rdataset = self.nodes[name].find_rdataset(self.rdclass, rdtype, covers)
371         rrset = dns.rrset.RRset(name, self.rdclass, rdtype, covers)
372         rrset.update(rdataset)
373         return rrset
374
375     def get_rrset(self, name, rdtype, covers=dns.rdatatype.NONE):
376         """Look for rdata with the specified name and type in the zone,
377         and return an RRset encapsulating it.
378
379         The I{name}, I{rdtype}, and I{covers} parameters may be
380         strings, in which case they will be converted to their proper
381         type.
382
383         This method is less efficient than the similar L{get_rdataset}
384         because it creates an RRset instead of returning the matching
385         rdataset.  It may be more convenient for some uses since it
386         returns an object which binds the owner name to the rdata.
387
388         This method may not be used to create new nodes or rdatasets;
389         use L{find_rdataset} instead.
390
391         None is returned if the name or type are not found.
392         Use L{find_rrset} if you want to have KeyError raised instead.
393
394         @param name: the owner name to look for
395         @type name: DNS.name.Name object or string
396         @param rdtype: the rdata type desired
397         @type rdtype: int or string
398         @param covers: the covered type (defaults to None)
399         @type covers: int or string
400         @rtype: dns.rrset.RRset object
401         """
402
403         try:
404             rrset = self.find_rrset(name, rdtype, covers)
405         except KeyError:
406             rrset = None
407         return rrset
408
409     def iterate_rdatasets(self, rdtype=dns.rdatatype.ANY,
410                           covers=dns.rdatatype.NONE):
411         """Return a generator which yields (name, rdataset) tuples for
412         all rdatasets in the zone which have the specified I{rdtype}
413         and I{covers}.  If I{rdtype} is dns.rdatatype.ANY, the default,
414         then all rdatasets will be matched.
415
416         @param rdtype: int or string
417         @type rdtype: int or string
418         @param covers: the covered type (defaults to None)
419         @type covers: int or string
420         """
421
422         if isinstance(rdtype, (str, unicode)):
423             rdtype = dns.rdatatype.from_text(rdtype)
424         if isinstance(covers, (str, unicode)):
425             covers = dns.rdatatype.from_text(covers)
426         for (name, node) in self.iteritems():
427             for rds in node:
428                 if rdtype == dns.rdatatype.ANY or \
429                    (rds.rdtype == rdtype and rds.covers == covers):
430                     yield (name, rds)
431
432     def iterate_rdatas(self, rdtype=dns.rdatatype.ANY,
433                        covers=dns.rdatatype.NONE):
434         """Return a generator which yields (name, ttl, rdata) tuples for
435         all rdatas in the zone which have the specified I{rdtype}
436         and I{covers}.  If I{rdtype} is dns.rdatatype.ANY, the default,
437         then all rdatas will be matched.
438
439         @param rdtype: int or string
440         @type rdtype: int or string
441         @param covers: the covered type (defaults to None)
442         @type covers: int or string
443         """
444
445         if isinstance(rdtype, (str, unicode)):
446             rdtype = dns.rdatatype.from_text(rdtype)
447         if isinstance(covers, (str, unicode)):
448             covers = dns.rdatatype.from_text(covers)
449         for (name, node) in self.iteritems():
450             for rds in node:
451                 if rdtype == dns.rdatatype.ANY or \
452                    (rds.rdtype == rdtype and rds.covers == covers):
453                     for rdata in rds:
454                         yield (name, rds.ttl, rdata)
455
456     def to_file(self, f, sorted=True, relativize=True, nl=None):
457         """Write a zone to a file.
458
459         @param f: file or string.  If I{f} is a string, it is treated
460         as the name of a file to open.
461         @param sorted: if True, the file will be written with the
462         names sorted in DNSSEC order from least to greatest.  Otherwise
463         the names will be written in whatever order they happen to have
464         in the zone's dictionary.
465         @param relativize: if True, domain names in the output will be
466         relativized to the zone's origin (if possible).
467         @type relativize: bool
468         @param nl: The end of line string.  If not specified, the
469         output will use the platform's native end-of-line marker (i.e.
470         LF on POSIX, CRLF on Windows, CR on Macintosh).
471         @type nl: string or None
472         """
473
474         if sys.hexversion >= 0x02030000:
475             # allow Unicode filenames
476             str_type = basestring
477         else:
478             str_type = str
479         if nl is None:
480             opts = 'w'
481         else:
482             opts = 'wb'
483         if isinstance(f, str_type):
484             f = file(f, opts)
485             want_close = True
486         else:
487             want_close = False
488         try:
489             if sorted:
490                 names = self.keys()
491                 names.sort()
492             else:
493                 names = self.iterkeys()
494             for n in names:
495                 l = self[n].to_text(n, origin=self.origin,
496                                     relativize=relativize)
497                 if nl is None:
498                     print >> f, l
499                 else:
500                     f.write(l)
501                     f.write(nl)
502         finally:
503             if want_close:
504                 f.close()
505
506     def check_origin(self):
507         """Do some simple checking of the zone's origin.
508
509         @raises dns.zone.NoSOA: there is no SOA RR
510         @raises dns.zone.NoNS: there is no NS RRset
511         @raises KeyError: there is no origin node
512         """
513         if self.relativize:
514             name = dns.name.empty
515         else:
516             name = self.origin
517         if self.get_rdataset(name, dns.rdatatype.SOA) is None:
518             raise NoSOA
519         if self.get_rdataset(name, dns.rdatatype.NS) is None:
520             raise NoNS
521
522
523 class _MasterReader(object):
524     """Read a DNS master file
525
526     @ivar tok: The tokenizer
527     @type tok: dns.tokenizer.Tokenizer object
528     @ivar ttl: The default TTL
529     @type ttl: int
530     @ivar last_name: The last name read
531     @type last_name: dns.name.Name object
532     @ivar current_origin: The current origin
533     @type current_origin: dns.name.Name object
534     @ivar relativize: should names in the zone be relativized?
535     @type relativize: bool
536     @ivar zone: the zone
537     @type zone: dns.zone.Zone object
538     @ivar saved_state: saved reader state (used when processing $INCLUDE)
539     @type saved_state: list of (tokenizer, current_origin, last_name, file)
540     tuples.
541     @ivar current_file: the file object of the $INCLUDed file being parsed
542     (None if no $INCLUDE is active).
543     @ivar allow_include: is $INCLUDE allowed?
544     @type allow_include: bool
545     @ivar check_origin: should sanity checks of the origin node be done?
546     The default is True.
547     @type check_origin: bool
548     """
549
550     def __init__(self, tok, origin, rdclass, relativize, zone_factory=Zone,
551                  allow_include=False, check_origin=True):
552         if isinstance(origin, (str, unicode)):
553             origin = dns.name.from_text(origin)
554         self.tok = tok
555         self.current_origin = origin
556         self.relativize = relativize
557         self.ttl = 0
558         self.last_name = None
559         self.zone = zone_factory(origin, rdclass, relativize=relativize)
560         self.saved_state = []
561         self.current_file = None
562         self.allow_include = allow_include
563         self.check_origin = check_origin
564
565     def _eat_line(self):
566         while 1:
567             token = self.tok.get()
568             if token.is_eol_or_eof():
569                 break
570
571     def _rr_line(self):
572         """Process one line from a DNS master file."""
573         # Name
574         if self.current_origin is None:
575             raise UnknownOrigin
576         token = self.tok.get(want_leading = True)
577         if not token.is_whitespace():
578             self.last_name = dns.name.from_text(token.value, self.current_origin)
579         else:
580             token = self.tok.get()
581             if token.is_eol_or_eof():
582                 # treat leading WS followed by EOL/EOF as if they were EOL/EOF.
583                 return
584             self.tok.unget(token)
585         name = self.last_name
586         if not name.is_subdomain(self.zone.origin):
587             self._eat_line()
588             return
589         if self.relativize:
590             name = name.relativize(self.zone.origin)
591         token = self.tok.get()
592         if not token.is_identifier():
593             raise dns.exception.SyntaxError
594         # TTL
595         try:
596             ttl = dns.ttl.from_text(token.value)
597             token = self.tok.get()
598             if not token.is_identifier():
599                 raise dns.exception.SyntaxError
600         except dns.ttl.BadTTL:
601             ttl = self.ttl
602         # Class
603         try:
604             rdclass = dns.rdataclass.from_text(token.value)
605             token = self.tok.get()
606             if not token.is_identifier():
607                 raise dns.exception.SyntaxError
608         except dns.exception.SyntaxError:
609             raise dns.exception.SyntaxError
610         except:
611             rdclass = self.zone.rdclass
612         if rdclass != self.zone.rdclass:
613             raise dns.exception.SyntaxError("RR class is not zone's class")
614         # Type
615         try:
616             rdtype = dns.rdatatype.from_text(token.value)
617         except:
618             raise dns.exception.SyntaxError("unknown rdatatype '%s'" % token.value)
619         n = self.zone.nodes.get(name)
620         if n is None:
621             n = self.zone.node_factory()
622             self.zone.nodes[name] = n
623         try:
624             rd = dns.rdata.from_text(rdclass, rdtype, self.tok,
625                                      self.current_origin, False)
626         except dns.exception.SyntaxError:
627             # Catch and reraise.
628             (ty, va) = sys.exc_info()[:2]
629             raise va
630         except:
631             # All exceptions that occur in the processing of rdata
632             # are treated as syntax errors.  This is not strictly
633             # correct, but it is correct almost all of the time.
634             # We convert them to syntax errors so that we can emit
635             # helpful filename:line info.
636             (ty, va) = sys.exc_info()[:2]
637             raise dns.exception.SyntaxError("caught exception %s: %s" % (str(ty), str(va)))
638
639         rd.choose_relativity(self.zone.origin, self.relativize)
640         covers = rd.covers()
641         rds = n.find_rdataset(rdclass, rdtype, covers, True)
642         rds.add(rd, ttl)
643
644     def read(self):
645         """Read a DNS master file and build a zone object.
646
647         @raises dns.zone.NoSOA: No SOA RR was found at the zone origin
648         @raises dns.zone.NoNS: No NS RRset was found at the zone origin
649         """
650
651         try:
652             while 1:
653                 token = self.tok.get(True, True).unescape()
654                 if token.is_eof():
655                     if not self.current_file is None:
656                         self.current_file.close()
657                     if len(self.saved_state) > 0:
658                         (self.tok,
659                          self.current_origin,
660                          self.last_name,
661                          self.current_file,
662                          self.ttl) = self.saved_state.pop(-1)
663                         continue
664                     break
665                 elif token.is_eol():
666                     continue
667                 elif token.is_comment():
668                     self.tok.get_eol()
669                     continue
670                 elif token.value[0] == '$':
671                     u = token.value.upper()
672                     if u == '$TTL':
673                         token = self.tok.get()
674                         if not token.is_identifier():
675                             raise dns.exception.SyntaxError("bad $TTL")
676                         self.ttl = dns.ttl.from_text(token.value)
677                         self.tok.get_eol()
678                     elif u == '$ORIGIN':
679                         self.current_origin = self.tok.get_name()
680                         self.tok.get_eol()
681                         if self.zone.origin is None:
682                             self.zone.origin = self.current_origin
683                     elif u == '$INCLUDE' and self.allow_include:
684                         token = self.tok.get()
685                         if not token.is_quoted_string():
686                             raise dns.exception.SyntaxError("bad filename in $INCLUDE")
687                         filename = token.value
688                         token = self.tok.get()
689                         if token.is_identifier():
690                             new_origin = dns.name.from_text(token.value, \
691                                                             self.current_origin)
692                             self.tok.get_eol()
693                         elif not token.is_eol_or_eof():
694                             raise dns.exception.SyntaxError("bad origin in $INCLUDE")
695                         else:
696                             new_origin = self.current_origin
697                         self.saved_state.append((self.tok,
698                                                  self.current_origin,
699                                                  self.last_name,
700                                                  self.current_file,
701                                                  self.ttl))
702                         self.current_file = file(filename, 'r')
703                         self.tok = dns.tokenizer.Tokenizer(self.current_file,
704                                                            filename)
705                         self.current_origin = new_origin
706                     else:
707                         raise dns.exception.SyntaxError("Unknown master file directive '" + u + "'")
708                     continue
709                 self.tok.unget(token)
710                 self._rr_line()
711         except dns.exception.SyntaxError, detail:
712             (filename, line_number) = self.tok.where()
713             if detail is None:
714                 detail = "syntax error"
715             raise dns.exception.SyntaxError("%s:%d: %s" % (filename, line_number, detail))
716
717         # Now that we're done reading, do some basic checking of the zone.
718         if self.check_origin:
719             self.zone.check_origin()
720
721 def from_text(text, origin = None, rdclass = dns.rdataclass.IN,
722               relativize = True, zone_factory=Zone, filename=None,
723               allow_include=False, check_origin=True):
724     """Build a zone object from a master file format string.
725
726     @param text: the master file format input
727     @type text: string.
728     @param origin: The origin of the zone; if not specified, the first
729     $ORIGIN statement in the master file will determine the origin of the
730     zone.
731     @type origin: dns.name.Name object or string
732     @param rdclass: The zone's rdata class; the default is class IN.
733     @type rdclass: int
734     @param relativize: should names be relativized?  The default is True
735     @type relativize: bool
736     @param zone_factory: The zone factory to use
737     @type zone_factory: function returning a Zone
738     @param filename: The filename to emit when describing where an error
739     occurred; the default is '<string>'.
740     @type filename: string
741     @param allow_include: is $INCLUDE allowed?
742     @type allow_include: bool
743     @param check_origin: should sanity checks of the origin node be done?
744     The default is True.
745     @type check_origin: bool
746     @raises dns.zone.NoSOA: No SOA RR was found at the zone origin
747     @raises dns.zone.NoNS: No NS RRset was found at the zone origin
748     @rtype: dns.zone.Zone object
749     """
750
751     # 'text' can also be a file, but we don't publish that fact
752     # since it's an implementation detail.  The official file
753     # interface is from_file().
754
755     if filename is None:
756         filename = '<string>'
757     tok = dns.tokenizer.Tokenizer(text, filename)
758     reader = _MasterReader(tok, origin, rdclass, relativize, zone_factory,
759                            allow_include=allow_include,
760                            check_origin=check_origin)
761     reader.read()
762     return reader.zone
763
764 def from_file(f, origin = None, rdclass = dns.rdataclass.IN,
765               relativize = True, zone_factory=Zone, filename=None,
766               allow_include=True, check_origin=True):
767     """Read a master file and build a zone object.
768
769     @param f: file or string.  If I{f} is a string, it is treated
770     as the name of a file to open.
771     @param origin: The origin of the zone; if not specified, the first
772     $ORIGIN statement in the master file will determine the origin of the
773     zone.
774     @type origin: dns.name.Name object or string
775     @param rdclass: The zone's rdata class; the default is class IN.
776     @type rdclass: int
777     @param relativize: should names be relativized?  The default is True
778     @type relativize: bool
779     @param zone_factory: The zone factory to use
780     @type zone_factory: function returning a Zone
781     @param filename: The filename to emit when describing where an error
782     occurred; the default is '<file>', or the value of I{f} if I{f} is a
783     string.
784     @type filename: string
785     @param allow_include: is $INCLUDE allowed?
786     @type allow_include: bool
787     @param check_origin: should sanity checks of the origin node be done?
788     The default is True.
789     @type check_origin: bool
790     @raises dns.zone.NoSOA: No SOA RR was found at the zone origin
791     @raises dns.zone.NoNS: No NS RRset was found at the zone origin
792     @rtype: dns.zone.Zone object
793     """
794
795     if sys.hexversion >= 0x02030000:
796         # allow Unicode filenames; turn on universal newline support
797         str_type = basestring
798         opts = 'rU'
799     else:
800         str_type = str
801         opts = 'r'
802     if isinstance(f, str_type):
803         if filename is None:
804             filename = f
805         f = file(f, opts)
806         want_close = True
807     else:
808         if filename is None:
809             filename = '<file>'
810         want_close = False
811
812     try:
813         z = from_text(f, origin, rdclass, relativize, zone_factory,
814                       filename, allow_include, check_origin)
815     finally:
816         if want_close:
817             f.close()
818     return z
819
820 def from_xfr(xfr, zone_factory=Zone, relativize=True):
821     """Convert the output of a zone transfer generator into a zone object.
822
823     @param xfr: The xfr generator
824     @type xfr: generator of dns.message.Message objects
825     @param relativize: should names be relativized?  The default is True.
826     It is essential that the relativize setting matches the one specified
827     to dns.query.xfr().
828     @type relativize: bool
829     @raises dns.zone.NoSOA: No SOA RR was found at the zone origin
830     @raises dns.zone.NoNS: No NS RRset was found at the zone origin
831     @rtype: dns.zone.Zone object
832     """
833
834     z = None
835     for r in xfr:
836         if z is None:
837             if relativize:
838                 origin = r.origin
839             else:
840                 origin = r.answer[0].name
841             rdclass = r.answer[0].rdclass
842             z = zone_factory(origin, rdclass, relativize=relativize)
843         for rrset in r.answer:
844             znode = z.nodes.get(rrset.name)
845             if not znode:
846                 znode = z.node_factory()
847                 z.nodes[rrset.name] = znode
848             zrds = znode.find_rdataset(rrset.rdclass, rrset.rdtype,
849                                        rrset.covers, True)
850             zrds.update_ttl(rrset.ttl)
851             for rd in rrset:
852                 rd.choose_relativity(z.origin, relativize)
853                 zrds.add(rd)
854     z.check_origin()
855     return z