PEP 410

3 files changed, 111 insertions, 16 deletions

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 06f1452..3f10a32 100644
--- a/Doc/library/os.rst
+++ b/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
 
diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 7865b5a..73a9518 100644
--- a/Doc/library/time.rst
+++ b/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.
diff --git a/Doc/whatsnew/3.3.rst b/Doc/whatsnew/3.3.rst
index 8739584..67408c6 100644
--- a/Doc/whatsnew/3.3.rst
+++ b/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
 ======================