-# Copyright (C) 2001-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2001-2017 Nominum, Inc.
#
# Permission to use, copy, modify, and distribute this software and its
# documentation for any purpose with or without fee is hereby granted,
class DifferingCovers(dns.exception.DNSException):
-
"""An attempt was made to add a DNS SIG/RRSIG whose covered type
is not the same as that of the other rdatas in the rdataset."""
class IncompatibleTypes(dns.exception.DNSException):
-
"""An attempt was made to add DNS RR data of an incompatible type."""
class Rdataset(dns.set.Set):
- """A DNS rdataset.
-
- @ivar rdclass: The class of the rdataset
- @type rdclass: int
- @ivar rdtype: The type of the rdataset
- @type rdtype: int
- @ivar covers: The covered type. Usually this value is
- dns.rdatatype.NONE, but if the rdtype is dns.rdatatype.SIG or
- dns.rdatatype.RRSIG, then the covers value will be the rdata
- type the SIG/RRSIG covers. The library treats the SIG and RRSIG
- types as if they were a family of
- types, e.g. RRSIG(A), RRSIG(NS), RRSIG(SOA). This makes RRSIGs much
- easier to work with than if RRSIGs covering different rdata
- types were aggregated into a single RRSIG rdataset.
- @type covers: int
- @ivar ttl: The DNS TTL (Time To Live) value
- @type ttl: int
- """
+ """A DNS rdataset."""
__slots__ = ['rdclass', 'rdtype', 'covers', 'ttl']
- def __init__(self, rdclass, rdtype, covers=dns.rdatatype.NONE):
+ def __init__(self, rdclass, rdtype, covers=dns.rdatatype.NONE, ttl=0):
"""Create a new rdataset of the specified class and type.
- @see: the description of the class instance variables for the
- meaning of I{rdclass} and I{rdtype}"""
+ *rdclass*, an ``int``, the rdataclass.
+
+ *rdtype*, an ``int``, the rdatatype.
+
+ *covers*, an ``int``, the covered rdatatype.
+
+ *ttl*, an ``int``, the TTL.
+ """
super(Rdataset, self).__init__()
self.rdclass = rdclass
self.rdtype = rdtype
self.covers = covers
- self.ttl = 0
+ self.ttl = ttl
def _clone(self):
obj = super(Rdataset, self)._clone()
return obj
def update_ttl(self, ttl):
- """Set the TTL of the rdataset to be the lesser of the set's current
+ """Perform TTL minimization.
+
+ Set the TTL of the rdataset to be the lesser of the set's current
TTL or the specified TTL. If the set contains no rdatas, set the TTL
to the specified TTL.
- @param ttl: The TTL
- @type ttl: int"""
+
+ *ttl*, an ``int``.
+ """
if len(self) == 0:
self.ttl = ttl
def add(self, rd, ttl=None):
"""Add the specified rdata to the rdataset.
- If the optional I{ttl} parameter is supplied, then
- self.update_ttl(ttl) will be called prior to adding the rdata.
+ If the optional *ttl* parameter is supplied, then
+ ``self.update_ttl(ttl)`` will be called prior to adding the rdata.
+
+ *rd*, a ``dns.rdata.Rdata``, the rdata
- @param rd: The rdata
- @type rd: dns.rdata.Rdata object
- @param ttl: The TTL
- @type ttl: int"""
+ *ttl*, an ``int``, the TTL.
+
+ Raises ``dns.rdataset.IncompatibleTypes`` if the type and class
+ do not match the type and class of the rdataset.
+
+ Raises ``dns.rdataset.DifferingCovers`` if the type is a signature
+ type and the covered type does not match that of the rdataset.
+ """
#
# If we're adding a signature, do some special handling to
def update(self, other):
"""Add all rdatas in other to self.
- @param other: The rdataset from which to update
- @type other: dns.rdataset.Rdataset object"""
+ *other*, a ``dns.rdataset.Rdataset``, the rdataset from which
+ to update.
+ """
self.update_ttl(other.ttl)
super(Rdataset, self).update(other)
return self.to_text()
def __eq__(self, other):
- """Two rdatasets are equal if they have the same class, type, and
- covers, and contain the same rdata.
- @rtype: bool"""
-
if not isinstance(other, Rdataset):
return False
if self.rdclass != other.rdclass or \
override_rdclass=None, **kw):
"""Convert the rdataset into DNS master file format.
- @see: L{dns.name.Name.choose_relativity} for more information
- on how I{origin} and I{relativize} determine the way names
+ See ``dns.name.Name.choose_relativity`` for more information
+ on how *origin* and *relativize* determine the way names
are emitted.
Any additional keyword arguments are passed on to the rdata
- to_text() method.
-
- @param name: If name is not None, emit a RRs with I{name} as
- the owner name.
- @type name: dns.name.Name object
- @param origin: The origin for relative names, or None.
- @type origin: dns.name.Name object
- @param relativize: True if names should names be relativized
- @type relativize: bool"""
+ ``to_text()`` method.
+
+ *name*, a ``dns.name.Name``. If name is not ``None``, emit RRs with
+ *name* as the owner name.
+
+ *origin*, a ``dns.name.Name`` or ``None``, the origin for relative
+ names.
+
+ *relativize*, a ``bool``. If ``True``, names will be relativized
+ to *origin*.
+ """
+
if name is not None:
name = name.choose_relativity(origin, relativize)
ntext = str(name)
override_rdclass=None, want_shuffle=True):
"""Convert the rdataset to wire format.
- @param name: The owner name of the RRset that will be emitted
- @type name: dns.name.Name object
- @param file: The file to which the wire format data will be appended
- @type file: file
- @param compress: The compression table to use; the default is None.
- @type compress: dict
- @param origin: The origin to be appended to any relative names when
- they are emitted. The default is None.
- @returns: the number of records emitted
- @rtype: int
+ *name*, a ``dns.name.Name`` is the owner name to use.
+
+ *file* is the file where the name is emitted (typically a
+ BytesIO file).
+
+ *compress*, a ``dict``, is the compression table to use. If
+ ``None`` (the default), names will not be compressed.
+
+ *origin* is a ``dns.name.Name`` or ``None``. If the name is
+ relative and origin is not ``None``, then *origin* will be appended
+ to it.
+
+ *override_rdclass*, an ``int``, is used as the class instead of the
+ class of the rdataset. This is useful when rendering rdatasets
+ associated with dynamic updates.
+
+ *want_shuffle*, a ``bool``. If ``True``, then the order of the
+ Rdatas within the Rdataset will be shuffled before rendering.
+
+ Returns an ``int``, the number of records emitted.
"""
if override_rdclass is not None:
return len(self)
def match(self, rdclass, rdtype, covers):
- """Returns True if this rdataset matches the specified class, type,
- and covers"""
+ """Returns ``True`` if this rdataset matches the specified class,
+ type, and covers.
+ """
if self.rdclass == rdclass and \
self.rdtype == rdtype and \
self.covers == covers:
-# Copyright (C) 2003-2007, 2009-2011 Nominum, Inc.
+# Copyright (C) 2003-2017 Nominum, Inc.
#
# Permission to use, copy, modify, and distribute this software and its
# documentation for any purpose with or without fee is hereby granted,
return self.to_text()
def __eq__(self, other):
- """Two RRsets are equal if they have the same name and the same
- rdataset
-
- @rtype: bool"""
if not isinstance(other, RRset):
return False
if self.name != other.name:
return super(RRset, self).__eq__(other)
def match(self, name, rdclass, rdtype, covers, deleting=None):
- """Returns True if this rrset matches the specified class, type,
- covers, and deletion state."""
+ """Returns ``True`` if this rrset matches the specified class, type,
+ covers, and deletion state.
+ """
if not super(RRset, self).match(rdclass, rdtype, covers):
return False
def to_text(self, origin=None, relativize=True, **kw):
"""Convert the RRset into DNS master file format.
- @see: L{dns.name.Name.choose_relativity} for more information
- on how I{origin} and I{relativize} determine the way names
+ See ``dns.name.Name.choose_relativity`` for more information
+ on how *origin* and *relativize* determine the way names
are emitted.
Any additional keyword arguments are passed on to the rdata
- to_text() method.
+ ``to_text()`` method.
- @param origin: The origin for relative names, or None.
- @type origin: dns.name.Name object
- @param relativize: True if names should names be relativized
- @type relativize: bool"""
+ *origin*, a ``dns.name.Name`` or ``None``, the origin for relative
+ names.
+
+ *relativize*, a ``bool``. If ``True``, names will be relativized
+ to *origin*.
+ """
return super(RRset, self).to_text(self.name, origin, relativize,
self.deleting, **kw)
def to_wire(self, file, compress=None, origin=None, **kw):
- """Convert the RRset to wire format."""
+ """Convert the RRset to wire format.
+
+ All keyword arguments are passed to ``dns.rdataset.to_wire()``; see
+ that function for details.
+
+ Returns an ``int``, the number of records emitted.
+ """
return super(RRset, self).to_wire(self.name, file, compress, origin,
self.deleting, **kw)
def to_rdataset(self):
"""Convert an RRset into an Rdataset.
- @rtype: dns.rdataset.Rdataset object
+ Returns a ``dns.rdataset.Rdataset``.
"""
return dns.rdataset.from_rdata_list(self.ttl, list(self))
projects / thirdparty / dnspython.git / commitdiff
