added documentation about OverflowError (#427)

Author: martin-neotech

docs/source/temporal_types.rst

@@ -73,12 +73,16 @@ Constructors and other class methods
 
 .. classmethod:: Date.today()
 
+    :raises OverflowError: if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.
+
 .. classmethod:: Date.utc_today()
 
     Return the current :class:`.Date` according to UTC.
 
 .. classmethod:: Date.from_timestamp(timestamp, tz=None)
 
+    :raises OverflowError: if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.
+
 .. classmethod:: Date.utc_from_timestamp(timestamp)
 
 .. classmethod:: Date.from_ordinal(ordinal)
@@ -190,15 +194,17 @@ Constructors and other class methods
 
 .. class:: neo4j.time.Time(hour, minute, second, tzinfo=None)
 
-.. py:classmethod:: Time.now()
+.. classmethod:: Time.now()
+
+    :raises OverflowError: if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.
 
-.. py:classmethod:: Time.utc_now()
+.. classmethod:: Time.utc_now()
 
-.. py:classmethod:: Time.from_ticks(ticks)
+.. classmethod:: Time.from_ticks(ticks)
 
-.. py:classmethod:: Time.from_native(time)
+.. classmethod:: Time.from_native(time)
 
-.. py:classmethod:: Time.from_clock_time(t, epoch)
+.. classmethod:: Time.from_clock_time(t, epoch)
 
 
 Class attributes
@@ -312,23 +318,29 @@ Constructors and other class methods
 
 .. autoclass:: neo4j.time.DateTime(year, month, day, hour=0, minute=0, second=0.0, tzinfo=None)
 
-.. py:classmethod:: DateTime.now()
+.. classmethod:: DateTime.now()
+
+    :raises OverflowError: if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.
+
+.. classmethod:: DateTime.utc_now()
 
-.. py:classmethod:: DateTime.utc_now()
+.. classmethod:: DateTime.from_timestamp(timestamp, tz=None)
 
-.. py:classmethod:: DateTime.from_timestamp(timestamp, tz=None)
+    :raises OverflowError: if the timestamp is out of the range of values supported by the platform C localtime() function. It’s common for this to be restricted to years from 1970 through 2038.
 
-.. py:classmethod:: DateTime.utc_from_timestamp(timestamp)
+.. classmethod:: DateTime.utc_from_timestamp(timestamp)
 
-.. py:classmethod:: DateTime.from_ordinal(ordinal)
+.. classmethod:: DateTime.from_ordinal(ordinal)
 
-.. py:classmethod:: DateTime.combine(date, time)
+.. classmethod:: DateTime.combine(date, time)
 
-.. py:classmethod:: DateTime.parse(timestamp, tz=None)
+..
+    NotImplementedError
+    .. classmethod:: DateTime.parse(timestamp, tz=None)
 
-.. py:classmethod:: DateTime.from_native(datetime)
+.. classmethod:: DateTime.from_native(datetime)
 
-.. py:classmethod:: DateTime.from_clock_time(t, epoch)
+.. classmethod:: DateTime.from_clock_time(t, epoch)
 
 
 Class attributes

neo4j/time/__init__.py

@@ -258,13 +258,24 @@ def available(cls):
 
     @classmethod
     def local_offset(cls):
-        """ The offset from UTC for local time read from this clock.
+        """The offset from UTC for local time read from this clock.
+        This may raise OverflowError if not supported, because of platform depending C libraries.
+
+        :returns:
+        :rtype:
+
+        :raises OverflowError:
         """
         return ClockTime(-int(mktime(gmtime(0))))
 
     def local_time(self):
-        """ Read and return the current local time from this clock, measured
-        relative to the Unix Epoch.
+        """ Read and return the current local time from this clock, measured relative to the Unix Epoch.
+        This may raise OverflowError if not supported, because of platform depending C libraries.
+
+        :returns:
+        :rtype:
+
+        :raises OverflowError:
         """
         return self.utc_time() + self.local_offset()
 
@@ -397,7 +408,9 @@ def from_iso_format(cls, s):
     def iso_format(self, sep="T"):
         """
 
-        :return:
+        :param sep: the seperation string
+        :returns:
+        :rtype: str
         """
         parts = []
         hours, minutes, seconds = self.hours_minutes_seconds
@@ -527,6 +540,14 @@ def __getattr__(self, name):
 
     @classmethod
     def today(cls, tz=None):
+        """This may raise OverflowError if not supported, because of platform depending C libraries.
+
+        :param tz: time zone
+        :returns:
+        :rtype:
+
+        :raises OverflowError:
+        """
         if tz is None:
             return cls.from_clock_time(Clock().local_time(), UnixEpoch)
         else:
@@ -538,6 +559,16 @@ def utc_today(cls):
 
     @classmethod
     def from_timestamp(cls, timestamp, tz=None):
+        """This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() function.
+        It’s common for this to be restricted to years from 1970 through 2038.
+
+        :param timestamp:
+        :param tz: time zone
+        :returns:
+        :rtype:
+
+        :raises OverflowError:
+        """
         if tz is None:
             return cls.from_clock_time(ClockTime(timestamp) + Clock().local_offset(), UnixEpoch)
         else:
@@ -916,6 +947,14 @@ def __getattr__(self, name):
 
     @classmethod
     def now(cls, tz=None):
+        """This may raise OverflowError if not supported, because of platform depending C libraries.
+
+        :param tz:
+        :returns:
+        :rtype:
+
+        :raises OverflowError:
+        """
         if tz is None:
             return cls.from_clock_time(Clock().local_time(), UnixEpoch)
         else:
@@ -1227,6 +1266,14 @@ def __getattr__(self, name):
 
     @classmethod
     def now(cls, tz=None):
+        """This may raise OverflowError if not supported, because of platform depending C libraries.
+
+        :param tz: time zone
+        :returns:
+        :rtype:
+
+        :raises OverflowError:
+        """
         if tz is None:
             return cls.from_clock_time(Clock().local_time(), UnixEpoch)
         else:
@@ -1245,6 +1292,15 @@ def from_iso_format(cls, s):
 
     @classmethod
     def from_timestamp(cls, timestamp, tz=None):
+        """This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() function,
+        and OverflowError on localtime() failure. It’s common for this to be restricted to years from 1970 through 2038.
+
+        :param timestamp:
+        :param tz:
+        :returns:
+
+        :raises OverflowError:
+        """
         if tz is None:
             return cls.from_clock_time(ClockTime(timestamp) + Clock().local_offset(), UnixEpoch)
         else: