diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libos.tex | 33 | ||||
| -rw-r--r-- | Doc/whatsnew/whatsnew23.tex | 25 |
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} |