Commit ce546ddd authored by JINMEI Tatuya's avatar JINMEI Tatuya
Browse files

[1333r] added python docstrings

parent fa89a079
......@@ -31,6 +31,7 @@ EXTRA_DIST = client_inc.cc
EXTRA_DIST += finder_inc.cc
EXTRA_DIST += iterator_inc.cc
EXTRA_DIST += updater_inc.cc
EXTRA_DIST += journal_reader_inc.cc
CLEANDIRS = __pycache__
......
......@@ -189,4 +189,58 @@ Parameters:\n\
journaling The zone updater should store a journal of the changes.\n\
\n\
";
// Modifications from C++ doc:
// pointer -> (removed)
// Null -> None
// exception types
const char* const DataSourceClient_getJournalReader_doc = "\
get_journal_reader(zone, begin_serial, end_serial) ->\n\
(int, ZoneJournalReader)\n\
\n\
Return a journal reader to retrieve differences of a zone.\n\
\n\
A derived version of this method creates a concrete ZoneJournalReader\n\
object specific to the underlying data source for the specified name\n\
of zone and differences between the versions specified by the\n\
beginning and ending serials of the corresponding SOA RRs. The RR\n\
class of the zone is the one that the client is expected to handle\n\
(see the detailed description of this class).\n\
\n\
Note that the SOA serials are compared by the semantics of the serial\n\
number arithmetic. So, for example, begin_serial can be larger than\n\
end_serial as bare unsigned integers. The underlying data source\n\
implementation is assumed to keep track of sufficient history to\n\
identify (if exist) the corresponding difference between the specified\n\
versions.\n\
\n\
This method returns the result as a pair of a result code and a\n\
ZoneJournalReader object. On success, the result code is\n\
SUCCESS and the object must not be None; otherwise the result code is\n\
something other than SUCCESS and the object must be None.\n\
\n\
If the specified zone is not found in the data source, the result code\n\
is NO_SUCH_ZONE. Otherwise, if specified range of difference for the\n\
zone is not found in the data source, the result code is\n\
NO_SUCH_VERSION.\n\
\n\
Handling differences is an optional feature of data source. If the\n\
underlying data source does not support difference handling, this\n\
method for that type of data source can throw an exception of class\n\
isc.datasrc.NotImplemented.\n\
\n\
Exceptions:\n\
isc.datasrc.NotImplemented The data source does not support differences.\n\
isc.datasrc.Error Other operational errors at the data source level.\n\
\n\
Parameters:\n\
zone The name of the zone for which the difference should be\n\
retrieved.\n\
begin_serial The SOA serial of the beginning version of the\n\
differences.\n\
end_serial The SOA serial of the ending version of the differences.\n\
\n\
Return Value(s): A pair of result code and a ZoneJournalReader object\n\
(which can be None)\n \
";
} // unnamed namespace
......@@ -214,7 +214,7 @@ PyMethodDef DataSourceClient_methods[] = {
{ "get_updater", DataSourceClient_getUpdater,
METH_VARARGS, DataSourceClient_getUpdater_doc },
{ "get_journal_reader", DataSourceClient_getJournalReader,
METH_VARARGS, ""/*DataSourceClient_getUpdater_doc*/ },
METH_VARARGS, DataSourceClient_getJournalReader_doc },
{ NULL, NULL, 0, NULL }
};
......
namespace {
const char* const ZoneJournalReader_doc = "\
The base class for retrieving differences between two versions of a\n\
zone.\n\
\n\
On construction, each derived class object will internally set up\n\
retrieving sequences of differences between two specific version of a\n\
specific zone managed in a particular data source. So the constructor\n\
of a derived class would normally take parameters to identify the zone\n\
and the two versions for which the differences should be retrieved.\n\
See DataSourceClient.get_journal_reader for more concrete details used\n\
in this API.\n\
\n\
Once constructed, an object of this class will act like an iterator\n\
over the sequences. Every time the get_next_diff() method is called it\n\
returns one element of the differences in the form of an RRset until\n\
it reaches the end of the entire sequences.\n\
\n\
";
// Modifications from C++ doc:
// ConstRRsetPtr -> RRset
// Null -> None
// InvalidOperation -> ValueError
const char* const ZoneJournalReader_getNextDiff_doc = "\
get_next_diff() -> isc.dns.RRset\n\
\n\
Return the next difference RR of difference sequences.\n\
\n\
In this API, the difference between two versions of a zone is\n\
conceptually represented as IXFR-style difference sequences: Each\n\
difference sequence is a sequence of RRs: an older version of SOA (to\n\
be deleted), zero or more other deleted RRs, the post-transaction SOA\n\
(to be added), and zero or more other added RRs. (Note, however, that\n\
the underlying data source implementation may or may not represent the\n\
difference in straightforward realization of this concept. The mapping\n\
between the conceptual difference and the actual implementation is\n\
hidden in each derived class).\n\
\n\
This method provides an application with a higher level interface to\n\
retrieve the difference along with the conceptual model: the\n\
ZoneJournalReader object iterates over the entire sequences from the\n\
beginning SOA (which is to be deleted) to one of the added RR of with\n\
the ending SOA, and each call to this method returns one RR in the\n\
form of an RRset that contains exactly one RDATA in the order of the\n\
sequences.\n\
\n\
Note that the ordering of the sequences specifies the semantics of\n\
each difference: add or delete. For example, the first RR is to be\n\
deleted, and the last RR is to be added. So the return value of this\n\
method does not explicitly indicate whether the RR is to be added or\n\
deleted.\n\
\n\
This method ensures the returned RRset represents an RR, that is, it\n\
contains exactly one RDATA. However, it does not necessarily ensure\n\
that the resulting sequences are in the form of IXFR-style. For\n\
example, the first RR is supposed to be an SOA, and it should normally\n\
be the case, but this interface does not necessarily require the\n\
derived class implementation ensure this. Normally the differences are\n\
expected to be stored using this API (via a ZoneUpdater object), and\n\
as long as that is the case and the underlying implementation follows\n\
the requirement of the API, the result of this method should be a\n\
valid IXFR-style sequences. So this API does not mandate the almost\n\
redundant check as part of the interface. If the application needs to\n\
make it sure 100%, it must check the resulting sequence itself.\n\
\n\
Once the object reaches the end of the sequences, this method returns\n\
None. Any subsequent call will result in an exception of class\n\
ValueError.\n\
\n\
Exceptions:\n\
ValueError The method is called beyond the end of the\n\
difference sequences.\n\
isc.datasrc.Error Underlying data is broken and the RR cannot be\n\
created or other low level data source error.\n\
\n\
Return Value(s): An RRset that contains one RDATA corresponding to the\n\
next difference in the sequences.\n\
";
} // unnamed namespace
......@@ -30,8 +30,7 @@
#include "datasrc.h"
#include "journal_reader_python.h"
// NOTYET
//#include "journal_reader_inc.cc"
#include "journal_reader_inc.cc"
using namespace isc::util::python;
using namespace isc::dns::python;
......@@ -124,7 +123,7 @@ ZoneJournalReader_next(PyObject* self) {
PyMethodDef ZoneJournalReader_methods[] = {
{ "get_next_diff", ZoneJournalReader_getNextDiff, METH_NOARGS,
""/*ZoneJournalReader_getNextDiff_doc*/ },
ZoneJournalReader_getNextDiff_doc },
{ NULL, NULL, 0, NULL }
};
......@@ -155,7 +154,7 @@ PyTypeObject journal_reader_type = {
NULL, // tp_setattro
NULL, // tp_as_buffer
Py_TPFLAGS_DEFAULT, // tp_flags
"", /*ZoneJournalReader_doc*/
ZoneJournalReader_doc,
NULL, // tp_traverse
NULL, // tp_clear
NULL, // tp_richcompare
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment