Skip to content

Commit 29cd422

Browse files
added documentation about OverflowError (#427)
1 parent ac331fc commit 29cd422

File tree

2 files changed

+86
-18
lines changed

2 files changed

+86
-18
lines changed

docs/source/temporal_types.rst

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -73,12 +73,16 @@ Constructors and other class methods
7373

7474
.. classmethod:: Date.today()
7575

76+
: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.
77+
7678
.. classmethod:: Date.utc_today()
7779

7880
Return the current :class:`.Date` according to UTC.
7981

8082
.. classmethod:: Date.from_timestamp(timestamp, tz=None)
8183

84+
: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.
85+
8286
.. classmethod:: Date.utc_from_timestamp(timestamp)
8387

8488
.. classmethod:: Date.from_ordinal(ordinal)
@@ -190,15 +194,17 @@ Constructors and other class methods
190194

191195
.. class:: neo4j.time.Time(hour, minute, second, tzinfo=None)
192196

193-
.. py:classmethod:: Time.now()
197+
.. classmethod:: Time.now()
198+
199+
: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.
194200

195-
.. py:classmethod:: Time.utc_now()
201+
.. classmethod:: Time.utc_now()
196202

197-
.. py:classmethod:: Time.from_ticks(ticks)
203+
.. classmethod:: Time.from_ticks(ticks)
198204

199-
.. py:classmethod:: Time.from_native(time)
205+
.. classmethod:: Time.from_native(time)
200206

201-
.. py:classmethod:: Time.from_clock_time(t, epoch)
207+
.. classmethod:: Time.from_clock_time(t, epoch)
202208

203209

204210
Class attributes
@@ -312,23 +318,29 @@ Constructors and other class methods
312318

313319
.. autoclass:: neo4j.time.DateTime(year, month, day, hour=0, minute=0, second=0.0, tzinfo=None)
314320

315-
.. py:classmethod:: DateTime.now()
321+
.. classmethod:: DateTime.now()
322+
323+
: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.
324+
325+
.. classmethod:: DateTime.utc_now()
316326

317-
.. py:classmethod:: DateTime.utc_now()
327+
.. classmethod:: DateTime.from_timestamp(timestamp, tz=None)
318328

319-
.. py:classmethod:: DateTime.from_timestamp(timestamp, tz=None)
329+
: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.
320330

321-
.. py:classmethod:: DateTime.utc_from_timestamp(timestamp)
331+
.. classmethod:: DateTime.utc_from_timestamp(timestamp)
322332

323-
.. py:classmethod:: DateTime.from_ordinal(ordinal)
333+
.. classmethod:: DateTime.from_ordinal(ordinal)
324334

325-
.. py:classmethod:: DateTime.combine(date, time)
335+
.. classmethod:: DateTime.combine(date, time)
326336

327-
.. py:classmethod:: DateTime.parse(timestamp, tz=None)
337+
..
338+
NotImplementedError
339+
.. classmethod:: DateTime.parse(timestamp, tz=None)
328340
329-
.. py:classmethod:: DateTime.from_native(datetime)
341+
.. classmethod:: DateTime.from_native(datetime)
330342

331-
.. py:classmethod:: DateTime.from_clock_time(t, epoch)
343+
.. classmethod:: DateTime.from_clock_time(t, epoch)
332344

333345

334346
Class attributes

neo4j/time/__init__.py

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -258,13 +258,24 @@ def available(cls):
258258

259259
@classmethod
260260
def local_offset(cls):
261-
""" The offset from UTC for local time read from this clock.
261+
"""The offset from UTC for local time read from this clock.
262+
This may raise OverflowError if not supported, because of platform depending C libraries.
263+
264+
:returns:
265+
:rtype:
266+
267+
:raises OverflowError:
262268
"""
263269
return ClockTime(-int(mktime(gmtime(0))))
264270

265271
def local_time(self):
266-
""" Read and return the current local time from this clock, measured
267-
relative to the Unix Epoch.
272+
""" Read and return the current local time from this clock, measured relative to the Unix Epoch.
273+
This may raise OverflowError if not supported, because of platform depending C libraries.
274+
275+
:returns:
276+
:rtype:
277+
278+
:raises OverflowError:
268279
"""
269280
return self.utc_time() + self.local_offset()
270281

@@ -397,7 +408,9 @@ def from_iso_format(cls, s):
397408
def iso_format(self, sep="T"):
398409
"""
399410
400-
:return:
411+
:param sep: the seperation string
412+
:returns:
413+
:rtype: str
401414
"""
402415
parts = []
403416
hours, minutes, seconds = self.hours_minutes_seconds
@@ -527,6 +540,14 @@ def __getattr__(self, name):
527540

528541
@classmethod
529542
def today(cls, tz=None):
543+
"""This may raise OverflowError if not supported, because of platform depending C libraries.
544+
545+
:param tz: time zone
546+
:returns:
547+
:rtype:
548+
549+
:raises OverflowError:
550+
"""
530551
if tz is None:
531552
return cls.from_clock_time(Clock().local_time(), UnixEpoch)
532553
else:
@@ -538,6 +559,16 @@ def utc_today(cls):
538559

539560
@classmethod
540561
def from_timestamp(cls, timestamp, tz=None):
562+
"""This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() function.
563+
It’s common for this to be restricted to years from 1970 through 2038.
564+
565+
:param timestamp:
566+
:param tz: time zone
567+
:returns:
568+
:rtype:
569+
570+
:raises OverflowError:
571+
"""
541572
if tz is None:
542573
return cls.from_clock_time(ClockTime(timestamp) + Clock().local_offset(), UnixEpoch)
543574
else:
@@ -916,6 +947,14 @@ def __getattr__(self, name):
916947

917948
@classmethod
918949
def now(cls, tz=None):
950+
"""This may raise OverflowError if not supported, because of platform depending C libraries.
951+
952+
:param tz:
953+
:returns:
954+
:rtype:
955+
956+
:raises OverflowError:
957+
"""
919958
if tz is None:
920959
return cls.from_clock_time(Clock().local_time(), UnixEpoch)
921960
else:
@@ -1227,6 +1266,14 @@ def __getattr__(self, name):
12271266

12281267
@classmethod
12291268
def now(cls, tz=None):
1269+
"""This may raise OverflowError if not supported, because of platform depending C libraries.
1270+
1271+
:param tz: time zone
1272+
:returns:
1273+
:rtype:
1274+
1275+
:raises OverflowError:
1276+
"""
12301277
if tz is None:
12311278
return cls.from_clock_time(Clock().local_time(), UnixEpoch)
12321279
else:
@@ -1245,6 +1292,15 @@ def from_iso_format(cls, s):
12451292

12461293
@classmethod
12471294
def from_timestamp(cls, timestamp, tz=None):
1295+
"""This may raise OverflowError, if the timestamp is out of the range of values supported by the platform C localtime() function,
1296+
and OverflowError on localtime() failure. It’s common for this to be restricted to years from 1970 through 2038.
1297+
1298+
:param timestamp:
1299+
:param tz:
1300+
:returns:
1301+
1302+
:raises OverflowError:
1303+
"""
12481304
if tz is None:
12491305
return cls.from_clock_time(ClockTime(timestamp) + Clock().local_offset(), UnixEpoch)
12501306
else:

0 commit comments

Comments
 (0)