PEP 410

Doc/library/os.rst

@@ -808,13 +808,16 @@ as internal buffering of data.
    Availability: Unix.
 
 
-.. function:: fstat(fd)
+.. function:: fstat(fd, timestamp=None)
 
    Return status for file descriptor *fd*, like :func:`~os.stat`.
 
    Availability: Unix, Windows.
 
-.. function:: fstatat(dirfd, path, flags=0)
+   .. versionchanged:: 3.3
+      Added the *timestamp* argument.
+
+.. function:: fstatat(dirfd, path, flags=0, timestamp="float")
 
    Like :func:`stat` but if *path* is relative, it is taken as relative to *dirfd*.
    *flags* is optional and may be 0 or :data:`AT_SYMLINK_NOFOLLOW`.
@@ -1696,7 +1699,7 @@ Files and Directories
    .. versionadded:: 3.3
 
 
-.. function:: lstat(path)
+.. function:: lstat(path, timestamp=None)
 
    Perform the equivalent of an :c:func:`lstat` system call on the given path.
    Similar to :func:`~os.stat`, but does not follow symbolic links.  On
@@ -1706,6 +1709,9 @@ Files and Directories
    .. versionchanged:: 3.2
       Added support for Windows 6.0 (Vista) symbolic links.
 
+   .. versionchanged:: 3.3
+      The *timestamp* argument was added.
+
 
 .. function:: lutimes(path[, times])
 
@@ -1969,7 +1975,7 @@ Files and Directories
    .. versionadded:: 3.3
 
 
-.. function:: stat(path)
+.. function:: stat(path, timestamp=None)
 
    Perform the equivalent of a :c:func:`stat` system call on the given path.
    (This function follows symlinks; to stat a symlink use :func:`lstat`.)
@@ -1989,6 +1995,11 @@ Files and Directories
    * :attr:`st_ctime` - platform dependent; time of most recent metadata change on
      Unix, or the time of creation on Windows)
 
+   :attr:`st_atime`, :attr:`st_mtime` and :attr:`st_ctime` are :class:`float`
+   by default, or :class:`int` if :func:`os.stat_float_times` is ``False``. Set
+   the *timestamp* argument to get another :ref:`timestamp type
+   <timestamp-types>`.
+
    On some Unix systems (such as Linux), the following attributes may also be
    available:
 
@@ -2044,6 +2055,9 @@ Files and Directories
 
    Availability: Unix, Windows.
 
+   .. versionchanged:: 3.3
+      Added the *timestamp* argument.
+
 
 .. function:: stat_float_times([newvalue])
 
@@ -2069,6 +2083,9 @@ Files and Directories
    are processed, this application should turn the feature off until the library
    has been corrected.
 
+   .. deprecated:: 3.3
+      Use *timestamp* argument of stat functions instead.
+
 
 .. function:: statvfs(path)
 
@@ -2859,27 +2876,39 @@ written in Python, such as a mail server's external command delivery program.
    with :const:`P_NOWAIT` return suitable process handles.
 
 
-.. function:: wait3([options])
+.. function:: wait3(options[, timestamp=float])
 
    Similar to :func:`waitpid`, except no process id argument is given and a
    3-element tuple containing the child's process id, exit status indication, and
    resource usage information is returned.  Refer to :mod:`resource`.\
    :func:`getrusage` for details on resource usage information.  The option
    argument is the same as that provided to :func:`waitpid` and :func:`wait4`.
+   :attr:`ru_utime` and :attr:`ru_stime` attributes of the resource usage are
+   :class:`float` by default, set the *timestamp* argument to get another
+   :ref:`timestamp type <timestamp-types>`.
 
    Availability: Unix.
 
+   .. versionchanged:: 3.3
+      Added the *timestamp* argument.
+
 
-.. function:: wait4(pid, options)
+.. function:: wait4(pid, options[, timestamp=float])
 
    Similar to :func:`waitpid`, except a 3-element tuple, containing the child's
    process id, exit status indication, and resource usage information is returned.
    Refer to :mod:`resource`.\ :func:`getrusage` for details on resource usage
    information.  The arguments to :func:`wait4` are the same as those provided to
    :func:`waitpid`.
+   :attr:`ru_utime` and :attr:`ru_stime` attributes of the resource usage are
+   :class:`float` by default, set the *timestamp* argument to get another
+   :ref:`timestamp type <timestamp-types>`.
 
    Availability: Unix.
 
+   .. versionchanged:: 3.3
+      Added the *timestamp* argument.
+
 
 .. data:: WNOHANG
 

Doc/library/time.rst

@@ -95,6 +95,14 @@ An explanation of some terminology and conventions is in order.
   | local time              |                         |                         |
   +-------------------------+-------------------------+-------------------------+
 
+.. _timestamp-types:
+
+* Python supports the following timestamp types:
+
+  * :class:`int`
+  * :class:`float`
+  * :class:`decimal.Decimal`
+
 
 The module defines the following functions and data items:
 
@@ -119,7 +127,7 @@ The module defines the following functions and data items:
       trailing newline.
 
 
-.. function:: clock()
+.. function:: clock(timestamp=float)
 
    .. index::
       single: CPU time
@@ -136,16 +144,27 @@ The module defines the following functions and data items:
    :c:func:`QueryPerformanceCounter`. The resolution is typically better than one
    microsecond.
 
+   Return as a floating point number by default, set the *timestamp* argument
+   to get another :ref:`timestamp type <timestamp-types>`.
+
+   .. versionchanged:: 3.3
+      Added the *timestamp* argument.
+
 
-.. function:: clock_getres(clk_id)
+.. function:: clock_getres(clk_id, timestamp=float)
 
    Return the resolution (precision) of the specified clock *clk_id*.
+   Return a floating point number by default, set the *timestamp* argument to
+   get another :ref:`timestamp type <timestamp-types>`.
+
 
    .. versionadded:: 3.3
 
-.. function:: clock_gettime(clk_id)
+.. function:: clock_gettime(clk_id, timestamp=float)
 
    Return the time of the specified clock *clk_id*.
+   Return a floating point number by default, set the *timestamp* argument to
+   get another :ref:`timestamp type <timestamp-types>`.
 
    .. versionadded:: 3.3
 
@@ -214,19 +233,22 @@ The module defines the following functions and data items:
    flag is set to ``1`` when DST applies to the given time.
 
 
-.. function:: mktime(t)
+.. function:: mktime(t, timestamp=float)
 
    This is the inverse function of :func:`localtime`.  Its argument is the
    :class:`struct_time` or full 9-tuple (since the dst flag is needed; use ``-1``
    as the dst flag if it is unknown) which expresses the time in *local* time, not
-   UTC.  It returns a floating point number, for compatibility with :func:`time`.
+   It returns a floating point number by default, for compatibility with
+   :func:`time`, set the *timestamp* argument to get another :ref:`timestamp
+   type <timestamp-types>`.
+
    If the input value cannot be represented as a valid time, either
    :exc:`OverflowError` or :exc:`ValueError` will be raised (which depends on
    whether the invalid value is caught by Python or the underlying C libraries).
    The earliest date for which it can generate a time is platform-dependent.
 
 
-.. function:: monotonic()
+.. function:: monotonic(timestamp=float)
 
    Monotonic clock.  The reference point of the returned value is undefined so
    only the difference of consecutive calls is valid.
@@ -440,15 +462,20 @@ The module defines the following functions and data items:
    :exc:`TypeError` is raised.
 
 
-.. function:: time()
+.. function:: time(timestamp=float)
 
-   Return the time as a floating point number expressed in seconds since the epoch,
-   in UTC.  Note that even though the time is always returned as a floating point
+   Return the time expressed in seconds since the epoch in UTC. Return a
+   floating point number by default, set the *timestamp* argument to get
+   another :ref:`timestamp type <timestamp-types>`.
+   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.
 
+   .. versionchanged:: 3.3
+      Added the *timestamp* argument.
+
 
 .. data:: timezone
 
@@ -546,13 +573,16 @@ The module defines the following functions and data items:
       ('EET', 'EEST')
 
 
-.. function:: wallclock()
+.. function:: wallclock(timestamp=float)
 
    .. index::
       single: Wallclock
       single: benchmarking
 
    Return the current time in fractions of a second to the system's best ability.
+   Return a floating point number by default, set the *timestamp* argument to
+   get another :ref:`timestamp type <timestamp-types>`.
+
    Use this when the most accurate representation of wall-clock is required, i.e.
    when "processor time" is inappropriate.  The reference point of the returned
    value is undefined so only the difference of consecutive calls is valid.

Doc/whatsnew/3.3.rst

@@ -270,6 +270,42 @@ new, more precise information::
    '<function C.D.meth at 0x7f46b9fe31e0>'
 
 
+PEP 410: Use decimal.Decimal type for timestamps
+================================================
+
+:pep:`410` - Use decimal.Decimal type for timestamps
+ PEP written and implemented by Victor Stinner.
+
+The following functions have a new optional *timestamp* argument to get a
+timestamp as a :class:`decimal.Decimal` instead of :class:`int` or
+:class:`float`:
+
+ * :mod:`time` module: :func:`~time.clock`, :func:`~time.clock_gettime`,
+   :func:`~time.clock_getres`, :func:`~time.monotonic`, :func:`~time.time` and
+   :func:`~time.wallclock`
+ * :mod:`os` module: :func:`~os.fstat`, :func:`~os.fstatat`, :func:`~os.lstat`
+   and :func:`~os.stat` (``st_atime``, ``st_ctime`` and ``st_mtime`` fields of
+   the stat structure)
+
+:class:`decimal.Decimal` supports a resolution of a nanosecond (10^-9)
+resolution, whereas :class:`float` has only a resolution of a microsecond
+(10^-6) in common cases. See the list of available :ref:`timestamp types
+<timestamp-types>`.
+
+Example::
+
+    >>> import decimal, time
+    >>> time.time()
+    1328006975.681211
+    >>> time.time(timestamp=int)
+    1328006979
+    >>> time.time(timestamp=decimal.Decimal)
+    Decimal('1328006983.761119')
+
+:func:`os.stat_float_times` has been deprecated, use *timestamp* argument of
+`os.stat` instead.
+
+
 Other Language Changes
 ======================
 

Include/pytime.h

@@ -2,7 +2,8 @@
 #ifndef Py_PYTIME_H
 #define Py_PYTIME_H
 
-#include "pyconfig.h" /* include for defines */
+#include "pyport.h"
+#include "object.h"
 
 /**************************************************************************
 Symbols and macros to supply platform-independent interfaces to time related
@@ -37,6 +38,31 @@ do { \
     ((tv_end.tv_sec - tv_start.tv_sec) + \
      (tv_end.tv_usec - tv_start.tv_usec) * 0.000001)
 
+#if defined(HAVE_LONG_LONG)
+typedef unsigned PY_LONG_LONG _PyTime_fraction_t;
+#else
+typedef size_t _PyTime_fraction_t;
+#endif
+
+typedef struct
+{
+    /* timestamp = seconds + numerator / denominator */
+    time_t seconds;
+    _PyTime_fraction_t numerator;
+    /* denominator cannot be zero */
+    _PyTime_fraction_t denominator;
+    /* the timestamp resolution is 1/divisor */
+} _PyTime_t;
+
+/* Similar to POSIX gettimeofday.  If system gettimeofday
+   fails or is not available, fall back to lower resolution clocks.  */
+PyAPI_FUNC(void) _PyTime_get(_PyTime_t *tp);
+
+/* Convert a timestamp structure to the specified timestamp type.
+
+   Raise a ValueError if the timestamp type is unknown. */
+PyAPI_FUNC(PyObject*) _PyTime_Convert(_PyTime_t *ts, PyObject *timestamp);
+
 /* Dummy to force linking. */
 PyAPI_FUNC(void) _PyTime_Init(void);
 

Lib/test/test_os.py

@@ -2,6 +2,7 @@
 # does add tests for a few functions which have been determined to be more
 # portable than they had been thought to be.
 
+import decimal
 import os
 import errno
 import unittest
@@ -238,6 +239,36 @@ class StatAttributeTests(unittest.TestCase):
             warnings.simplefilter("ignore", DeprecationWarning)
             self.check_stat_attributes(fname)
 
+    def test_stat_timestamp(self):
+        # test deprecation
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", DeprecationWarning)
+            self.assertRaises(DeprecationWarning, os.stat_float_times, False)
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            old_value = os.stat_float_times()
+            try:
+                # test invalid timestamp types
+                self.assertRaises(ValueError, os.stat, self.fname,
+                                  timestamp="abc")
+                self.assertRaises(ValueError, os.stat, self.fname,
+                                  timestamp=decimal.Context)
+
+                for float_times in (False, True):
+                    os.stat_float_times(float_times)
+                    t = os.stat(self.fname).st_mtime
+                    if float_times:
+                        self.assertIsInstance(t, float)
+                    else:
+                        self.assertIsInstance(t, int)
+
+                    for type in (int, float, decimal.Decimal):
+                        t = os.stat(self.fname, timestamp=type).st_mtime
+                        self.assertIsInstance(t, type)
+            finally:
+                os.stat_float_times(old_value)
+
     def test_statvfs_attributes(self):
         if not hasattr(os, "statvfs"):
             return

Lib/test/test_time.py

+import locale
+import platform
+import sys
+import sysconfig
 from test import support
 import time
 import unittest
-import locale
-import sysconfig
-import sys
-import platform
 
 # Max year is only limited by the size of C int.
 SIZEOF_INT = sysconfig.get_config_var('SIZEOF_INT') or 4
@@ -345,6 +345,31 @@ class TimeTestCase(unittest.TestCase):
         self.assertGreater(t2, t1)
         self.assertAlmostEqual(dt, 0.1, delta=0.2)
 
+    def test_timestamp(self):
+        import decimal
+        calls = [
+            (time.time,),
+            (time.mktime, time.localtime()),
+        ]
+        if hasattr(time, 'monotonic'):
+            calls.append((time.monotonic,))
+        if hasattr(time, 'wallclock'):
+            calls.append((time.wallclock,))
+        if hasattr(time, 'CLOCK_REALTIME'):
+            if hasattr(time, 'clock_gettime'):
+                calls.append((time.clock_gettime, time.CLOCK_REALTIME))
+            if hasattr(time, 'clock_getres'):
+                calls.append((time.clock_getres, time.CLOCK_REALTIME))
+        for call in calls:
+            func, *args = call
+
+            # test invalid timestamp
+            for invalid in ("int", decimal.Context):
+                self.assertRaises(ValueError, func, *args, timestamp=invalid)
+
+            for type in (int, float, decimal.Decimal):
+                self.assertIsInstance(func(*args, timestamp=type), type)
+
     def test_wallclock(self):
         t1 = time.wallclock()
         t2 = time.wallclock()