[2435] updated pydoc for RRsetCollections to match the latest C++ doxygen doc.

src/lib/dns/python/rrset_collection_python_inc.cc

@@ -36,6 +36,41 @@ Returns the RRset in the collection that exactly matches the given\n\
 name, rrclass and rrtype. If no matching RRset is found, None is\n\
 returned.\n\
 \n\
+This method's implementations currently are not specified to handle\n\
+RRTypes such as RRSIG and NSEC3. This interface may be refined to\n\
+clarify this point in the future, and perhaps, provide additional API\n\
+for these RRType.\n\
+\n\
+As for RRSIG, there are some fundamental open questions. For example,\n\
+it's not clear whether we want to return all RRSIGs of the given name\n\
+covering any RR types (in which case, we need to figure out how), or\n\
+we need to extend the interface so we can specify the covered type. A\n\
+specific derived implementation may return something if type RRSIG is\n\
+specified, but this is not specified here at the base class level. So,\n\
+for RRSIGs the behavior should be assumed as undefined.\n\
+\n\
+As for NSEC3, it's not clear whether owner names (which included\n\
+hashed labels) are the best choice of search key, because in many\n\
+cases, what the application wants to find is an NSEC3 that has the\n\
+hash of some particular \"normal\" domain names. Also, if the\n\
+underlying implementation encapsulates a single zone, NSEC3 records\n\
+conceptually belong to a separate name space, which may cause\n\
+implementation difficulty.\n\
+\n\
+Behavior with meta types such as ANY and AXFR are also undefined. A\n\
+specific implementation may return something for these. But, unlike\n\
+the case of RRSIGs, these types of RRsets are not expected to be added\n\
+to any implementation of collection in the first place (by the\n\
+definition of \"meta types\"), so querying for such types is\n\
+basically an invalid operation. The API doesn't require\n\
+implementations to check this condition and reject it, so the behavior\n\
+is undefined. This interface will not be refined in future versions\n\
+for these meta types.\n\
+\n\
+Exceptions:\n\
+  RRsetCollectionError if find() results in some implementation-\n\
+             specific error.\n\
+\n\
 Parameters:\n\
   name       (isc.dns.Name) The name of the RRset to search for.\n\
   rrtype     (isc.dns.RRType) The type of the RRset to search for.\n\
@@ -121,7 +156,7 @@ find(name, rrclass, rrtype) -> isc.dns.RRset\n\
 Find a matching RRset in the collection.\n\
 \n\
 Returns the RRset in the collection that exactly matches the given\n\
-name, rrclass and rrtype. If no matching RRset is found, NULL is\n\
+name, rrclass and rrtype. If no matching RRset is found, None is\n\
 returned.\n\
 \n\
 Parameters:\n\
@@ -129,7 +164,7 @@ Parameters:\n\
   rrclass    The class of the RRset to search for.\n\
   rrtype     The type of the RRset to search for.\n\
 \n\
-Return Value(s): The RRset if found, NULL otherwise.\n\
+Return Value(s): The RRset if found, None otherwise.\n\
 ";
 
 // Modifications

src/lib/python/isc/datasrc/updater_inc.cc

@@ -178,4 +178,67 @@ Exceptions:\n\
              error, or wrapper error\n\\n\
 \n\
 ";
+
+// Modifications:
+// -  remove reference to isc.datasrc.RRsetCollectionBase (hidden for Python
+//    wrapper)
+const char* const ZoneUpdater_getRRsetCollection_doc = "\
+get_rrset_collection() -> isc.dns.RRsetCollectionBase \n\
+\n\
+Return an RRsetCollection for the updater.\n\
+\n\
+This method returns an RRsetCollection for the updater, implementing\n\
+the isc.dns.RRsetCollectionBase interface. Typically, the returned\n\
+RRsetCollection is a singleton for its ZoneUpdater. The returned\n\
+RRsetCollection object must not be used after its corresponding\n\
+ZoneUpdater has been destroyed. The returned RRsetCollection object\n\
+may be used to search RRsets from the ZoneUpdater. The actual\n\
+RRsetCollection returned has a behavior dependent on the ZoneUpdater\n\
+implementation.\n\
+\n\
+The behavior of the RRsetCollection is similar to the behavior of the\n\
+Zonefinder returned by get_finder(). In fact, it's redundant in a\n\
+sense because one can implement the dns.RRsetCollectionBase interface\n\
+using an updater and get_finder() interface (unless it's expected to\n\
+support zone iteration, and the initial implementation of the\n\
+RRsetCollection returned by this method doesn't support it). We\n\
+still provide it as an updater's method so it will be easier for an\n\
+updater implementation to customize the RRsetCollection\n\
+implementation, and also for making it easy to impose restrictions\n\
+described below.\n\
+\n\
+Specific data sources may have special restrictions. That's especially\n\
+the case for database-based data sources. Such restrictions may also\n\
+result in limiting the usage of the RRsetCollection as described in\n\
+the following paragraphs. A specific updater implementation may\n\
+provide more flexible behavior, but applications using this interface\n\
+must assume the most restricted case unless it knows it uses a\n\
+particular specialized updater implementation that loosens specific\n\
+restrictions.\n\
+\n\
+- An application must not add or delete RRsets after\n\
+  get_rrset_collection() is called.\n\
+- An application must not use the returned collection from\n\
+  get_rrset_collection() once commit() is called on the updater that\n\
+  generates the collection.\n\
+\n\
+Implementations of ZoneUpdater may not allow adding or deleting RRsets\n\
+after get_rrset_collection() is called. This is because if an\n\
+iterator of the collection is being used at that time the modification\n\
+to the zone may break an internal assumption of the iterator and may\n\
+result in unexpected behavior. Also, the iterator may conceptually\n\
+hold a \"reader lock\" of the zone (in an implementation dependent\n\
+manner), which would prevent the addition or deletion, surprising the\n\
+caller (who would normally expect it to succeed).\n\
+\n\
+Implementations of ZoneUpdater may disable a previously returned\n\
+RRsetCollection after commit() is called. This is because the returned\n\
+RRsetCollection may internally rely on the conceptual transaction of\n\
+the updater that generates the collection (which would be literally\n\
+the case for database-based data sources), and once the transaction is\n\
+committed anything that relies on it won't be valid. If an\n\
+RRsetCollection is disabled, using methods such as find() and using\n\
+its iterator would cause an exception to be thrown.\n\
+\n\
+";
 } // unnamed namespace