more docs for timestamp module

Author: Mike Dirolf

doc/api/pymongo/index.rst

@@ -30,5 +30,6 @@ Sub-modules:
    message
    son
    son_manipulator
+   timestamp
    json_util
    cursor_manager

doc/api/pymongo/timestamp.rst

@@ -0,0 +1,7 @@
+:mod:`timestamp` -- Tools for representing MongoDB internal Timestamps
+======================================================================
+.. versionadded:: 1.4+
+
+.. automodule:: pymongo.timestamp
+   :synopsis: Tools for representing MongoDB internal Timestamps
+   :members:

pymongo/timestamp.py

@@ -19,21 +19,23 @@
 
 class Timestamp(object):
     """MongoDB internal timestamps used in the opLog.
+    """
 
-    This class is only for use with the MongoDB opLog. If you need to
-    store a regular timestamp, please use a
-    :class:`datetime.datetime`.
+    def __init__(self, time, inc):
+        """Create a new :class:`Timestamp`.
 
-    Raises :class:`TypeError` if `time` and `inc` are not instances of
-    :class:`int`. Raises :class:`ValueError` if `time` or `inc` is not
-    in [0, 2**32).
+        This class is only for use with the MongoDB opLog. If you need
+        to store a regular timestamp, please use a
+        :class:`~datetime.datetime`.
 
-    :Parameters:
-      - `time`: time in seconds since epoch UTC
-      - `inc`: the incrementing counter
-    """
+        Raises :class:`TypeError` if `time` and `inc` are not
+        instances of :class:`int`. Raises :class:`ValueError` if
+        `time` or `inc` is not in [0, 2**32).
 
-    def __init__(self, time, inc):
+        :Parameters:
+          - `time`: time in seconds since epoch UTC
+          - `inc`: the incrementing counter
+        """
         if not isinstance(time, int):
             raise TypeError("time must be an instance of int")
         if not isinstance(inc, int):
@@ -43,17 +45,32 @@ def __init__(self, time, inc):
         if not 0 <= inc < 2**32:
             raise ValueError("inc must be contained in [0, 2**32)")
 
-        self.time = time
-        self.inc = inc
+        self.__time = time
+        self.__inc = inc
+
+    @property
+    def time(self):
+        """Get the time portion of this :class:`Timestamp`.
+        """
+        return self.__time
+
+    @property
+    def inc(self):
+        """Get the inc portion of this :class:`Timestamp`.
+        """
+        return self.__inc
 
     def __eq__(self, other):
         if isinstance(other, Timestamp):
-            return (self.time == other.time and self.inc == other.inc)
+            return (self.__time == other.time and self.__inc == other.inc)
         else:
             return NotImplemented
 
     def __repr__(self):
-        return "Timestamp(%s, %s)" % (self.time, self.inc)
+        return "Timestamp(%s, %s)" % (self.__time, self.__inc)
 
     def as_datetime(self):
-        return datetime.datetime.utcfromtimestamp(self.time)
+        """Return a :class:`~datetime.datetime` instance corresponding
+        to the time portion of this :class:`Timestamp`.
+        """
+        return datetime.datetime.utcfromtimestamp(self.__time)