From 31ce20b67b0688b155c9c91704a15c103a8f2e16 Mon Sep 17 00:00:00 2001 From: Eric Appelt Date: Sat, 11 Feb 2017 21:31:42 -0500 Subject: [PATCH 1/3] bpo-29026: Clarity documentation of time.time Clarify the documentation of time.time by more precisely defining what is meant by "seconds since the epoch" on most platforms. Additionally explain how gmtime and localtime may be used to extract calendar components and convert to a more common date format. --- Doc/library/time.rst | 34 ++++++++++++++++++++++++++++------ 1 file changed, 28 insertions(+), 6 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 6ef02b740316dc..59564f03d3b546 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -19,9 +19,16 @@ An explanation of some terminology and conventions is in order. .. index:: single: epoch -* The :dfn:`epoch` is the point where the time starts. On January 1st of that - year, at 0 hours, the "time since the epoch" is zero. For Unix, the epoch is - 1970. To find out what the epoch is, look at ``gmtime(0)``. +* The :dfn:`epoch` is the point where the time starts, and is platform + dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC). + To find out what the epoch is on a given platform, look at ``gmtime(0)``. + +.. index:: seconds since the epoch + +* The term :dfn:`seconds since the epoch` refers to the total number + of elapsed seconds since the epoch, typically excluding + `leap seconds `_. + Leap seconds are excluded from this total on all POSIX-compliant platforms. .. index:: single: Year 2038 @@ -572,12 +579,27 @@ The module defines the following functions and data items: .. function:: time() - Return the time in seconds since the epoch as a floating point number. + Return the time in seconds since the epoch as a floating point + number. The specific date of the epoch and the handling of + `leap seconds `_ + is platform dependent. + On Windows and most Unix systems, the epoch is January 1, 1970, + 00:00:00 (UTC) and leap seconds are not counted towards the time + in seconds since the epoch. This is commonly referred to as + `Unix time `_. + Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. While this function normally returns non-decreasing values, it can return a - lower value than a previous call if the system clock has been set back between - the two calls. + lower value than a previous call if the system clock has been set back + between the two calls. + + The number returned by :func:`time` may be converted into a more common + time format (i.e. year, month, day, hour, etc...) in UTC by passing it to + :func:`gmtime` function or in local time by passing it to the + :func:`localtime` function. In both cases a :class:`struct_time` object + is returned, from which the components of the calendar date may be accessed + as attributes. .. data:: timezone From d387bf756ae11e463062a854a2fce172a5b115fc Mon Sep 17 00:00:00 2001 From: Eric Appelt Date: Mon, 13 Feb 2017 20:51:14 -0500 Subject: [PATCH 2/3] bpo-29026: Minor improvements for time.time doc --- Doc/library/time.rst | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 59564f03d3b546..853caa71c778a2 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -17,18 +17,23 @@ semantics of these functions varies among platforms. An explanation of some terminology and conventions is in order. +.. _epoch: + .. index:: single: epoch * The :dfn:`epoch` is the point where the time starts, and is platform dependent. For Unix, the epoch is January 1, 1970, 00:00:00 (UTC). - To find out what the epoch is on a given platform, look at ``gmtime(0)``. + To find out what the epoch is on a given platform, look at + ``time.gmtime(0)``. + +.. _leap seconds: https://en.wikipedia.org/wiki/Leap_second .. index:: seconds since the epoch * The term :dfn:`seconds since the epoch` refers to the total number of elapsed seconds since the epoch, typically excluding - `leap seconds `_. - Leap seconds are excluded from this total on all POSIX-compliant platforms. + `leap seconds`_. Leap seconds are excluded from this total on all + POSIX-compliant platforms. .. index:: single: Year 2038 @@ -579,14 +584,15 @@ The module defines the following functions and data items: .. function:: time() - Return the time in seconds since the epoch as a floating point + Return the time in seconds since the epoch_ as a floating point number. The specific date of the epoch and the handling of - `leap seconds `_ - is platform dependent. + `leap seconds`_ is platform dependent. On Windows and most Unix systems, the epoch is January 1, 1970, 00:00:00 (UTC) and leap seconds are not counted towards the time in seconds since the epoch. This is commonly referred to as `Unix time `_. + To find out what the epoch is on a given platform, look at + ``time.gmtime(0)``. Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. @@ -594,12 +600,12 @@ The module defines the following functions and data items: lower value than a previous call if the system clock has been set back between the two calls. - The number returned by :func:`time` may be converted into a more common + The number returned by :func:`time.time` may be converted into a more common time format (i.e. year, month, day, hour, etc...) in UTC by passing it to - :func:`gmtime` function or in local time by passing it to the - :func:`localtime` function. In both cases a :class:`struct_time` object - is returned, from which the components of the calendar date may be accessed - as attributes. + :func:`time.gmtime` function or in local time by passing it to the + :func:`time.localtime` function. In both cases a + :class:`time.struct_time` object is returned, from which the components + of the calendar date may be accessed as attributes. .. data:: timezone From 263a4f476615210322c89b6dba0abdd414db02e0 Mon Sep 17 00:00:00 2001 From: Eric Appelt Date: Mon, 13 Feb 2017 23:18:23 -0500 Subject: [PATCH 3/3] bpo-29026: Consistency fixes for time.time doc --- Doc/library/time.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/time.rst b/Doc/library/time.rst index 853caa71c778a2..ef0e69a5e8c1f8 100644 --- a/Doc/library/time.rst +++ b/Doc/library/time.rst @@ -479,7 +479,7 @@ The module defines the following functions and data items: (2) The range really is ``0`` to ``61``; value ``60`` is valid in - timestamps representing leap seconds and value ``61`` is supported + timestamps representing `leap seconds`_ and value ``61`` is supported for historical reasons. (3) @@ -592,7 +592,7 @@ The module defines the following functions and data items: in seconds since the epoch. This is commonly referred to as `Unix time `_. To find out what the epoch is on a given platform, look at - ``time.gmtime(0)``. + ``gmtime(0)``. Note that even though the time is always returned as a floating point number, not all systems provide time with a better precision than 1 second. @@ -600,11 +600,11 @@ The module defines the following functions and data items: lower value than a previous call if the system clock has been set back between the two calls. - The number returned by :func:`time.time` may be converted into a more common + The number returned by :func:`.time` may be converted into a more common time format (i.e. year, month, day, hour, etc...) in UTC by passing it to - :func:`time.gmtime` function or in local time by passing it to the - :func:`time.localtime` function. In both cases a - :class:`time.struct_time` object is returned, from which the components + :func:`gmtime` function or in local time by passing it to the + :func:`localtime` function. In both cases a + :class:`struct_time` object is returned, from which the components of the calendar date may be accessed as attributes. .. data:: timezone