Add PyStructSequence_UnnamedField. Add stat_float_times.

Use integers in stat tuple, optionally floats in named fields.

2 files changed, 55 insertions, 3 deletions

diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index 17b7c67..2b4728c 100644
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -854,9 +854,10 @@ the \ctype{stat} structure, namely:
 \member{st_ctime}
 (time of most recent content modification or metadata change).
 
-\versionchanged [The time values are floats, measuring
-  seconds. Fractions of a second may be reported if the system
-  supports that]{2.3}
+\versionchanged [If \function{stat_float_times} returns true, the time
+values are floats, measuring seconds. Fractions of a second may be
+reported if the system supports that. On Mac OS, the times are always
+floats. See \function{stat_float_times} for further discussion. ]{2.3}
 
 On some Unix systems (such as Linux), the following attributes may
 also be available:
@@ -899,6 +900,32 @@ Availability: Macintosh, \UNIX, Windows.
 [Added access to values as attributes of the returned object]{2.2}
 \end{funcdesc}
 
+\begin{funcdesc}{stat_float_times}{\optional{newvalue}}
+Determine whether \class{stat_result} represents time stamps as float
+objects.  If newval is True, future calls to stat() return floats, if
+it is False, future calls return ints.  If newval is omitted, return
+the current setting.
+
+For compatibility with older Python versions, accessing
+\class{stat_result} as a tuple always returns integers. For
+compatibility with Python 2.2, accessing the time stamps by field name
+also returns integers. Applications that want to determine the
+fractions of a second in a time stamp can use this function to have
+time stamps represented as floats. Whether they will actually observe
+non-zero fractions depends on the system.
+
+Future Python releases will change the default of this settings;
+applications that cannot deal with floating point time stamps can then
+use this function to turn the feature off.
+
+It is recommended that this setting is only changed at program startup
+time in the \var{__main__} module; libraries should never change this
+setting. If an application uses a library that works incorrectly if
+floating point time stamps are processed, this application should turn
+the feature off until the library has been corrected.
+
+\end{funcdesc}
+
 \begin{funcdesc}{statvfs}{path}
 Perform a \cfunction{statvfs()} system call on the given path.  The
 return value is an object whose attributes describe the filesystem on
diff --git a/Doc/whatsnew/whatsnew23.tex b/Doc/whatsnew/whatsnew23.tex
index 85f6643..2b14698 100644
--- a/Doc/whatsnew/whatsnew23.tex
+++ b/Doc/whatsnew/whatsnew23.tex
@@ -1067,6 +1067,31 @@ in \module{xml.dom.minidom} can now generate XML output in a
 particular encoding, by specifying an optional encoding argument to
 the \method{toxml()} and \method{toprettyxml()} methods of DOM nodes.
 
+\item The \function{stat} family of functions can now report fractions
+of a second in a time stamp. Similar to \function{time.time}, such
+time stamps are represented as floats.
+
+During testing, it was found that some applications break if time
+stamps are floats. For compatibility, when using the tuple interface
+of the \class{stat_result}, time stamps are represented as integers.
+When using named fields (first introduced in Python 2.2), time stamps
+are still represented as ints, unless \function{os.stat_float_times}
+is invoked:
+
+\begin{verbatim}
+>>> os.stat_float_times(True)
+>>> os.stat("/tmp").st_mtime
+1034791200.6335014
+\end{verbatim}
+
+In Python 2.4, the default will change to return floats.
+
+Application developers should use this feature only if all their
+libraries work properly when confronted with floating point time
+stamps (or use the tuple API). If used, the feature should be
+activated on application level, instead of trying to activate it on a
+per-use basis.
+
 \end{itemize}