From d51cd470243441b5be02eddbed6692b103f0f014 Mon Sep 17 00:00:00 2001 From: Bob Halley Date: Tue, 10 Jan 2017 14:56:57 -0800 Subject: [PATCH] continue doco overhaul --- dns/rcode.py | 57 +++++++++++++++++++++++++-------------- dns/rdataset.py | 8 +++--- dns/rrset.py | 8 +++--- doc/exceptions.rst | 14 +++++++--- doc/rdata-set-classes.rst | 4 +-- 5 files changed, 58 insertions(+), 33 deletions(-) diff --git a/dns/rcode.py b/dns/rcode.py index 314815f7..eb4d1d6b 100644 --- a/dns/rcode.py +++ b/dns/rcode.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, @@ -18,18 +18,29 @@ import dns.exception from ._compat import long - +#: No error NOERROR = 0 +#: Form error FORMERR = 1 +#: Server failure SERVFAIL = 2 +#: Name does not exist ("Name Error" in RFC 1025 terminology). NXDOMAIN = 3 +#: Not implemented NOTIMP = 4 +#: Refused REFUSED = 5 +#: Name exists. YXDOMAIN = 6 +#: RRset exists. YXRRSET = 7 +#: RRset does not exist. NXRRSET = 8 +#: Not authoritative. NOTAUTH = 9 +#: Name not in zone. NOTZONE = 10 +#: Bad EDNS version. BADVERS = 16 _by_text = { @@ -55,17 +66,17 @@ _by_value = dict((y, x) for x, y in _by_text.items()) class UnknownRcode(dns.exception.DNSException): - """A DNS rcode is unknown.""" def from_text(text): """Convert text into an rcode. - @param text: the textual rcode - @type text: string - @raises UnknownRcode: the rcode is unknown - @rtype: int + *text*, a ``text``, the textual rcode or an integer in textual form. + + Raises ``dns.rcode.UnknownRcode`` if the rcode mnemonic is unknown. + + Returns an ``int``. """ if text.isdigit(): @@ -81,12 +92,13 @@ def from_text(text): def from_flags(flags, ednsflags): """Return the rcode value encoded by flags and ednsflags. - @param flags: the DNS flags - @type flags: int - @param ednsflags: the EDNS flags - @type ednsflags: int - @raises ValueError: rcode is < 0 or > 4095 - @rtype: int + *flags*, an ``int``, the DNS flags field. + + *ednsflags*, an ``int``, the EDNS flags field. + + Raises ``ValueError`` if rcode is < 0 or > 4095 + + Returns an ``int``. """ value = (flags & 0x000f) | ((ednsflags >> 20) & 0xff0) @@ -98,10 +110,11 @@ def from_flags(flags, ednsflags): def to_flags(value): """Return a (flags, ednsflags) tuple which encodes the rcode. - @param value: the rcode - @type value: int - @raises ValueError: rcode is < 0 or > 4095 - @rtype: (int, int) tuple + *value*, an ``int``, the rcode. + + Raises ``ValueError`` if rcode is < 0 or > 4095. + + Returns an ``(int, int)`` tuple. """ if value < 0 or value > 4095: @@ -114,11 +127,15 @@ def to_flags(value): def to_text(value): """Convert rcode into text. - @param value: the rcode - @type value: int - @rtype: string + *value*, and ``int``, the rcode. + + Raises ``ValueError`` if rcode is < 0 or > 4095. + + Returns a ``text``. """ + if value < 0 or value > 4095: + raise ValueError('rcode must be >= 0 and <= 4095') text = _by_value.get(value) if text is None: text = str(value) diff --git a/dns/rdataset.py b/dns/rdataset.py index db266f2f..9f0825e2 100644 --- a/dns/rdataset.py +++ b/dns/rdataset.py @@ -285,7 +285,7 @@ def from_text_list(rdclass, rdtype, ttl, text_rdatas): """Create an rdataset with the specified class, type, and TTL, and with the specified list of rdatas in text format. - @rtype: dns.rdataset.Rdataset object + Returns a ``dns.rdataset.Rdataset`` object. """ if isinstance(rdclass, string_types): @@ -304,7 +304,7 @@ def from_text(rdclass, rdtype, ttl, *text_rdatas): """Create an rdataset with the specified class, type, and TTL, and with the specified rdatas in text format. - @rtype: dns.rdataset.Rdataset object + Returns a ``dns.rdataset.Rdataset`` object. """ return from_text_list(rdclass, rdtype, ttl, text_rdatas) @@ -314,7 +314,7 @@ def from_rdata_list(ttl, rdatas): """Create an rdataset with the specified TTL, and with the specified list of rdata objects. - @rtype: dns.rdataset.Rdataset object + Returns a ``dns.rdataset.Rdataset`` object. """ if len(rdatas) == 0: @@ -332,7 +332,7 @@ def from_rdata(ttl, *rdatas): """Create an rdataset with the specified TTL, and with the specified rdata objects. - @rtype: dns.rdataset.Rdataset object + Returns a ``dns.rdataset.Rdataset`` object. """ return from_rdata_list(ttl, rdatas) diff --git a/dns/rrset.py b/dns/rrset.py index d0f8f937..30086453 100644 --- a/dns/rrset.py +++ b/dns/rrset.py @@ -124,7 +124,7 @@ def from_text_list(name, ttl, rdclass, rdtype, text_rdatas, """Create an RRset with the specified name, TTL, class, and type, and with the specified list of rdatas in text format. - @rtype: dns.rrset.RRset object + Returns a ``dns.rrset.RRset`` object. """ if isinstance(name, string_types): @@ -145,7 +145,7 @@ def from_text(name, ttl, rdclass, rdtype, *text_rdatas): """Create an RRset with the specified name, TTL, class, and type and with the specified rdatas in text format. - @rtype: dns.rrset.RRset object + Returns a ``dns.rrset.RRset`` object. """ return from_text_list(name, ttl, rdclass, rdtype, text_rdatas) @@ -155,7 +155,7 @@ def from_rdata_list(name, ttl, rdatas, idna_codec=None): """Create an RRset with the specified name and TTL, and with the specified list of rdata objects. - @rtype: dns.rrset.RRset object + Returns a ``dns.rrset.RRset`` object. """ if isinstance(name, string_types): @@ -176,7 +176,7 @@ def from_rdata(name, ttl, *rdatas): """Create an RRset with the specified name and TTL, and with the specified rdata objects. - @rtype: dns.rrset.RRset object + Returns a ``dns.rrset.RRset`` object. """ return from_rdata_list(name, ttl, rdatas) diff --git a/doc/exceptions.rst b/doc/exceptions.rst index 1eb856fb..8c5c003a 100644 --- a/doc/exceptions.rst +++ b/doc/exceptions.rst @@ -1,13 +1,16 @@ .. _exceptions: +Exceptions +========== + Common Exceptions -================= +----------------- .. automodule:: dns.exception :members: dns.name Exceptions -=================== +------------------- .. autoexception:: dns.name.AbsoluteConcatenation .. autoexception:: dns.name.BadEscape @@ -21,8 +24,13 @@ dns.name Exceptions .. autoexception:: dns.name.NoIDNA2008 .. autoexception:: dns.name.NoParent +dns.rcode Exceptions +-------------------- + +.. autoexception:: dns.rcode.UnknownRcode + dns.rdataset Exceptions -======================= +----------------------- .. autoexception:: dns.rdataset.DifferingCovers .. autoexception:: dns.rdataset.IncompatibleTypes diff --git a/doc/rdata-set-classes.rst b/doc/rdata-set-classes.rst index 5a953c89..c66df396 100644 --- a/doc/rdata-set-classes.rst +++ b/doc/rdata-set-classes.rst @@ -1,7 +1,7 @@ .. _rdata-set-classes: -DNS Rdataset Class -================== +Rdataset and RRset Classes +========================== An ``Rdataset`` is a set of ``Rdata`` objects which all have the same rdatatype, rdataclass, and covered type. ``Rdatasets`` also have a -- 2.47.3