From 6eb50285554fb4c1553941a8311391fe7f0a760d Mon Sep 17 00:00:00 2001 From: Bob Halley Date: Mon, 16 Jan 2017 07:53:55 -0800 Subject: [PATCH] node doco update --- dns/node.py | 100 +++++++++++++++++++------------------- doc/rdata-set-classes.rst | 11 ++++- 2 files changed, 60 insertions(+), 51 deletions(-) diff --git a/dns/node.py b/dns/node.py index 7c25060e..cc507b50 100644 --- a/dns/node.py +++ b/dns/node.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, @@ -24,19 +24,12 @@ import dns.renderer class Node(object): - """A DNS node. - - A node is a set of rdatasets - - @ivar rdatasets: the node's rdatasets - @type rdatasets: list of dns.rdataset.Rdataset objects""" + """A Node is a set of rdatasets.""" __slots__ = ['rdatasets'] def __init__(self): - """Initialize a DNS node. - """ - + #: the set of rdatsets, represented as a list. self.rdatasets = [] def to_text(self, name, **kw): @@ -44,9 +37,10 @@ class Node(object): Each rdataset at the node is printed. Any keyword arguments to this method are passed on to the rdataset's to_text() method. - @param name: the owner name of the rdatasets - @type name: dns.name.Name object - @rtype: string + + *name*, a ``dns.name.Name``, the owner name of the rdatasets. + + Returns a ``text``. """ s = StringIO() @@ -60,10 +54,6 @@ class Node(object): return '' def __eq__(self, other): - """Two nodes are equal if they have the same rdatasets. - - @rtype: bool - """ # # This is inefficient. Good thing we don't need to do it much. # @@ -89,11 +79,11 @@ class Node(object): """Find an rdataset matching the specified properties in the current node. - @param rdclass: The class of the rdataset - @type rdclass: int - @param rdtype: The type of the rdataset - @type rdtype: int - @param covers: The covered type. Usually this value is + *rdclass*, an ``int``, the class of the rdataset. + + *rdtype*, an ``int``, the type of the rdataset. + + *covers*, an ``int``, 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 @@ -101,12 +91,13 @@ class Node(object): 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 - @param create: If True, create the rdataset if it is not found. - @type create: bool - @raises KeyError: An rdataset of the desired type and class does - not exist and I{create} is not True. - @rtype: dns.rdataset.Rdataset object + + *create*, a ``bool``. If True, create the rdataset if it is not found. + + Raises ``KeyError`` if an rdataset of the desired type and class does + not exist and *create* is not ``True``. + + Returns a ``dns.rdataset.Rdataset``. """ for rds in self.rdatasets: @@ -124,17 +115,24 @@ class Node(object): current node. None is returned if an rdataset of the specified type and - class does not exist and I{create} is not True. - - @param rdclass: The class of the rdataset - @type rdclass: int - @param rdtype: The type of the rdataset - @type rdtype: int - @param covers: The covered type. - @type covers: int - @param create: If True, create the rdataset if it is not found. - @type create: bool - @rtype: dns.rdataset.Rdataset object or None + class does not exist and *create* is not ``True``. + + *rdclass*, an ``int``, the class of the rdataset. + + *rdtype*, an ``int``, the type of the rdataset. + + *covers*, an ``int``, 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. + + *create*, a ``bool``. If True, create the rdataset if it is not found. + + Returns a ``dns.rdataset.Rdataset`` or ``None``. """ try: @@ -149,12 +147,11 @@ class Node(object): If a matching rdataset does not exist, it is not an error. - @param rdclass: The class of the rdataset - @type rdclass: int - @param rdtype: The type of the rdataset - @type rdtype: int - @param covers: The covered type. - @type covers: int + *rdclass*, an ``int``, the class of the rdataset. + + *rdtype*, an ``int``, the type of the rdataset. + + *covers*, an ``int``, the covered type. """ rds = self.get_rdataset(rdclass, rdtype, covers) @@ -164,11 +161,16 @@ class Node(object): def replace_rdataset(self, replacement): """Replace an rdataset. - It is not an error if there is no rdataset matching I{replacement}. + It is not an error if there is no rdataset matching *replacement*. + + Ownership of the *replacement* object is transferred to the node; + in other words, this method does not store a copy of *replacement* + at the node, it stores *replacement* itself. + + *replacement*, a ``dns.rdataset.Rdataset``. - Ownership of the I{replacement} object is transferred to the node; - in other words, this method does not store a copy of I{replacement} - at the node, it stores I{replacement} itself. + Raises ``ValueError`` if *replacement* is not a + ``dns.rdataset.Rdataset``. """ if not isinstance(replacement, dns.rdataset.Rdataset): diff --git a/doc/rdata-set-classes.rst b/doc/rdata-set-classes.rst index c66df396..ed350085 100644 --- a/doc/rdata-set-classes.rst +++ b/doc/rdata-set-classes.rst @@ -1,7 +1,7 @@ .. _rdata-set-classes: -Rdataset and RRset Classes -========================== +Rdataset, RRset and Node Classes +================================ An ``Rdataset`` is a set of ``Rdata`` objects which all have the same rdatatype, rdataclass, and covered type. ``Rdatasets`` also have a @@ -12,8 +12,15 @@ An ``RRset`` is a subclass of ``Rdataset`` that also has an owner name, i.e. a ``dns.name.Name`` that says where in the DNS tree this set is located. +A ``Node`` is a set of ``Rdataset`` objects, the Rdatasets being +interpreted as at the same place (i.e. same owner name) int the DNS +tree. Nodes are primarily used in ``Zone`` objects. + .. autoclass:: dns.rdataset.Rdataset :members: .. autoclass:: dns.rrset.RRset :members: + +.. autoclass:: dns.node.Node + :members: -- 2.47.3