docs and test updates

git-svn-id: svn://bind10.isc.org/svn/bind10/experiments/python-binding@2083 e5f2f494-b856-4b98-b285-d166d9295462

src/lib/dns/python/messagerenderer_python.cc

@@ -45,12 +45,18 @@ static PyObject* MessageRenderer_setLengthLimit(s_MessageRenderer* self, PyObjec
 
 
 static PyMethodDef MessageRenderer_methods[] = {
-    { "get_data", (PyCFunction)MessageRenderer_getData, METH_NOARGS, "Return the data" },
-    { "get_length", (PyCFunction)MessageRenderer_getLength, METH_NOARGS, "Return the length of the data" },
-    { "is_truncated", (PyCFunction)MessageRenderer_isTruncated, METH_NOARGS, "Returns True if the data is truncated" },
-    { "get_length_limit", (PyCFunction)MessageRenderer_getLengthLimit, METH_NOARGS, "Return the length limit of the data" },
-    { "set_truncated", (PyCFunction)MessageRenderer_setTruncated, METH_NOARGS, "Set truncated to true" },
-    { "set_length_limit", (PyCFunction)MessageRenderer_setLengthLimit, METH_VARARGS, "Set the length limit of the data" },
+    { "get_data", (PyCFunction)MessageRenderer_getData, METH_NOARGS,
+      "Returns the data as a bytes() object" },
+    { "get_length", (PyCFunction)MessageRenderer_getLength, METH_NOARGS,
+      "Returns the length of the data" },
+    { "is_truncated", (PyCFunction)MessageRenderer_isTruncated, METH_NOARGS,
+      "Returns True if the data is truncated" },
+    { "get_length_limit", (PyCFunction)MessageRenderer_getLengthLimit, METH_NOARGS,
+      "Returns the length limit of the data" },
+    { "set_truncated", (PyCFunction)MessageRenderer_setTruncated, METH_NOARGS,
+      "Sets truncated to true" },
+    { "set_length_limit", (PyCFunction)MessageRenderer_setLengthLimit, METH_VARARGS,
+      "Sets the length limit of the data to the given number" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -75,7 +81,12 @@ static PyTypeObject messagerenderer_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ MessageRenderer Object",  /* tp_doc */
+    "The MessageRenderer class encapsulates implementation details "
+    "of rendering a DNS message into a buffer in wire format. "
+    "In effect, it's simply responsible for name compression at least in the "
+    "current implementation. A MessageRenderer class object manages the "
+    "positions of names rendered in a buffer and uses that information to render "
+    "subsequent names with compression.",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     NULL,                               /* tp_richcompare */

src/lib/dns/python/name_python.cc

@@ -77,9 +77,12 @@ static PyObject* NameComparisonResult_getCommonLabels(s_NameComparisonResult* se
 static PyObject* NameComparisonResult_getRelation(s_NameComparisonResult* self);
 
 static PyMethodDef NameComparisonResult_methods[] = {
-    { "get_order", (PyCFunction)NameComparisonResult_getOrder, METH_NOARGS, "Return the order" },
-    { "get_common_labels", (PyCFunction)NameComparisonResult_getCommonLabels, METH_NOARGS, "Return the number of common labels" },
-    { "get_relation", (PyCFunction)NameComparisonResult_getRelation, METH_NOARGS, "Return the relation" },
+    { "get_order", (PyCFunction)NameComparisonResult_getOrder, METH_NOARGS,
+      "Returns the order" },
+    { "get_common_labels", (PyCFunction)NameComparisonResult_getCommonLabels, METH_NOARGS,
+      "Returns the number of common labels" },
+    { "get_relation", (PyCFunction)NameComparisonResult_getRelation, METH_NOARGS,
+      "Returns the relation" },
     { NULL, NULL, 0, NULL }
 };
 
@@ -104,7 +107,13 @@ static PyTypeObject name_comparison_result_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ NameComparisonResult Object",  /* tp_doc */
+    "This is a supplemental class used only as a return value of Name.compare(). "
+    "It encapsulate a tuple of the comparison: ordering, number of common labels, "
+    "and relationship as follows:\n"
+    "- ordering: relative ordering under the DNSSEC order relation\n"
+    "- labels: the number of common significant labels of the two names being"
+    "  compared\n"
+    "- relationship: see NameComparisonResult.NameRelation\n",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     NULL,                               /* tp_richcompare */
@@ -194,18 +203,39 @@ static PyObject* Name_downcase(s_Name* self);
 static PyObject* Name_isWildCard(s_Name* self);
 
 static PyMethodDef Name_methods[] = {
-    { "at", (PyCFunction)Name_at, METH_VARARGS, "Return the int value of the name data at the specified position" },
-    { "get_length", (PyCFunction)Name_getLength, METH_NOARGS, "Return the length" },
-    { "get_labelcount", (PyCFunction)Name_getLabelCount, METH_NOARGS, "Return the number of labels" },
-    { "to_text", (PyCFunction)Name_toText, METH_NOARGS, "Return the string representation" },
-    { "to_wire", (PyCFunction)Name_toWire, METH_VARARGS, "Return the wire format" },
-    { "compare", (PyCFunction)Name_compare, METH_VARARGS, "Compare" },
-    { "equals", (PyCFunction)Name_equals, METH_VARARGS, "Equals" },
-    { "split", (PyCFunction)Name_split, METH_VARARGS, "split" },
-    { "reverse", (PyCFunction)Name_reverse, METH_NOARGS, "reverse" },
-    { "concatenate", (PyCFunction)Name_concatenate, METH_VARARGS, "concatenate" },
-    { "downcase", (PyCFunction)Name_downcase, METH_NOARGS, "downcase" },
-    { "is_wildcard", (PyCFunction)Name_isWildCard, METH_NOARGS, "isWildCard" },
+    { "at", (PyCFunction)Name_at, METH_VARARGS,
+      "Returns the integer value of the name data at the specified position" },
+    { "get_length", (PyCFunction)Name_getLength, METH_NOARGS,
+      "Returns the length" },
+    { "get_labelcount", (PyCFunction)Name_getLabelCount, METH_NOARGS,
+      "Returns the number of labels" },
+    { "to_text", (PyCFunction)Name_toText, METH_NOARGS,
+      "Returns the string representation" },
+    { "to_wire", (PyCFunction)Name_toWire, METH_VARARGS,
+      "Converts the Name object to wire format.\n"
+      "The argument can be either a MessageRenderer or an object that "
+      "implements the sequence interface. If the object is mutable "
+      "(for instance a bytearray()), the wire data is added in-place.\n"
+      "If it is not (for instance a bytes() object), a new object is "
+      "returned" },
+    { "compare", (PyCFunction)Name_compare, METH_VARARGS,
+      "Returns a NameComparisonResult object. The argument must be another Name object" },
+    { "equals", (PyCFunction)Name_equals, METH_VARARGS,
+      "Returns true if the given Name object is equal to this one" },
+    { "split", (PyCFunction)Name_split, METH_VARARGS,
+      "Splits the name, takes two arguments, the first is an integer "
+      "specifying the first label to place in the result. The second "
+      "is an integer specifying the number of labels to put in the "
+      "result. Returns a new Name object" },
+    { "reverse", (PyCFunction)Name_reverse, METH_NOARGS,
+      "Returns a new Name object that is the reverse of this one" },
+    { "concatenate", (PyCFunction)Name_concatenate, METH_VARARGS,
+      "Concatenates the given Name object to this one and returns the "
+      "result as a new Name object" },
+    { "downcase", (PyCFunction)Name_downcase, METH_NOARGS,
+      "Downcases this name object (in-place)." },
+    { "is_wildcard", (PyCFunction)Name_isWildCard, METH_NOARGS,
+      "Returns True if the Name object represents a wildcard name." },
     { NULL, NULL, 0, NULL }
 };
 
@@ -230,7 +260,10 @@ static PyTypeObject name_type = {
     NULL,                               /* tp_setattro */
     NULL,                               /* tp_as_buffer */
     Py_TPFLAGS_DEFAULT,                 /* tp_flags */
-    "C++ Name Object",  /* tp_doc */
+    "The Name class encapsulates DNS names.\n"
+    "It provides interfaces to construct a name from string or wire-format data, "
+    "transform a name into a string or wire-format data, compare two names, get "
+    "access to various properties of a name, etc.",
     NULL,                               /* tp_traverse */
     NULL,                               /* tp_clear */
     (richcmpfunc)Name_richcmp,                               /* tp_richcompare */
@@ -607,26 +640,26 @@ initModulePart_Name(PyObject* mod)
     addClassVariable(name_type, "ROOT_NAME", po_ROOT_NAME);
 
     // Add the exceptions to the module
-    po_EmptyLabel = PyErr_NewException("libdns_python.Name.EmptyLabel", NULL, NULL);
-    addClassVariable(name_type, "EmptyLabel", po_EmptyLabel);
+    po_EmptyLabel = PyErr_NewException("libdns_python.EmptyLabel", NULL, NULL);
+    PyModule_AddObject(mod, "EmptyLabel", po_EmptyLabel);
 
-    po_TooLongName = PyErr_NewException("libdns_python.Name.TooLongName", NULL, NULL);
-    addClassVariable(name_type, "TooLongName", po_TooLongName);
+    po_TooLongName = PyErr_NewException("libdns_python.TooLongName", NULL, NULL);
+    PyModule_AddObject(mod, "TooLongName", po_TooLongName);
 
-    po_TooLongLabel = PyErr_NewException("libdns_python.Name.TooLongLabel", NULL, NULL);
-    addClassVariable(name_type, "TooLongLabel", po_TooLongLabel);
+    po_TooLongLabel = PyErr_NewException("libdns_python.TooLongLabel", NULL, NULL);
+    PyModule_AddObject(mod, "TooLongLabel", po_TooLongLabel);
 
-    po_BadLabelType = PyErr_NewException("libdns_python.Name.BadLabelType", NULL, NULL);
-    addClassVariable(name_type, "BadLabelType", po_BadLabelType);
+    po_BadLabelType = PyErr_NewException("libdns_python.BadLabelType", NULL, NULL);
+    PyModule_AddObject(mod, "BadLabelType", po_BadLabelType);
 
-    po_BadEscape = PyErr_NewException("libdns_python.Name.BadEscape", NULL, NULL);
-    addClassVariable(name_type, "BadEscape", po_BadEscape);
+    po_BadEscape = PyErr_NewException("libdns_python.BadEscape", NULL, NULL);
+    PyModule_AddObject(mod, "BadEscape", po_BadEscape);
 
-    po_IncompleteName = PyErr_NewException("libdns_python.Name.IncompleteName", NULL, NULL);
-    addClassVariable(name_type, "IncompleteName", po_IncompleteName);
+    po_IncompleteName = PyErr_NewException("libdns_python.IncompleteName", NULL, NULL);
+    PyModule_AddObject(mod, "IncompleteName", po_IncompleteName);
 
-    po_InvalidBufferPosition = PyErr_NewException("libdns_python.Name.InvalidBufferPosition", NULL, NULL);
-    addClassVariable(name_type, "InvalidBufferPosition", po_InvalidBufferPosition);
+    po_InvalidBufferPosition = PyErr_NewException("libdns_python.InvalidBufferPosition", NULL, NULL);
+    PyModule_AddObject(mod, "InvalidBufferPosition", po_InvalidBufferPosition);
 
     /* TODO; this one is a message-specific one, move to message? */
     po_DNSMessageFORMERR = PyErr_NewException("libdns_python.DNSMessageFORMERR", NULL, NULL);

src/lib/dns/python/tests/message_python_test.py

@@ -369,7 +369,7 @@ class ConvertedUnittests(unittest.TestCase):
         self.assertFalse(message_render.is_dnssec_supported())
     
         ## A message in the parse mode doesn't allow this flag to be set.
-        self.assertRaises(Message.InvalidMessageOperation,
+        self.assertRaises(InvalidMessageOperation,
                           message_parse.set_dnssec_supported,
                           True)
         ## Once converted to the render mode, it works as above
@@ -408,17 +408,17 @@ class ConvertedUnittests(unittest.TestCase):
         message_render.set_udp_size(0xffff)
         self.assertEqual(0xffff, message_render.get_udp_size())
         # Too small is value is rejected
-        self.assertRaises(Message.InvalidMessageUDPSize, message_render.set_udp_size, 511)
+        self.assertRaises(InvalidMessageUDPSize, message_render.set_udp_size, 511)
     
         # A message in the parse mode doesn't allow the set operation.
-        self.assertRaises(Message.InvalidMessageOperation, message_parse.set_udp_size, 4096)
+        self.assertRaises(InvalidMessageOperation, message_parse.set_udp_size, 4096)
         ## Once converted to the render mode, it works as above.
         message_parse.make_response()
         message_parse.set_udp_size(4096)
         self.assertEqual(4096, message_parse.get_udp_size())
         message_parse.set_udp_size(0xffff)
         self.assertEqual(0xffff, message_parse.get_udp_size())
-        self.assertRaises(Message.InvalidMessageUDPSize, message_parse.set_udp_size, 511)
+        self.assertRaises(InvalidMessageUDPSize, message_parse.set_udp_size, 511)
     
     def test_EDNS0ExtCode(self):
         # Extended Rcode = BADVERS
@@ -461,7 +461,7 @@ class ConvertedUnittests(unittest.TestCase):
 
         # Unsupported Version
         message_parse.clear(Message.PARSE)
-        self.assertRaises(Message.DNSMessageBADVERS,
+        self.assertRaises(DNSMessageBADVERS,
                           factoryFromFile,
                           message_parse,
                           "message_fromWire9")

src/lib/dns/python/tests/name_python_test.py

@@ -67,19 +67,19 @@ class NameTest(unittest.TestCase):
         self.name5 = Name("*.example.com")
 
     def test_init(self):
-        self.assertRaises(Name.EmptyLabel, Name, "example..com")
-        self.assertRaises(Name.TooLongLabel, Name, "a"*64 + ".example.com")
-        self.assertRaises(Name.BadLabelType, Name, "\[asdf.example.com")
-        self.assertRaises(Name.BadEscape, Name, "\\999")
-        self.assertRaises(Name.TooLongName, Name, "example."*32 + "com")
-        self.assertRaises(Name.IncompleteName, Name, "\\")
+        self.assertRaises(EmptyLabel, Name, "example..com")
+        self.assertRaises(TooLongLabel, Name, "a"*64 + ".example.com")
+        self.assertRaises(BadLabelType, Name, "\[asdf.example.com")
+        self.assertRaises(BadEscape, Name, "\\999")
+        self.assertRaises(TooLongName, Name, "example."*32 + "com")
+        self.assertRaises(IncompleteName, Name, "\\")
         self.assertRaises(TypeError, Name, 1)
 
         b = bytearray()
         self.name1.to_wire(b)
         self.assertEqual(self.name1, Name(b))
         self.assertEqual(self.name1, Name(b, 0))
-        self.assertRaises(Name.InvalidBufferPosition, Name, b, 100)
+        self.assertRaises(InvalidBufferPosition, Name, b, 100)
         b = bytearray()
         b += b'\x07example'*32 + b'\x03com\x00'
         # no TooLong for from wire?
@@ -154,7 +154,7 @@ class NameTest(unittest.TestCase):
         self.assertEqual("example.com.", self.name1.concatenate(self.name2).to_text())
         self.assertEqual("example.com.example.com.", self.name1.concatenate(self.name1).to_text())
         self.assertRaises(TypeError, self.name1.concatenate, "wrong")
-        self.assertRaises(Name.TooLongName, self.name1.concatenate, Name("example."*31))
+        self.assertRaises(TooLongName, self.name1.concatenate, Name("example."*31))
         
 
     def test_downcase(self):