From: Bob Halley Date: Mon, 16 Jan 2017 14:53:48 +0000 (-0800) Subject: more doco updates X-Git-Tag: v1.16.0~58 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=03658ba0f8a43bb5cce22889542290f3864d1a2c;p=thirdparty%2Fdnspython.git more doco updates --- diff --git a/dns/name.py b/dns/name.py index 951488ed..7537792e 100644 --- a/dns/name.py +++ b/dns/name.py @@ -628,7 +628,6 @@ class Name(object): relative and no origin was provided. Returns a ``binary`` or ``None``. - """ if file is None: diff --git a/dns/rdataset.py b/dns/rdataset.py index 9f0825e2..bd8cfab7 100644 --- a/dns/rdataset.py +++ b/dns/rdataset.py @@ -1,4 +1,4 @@ -# 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, @@ -31,50 +31,37 @@ SimpleSet = dns.set.Set 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() @@ -85,11 +72,14 @@ class Rdataset(dns.set.Set): 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 @@ -99,13 +89,19 @@ class Rdataset(dns.set.Set): 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 @@ -139,8 +135,9 @@ class Rdataset(dns.set.Set): 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) @@ -157,10 +154,6 @@ class Rdataset(dns.set.Set): 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 \ @@ -176,20 +169,23 @@ class Rdataset(dns.set.Set): 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) @@ -227,16 +223,26 @@ class Rdataset(dns.set.Set): 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: @@ -272,8 +278,9 @@ class Rdataset(dns.set.Set): 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: diff --git a/dns/rrset.py b/dns/rrset.py index 30086453..6774647a 100644 --- a/dns/rrset.py +++ b/dns/rrset.py @@ -1,4 +1,4 @@ -# 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, @@ -67,10 +67,6 @@ class RRset(dns.rdataset.Rdataset): 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: @@ -78,8 +74,9 @@ class RRset(dns.rdataset.Rdataset): 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 @@ -90,23 +87,31 @@ class RRset(dns.rdataset.Rdataset): 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) @@ -114,7 +119,7 @@ class RRset(dns.rdataset.Rdataset): 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))