Time Module

Time access and conversions.

asctime( [t]) - Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a 24-character string of the following form: 'Sun Jun 20 23:21:05 1993'. If t is not provided, the current time as returned by localtime() is used. Locale information is not used by asctime(). Note: Unlike the C function of the same name, there is no trailing newline. Changed in version 2.1: Allowed t to be omitted.

    asctime()             # 'Tue Apr 01 14:33:23 2008'

clock( ) - On Unix, return the current processor time as a floating point number expressed in seconds. The precision, and in fact the very definition of the meaning of ``processor time'', depends on that of the C function of the same name, but in any case, this is the function to use for benchmarking Python or timing algorithms. On Windows, this function returns wall-clock seconds elapsed since the first call to this function, as a floating point number, based on the Win32 function QueryPerformanceCounter(). The resolution is typically better than one microsecond.

    clock()               # 1.9555558038801022e-006

ctime( [secs]) - Convert a time expressed in seconds since the epoch to a string representing local time. If secs is not provided or None, the current time as returned by time() is used. ctime(secs) is equivalent to asctime(localtime(secs)). Locale information is not used by ctime(). Changed in version 2.1: Allowed secs to be omitted. Changed in version 2.4: If secs is None, the current time is used.

    ctime()               # 'Tue Apr 01 14:33:30 2008'

gmtime( [secs]) - Convert a time expressed in seconds since the epoch to a struct_time in UTC in which the dst flag is always zero. If secs is not provided or None, the current time as returned by time() is used. Fractions of a second are ignored. See above for a description of the struct_time object. See calendar.timegm() for the inverse of this function. Changed in version 2.1: Allowed secs to be omitted. Changed in version 2.4: If secs is None, the current time is used.

    gmtime()              # (2008, 4, 1, 19, 33, 35, 1, 92, 0)

localtime( [secs]) - Like gmtime() but converts to local time. If secs is not provided or None, the current time as returned by time() is used. The dst flag is set to 1 when DST applies to the given time. Changed in version 2.1: Allowed secs to be omitted. Changed in version 2.4: If secs is None, the current time is used.

    localtime()           # (2008, 4, 1, 14, 33, 39, 1, 92, 0)

mktime( t) - This is the inverse function of localtime(). Its argument is the 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 time(). If the input value cannot be represented as a valid time, either OverflowError or 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.

    mktime(localtime())   # 1207078436.0

sleep( secs) - Suspend execution for the given number of seconds. The argument may be a floating point number to indicate a more precise sleep time. The actual suspension time may be less than that requested because any caught signal will terminate the sleep() following execution of that signal's catching routine. Also, the suspension time may be longer than requested by an arbitrary amount because of the scheduling of other activity in the system.

    sleep(1.25)           # [sleep for 1 1/4 seconds]

strftime( format[, t]) - Convert a tuple or struct_time representing a time as returned by gmtime() or localtime() to a string as specified by the format argument. If t is not provided, the current time as returned by localtime() is used. format must be a string. ValueError is raised if any field in t is outside of the allowed range. Changed in version 2.1: Allowed t to be omitted. Changed in version 2.4: ValueError raised if a field in t is out of range. Changed in version 2.5: 0 is now a legal argument for any position in the time tuple; if it is normally illegal the value is forced to a correct one.. The following directives can be embedded in the format string. They are shown without the optional field width and precision specification, and are replaced by the indicated characters in the strftime() result:

    strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())   # 'Tue, 01 Apr 2008 19:34:44 +0000'

    Directive Meaning Notes 
    %a Locale's abbreviated weekday name.  
    %A Locale's full weekday name.  
    %b Locale's abbreviated month name.  
    %B Locale's full month name.  
    %c Locale's appropriate date and time representation.  
    %d Day of the month as a decimal number [01,31].  
    %H Hour (24-hour clock) as a decimal number [00,23].  
    %I Hour (12-hour clock) as a decimal number [01,12].  
    %j Day of the year as a decimal number [001,366].  
    %m Month as a decimal number [01,12].  
    %M Minute as a decimal number [00,59].  
    %p Locale's equivalent of either AM or PM. (1) 
    %S Second as a decimal number [00,61]. (2) 
    %U Week number of the year (Sunday as the first day of the week) as a
        decimal number [00,53]. All days in a new year preceding the first Sunday
    are considered to be in week 0. (3) 
    %w Weekday as a decimal number [0(Sunday),6].  
    %W Week number of the year (Monday as the first day of the week) as a
        decimal number [00,53]. All days in a new year preceding the first Monday
    are considered to be in week 0. (3) 
    %x Locale's appropriate date representation.  
    %X Locale's appropriate time representation.  
    %y Year without century as a decimal number [00,99].  
    %Y Year with century as a decimal number.  
    %Z Time zone name (no characters if no time zone exists).  
    %% A literal "%" character.  


    from time import gmtime, strftime
    strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
    'Thu, 28 Jun 2001 14:17:15 +0000'

    Additional directives may be supported on certain platforms, but only the
    ones listed here have a meaning standardized by ANSI C. 

    On some platforms, an optional field width and precision specification can
    immediately follow the initial "%" of a directive in the following order;
    this is also not portable. The field width is normally 2 except for %j
    where it is 3.

strptime( string[, format]) - Parse a string representing a time according to a format. The return value is a struct_time as returned by gmtime() or localtime(). The format parameter uses the same directives as those used by strftime(); it defaults to "%a %b %d %H:%M:%S %Y" which matches the formatting returned by ctime(). If string cannot be parsed according to format, ValueError is raised. If the string to be parsed has excess data after parsing, ValueError is raised. The default values used to fill in any missing data when more accurate values cannot be inferred are (1900, 1, 1, 0, 0, 0, 0, 1, -1) . Support for the %Z directive is based on the values contained in tzname and whether daylight is true. Because of this, it is platform-specific except for recognizing UTC and GMT which are always known (and are considered to be non-daylight savings timezones).

    strptime(ctime())     # (2008, 4, 1, 14, 35, 18, 1, 92, -1)

time( ) - 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 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.

    time()                # 1207078523.562

tzset( ) - Resets the time conversion rules used by the library routines. The environment variable TZ specifies how this is done. New in version 2.3.

index