add hg and python

1 files changed, 461 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libtime.tex b/sys/src/cmd/python/Doc/lib/libtime.tex
new file mode 100644
index 000000000..f40838a44
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libtime.tex
@@ -0,0 +1,461 @@
+\section{\module{time} ---
+         Time access and conversions}
+
+\declaremodule{builtin}{time}
+\modulesynopsis{Time access and conversions.}
+
+
+This module provides various time-related functions.  It is always
+available, but not all functions are available on all platforms.  Most
+of the functions defined in this module call platform C library
+functions with the same name.  It may sometimes be helpful to consult
+the platform documentation, because the semantics of these functions
+varies among platforms.
+
+An explanation of some terminology and conventions is in order.
+
+\begin{itemize}
+
+\item
+The \dfn{epoch}\index{epoch} is the point where the time starts.  On
+January 1st of that year, at 0 hours, the ``time since the epoch'' is
+zero.  For \UNIX, the epoch is 1970.  To find out what the epoch is,
+look at \code{gmtime(0)}.
+
+\item
+The functions in this module do not handle dates and times before the
+epoch or far in the future.  The cut-off point in the future is
+determined by the C library; for \UNIX, it is typically in
+2038\index{Year 2038}.
+
+\item
+\strong{Year 2000 (Y2K) issues}:\index{Year 2000}\index{Y2K}  Python
+depends on the platform's C library, which generally doesn't have year
+2000 issues, since all dates and times are represented internally as
+seconds since the epoch.  Functions accepting a \class{struct_time}
+(see below) generally require a 4-digit year.  For backward
+compatibility, 2-digit years are supported if the module variable
+\code{accept2dyear} is a non-zero integer; this variable is
+initialized to \code{1} unless the environment variable
+\envvar{PYTHONY2K} is set to a non-empty string, in which case it is
+initialized to \code{0}.  Thus, you can set
+\envvar{PYTHONY2K} to a non-empty string in the environment to require 4-digit
+years for all year input.  When 2-digit years are accepted, they are
+converted according to the \POSIX{} or X/Open standard: values 69-99
+are mapped to 1969-1999, and values 0--68 are mapped to 2000--2068.
+Values 100--1899 are always illegal.  Note that this is new as of
+Python 1.5.2(a2); earlier versions, up to Python 1.5.1 and 1.5.2a1,
+would add 1900 to year values below 1900.
+
+\item
+UTC\index{UTC} is Coordinated Universal Time\index{Coordinated
+Universal Time} (formerly known as Greenwich Mean
+Time,\index{Greenwich Mean Time} or GMT).  The acronym UTC is not a
+mistake but a compromise between English and French.
+
+\item
+DST is Daylight Saving Time,\index{Daylight Saving Time} an adjustment
+of the timezone by (usually) one hour during part of the year.  DST
+rules are magic (determined by local law) and can change from year to
+year.  The C library has a table containing the local rules (often it
+is read from a system file for flexibility) and is the only source of
+True Wisdom in this respect.
+
+\item
+The precision of the various real-time functions may be less than
+suggested by the units in which their value or argument is expressed.
+E.g.\ on most \UNIX{} systems, the clock ``ticks'' only 50 or 100 times a
+second, and on the Mac, times are only accurate to whole seconds.
+
+\item
+On the other hand, the precision of \function{time()} and
+\function{sleep()} is better than their \UNIX{} equivalents: times are
+expressed as floating point numbers, \function{time()} returns the
+most accurate time available (using \UNIX{} \cfunction{gettimeofday()}
+where available), and \function{sleep()} will accept a time with a
+nonzero fraction (\UNIX{} \cfunction{select()} is used to implement
+this, where available).
+
+\item
+The time value as returned by \function{gmtime()},
+\function{localtime()}, and \function{strptime()}, and accepted by
+\function{asctime()}, \function{mktime()} and \function{strftime()},
+is a sequence of 9 integers.  The return values of \function{gmtime()},
+\function{localtime()}, and \function{strptime()} also offer attribute
+names for individual fields.
+
+\begin{tableiii}{c|l|l}{textrm}{Index}{Attribute}{Values}
+  \lineiii{0}{\member{tm_year}}{(for example, 1993)}
+  \lineiii{1}{\member{tm_mon}}{range [1,12]}
+  \lineiii{2}{\member{tm_mday}}{range [1,31]}
+  \lineiii{3}{\member{tm_hour}}{range [0,23]}
+  \lineiii{4}{\member{tm_min}}{range [0,59]}
+  \lineiii{5}{\member{tm_sec}}{range [0,61]; see \strong{(1)} in \function{strftime()} description}
+  \lineiii{6}{\member{tm_wday}}{range [0,6], Monday is 0}
+  \lineiii{7}{\member{tm_yday}}{range [1,366]}
+  \lineiii{8}{\member{tm_isdst}}{0, 1 or -1; see below}
+\end{tableiii}
+
+Note that unlike the C structure, the month value is a
+range of 1-12, not 0-11.  A year value will be handled as described
+under ``Year 2000 (Y2K) issues'' above.  A \code{-1} argument as the
+daylight savings flag, passed to \function{mktime()} will usually
+result in the correct daylight savings state to be filled in.
+
+When a tuple with an incorrect length is passed to a function
+expecting a \class{struct_time}, or having elements of the wrong type, a
+\exception{TypeError} is raised.
+
+\versionchanged[The time value sequence was changed from a tuple to a
+                \class{struct_time}, with the addition of attribute names
+                for the fields]{2.2}
+\end{itemize}
+
+The module defines the following functions and data items:
+
+
+\begin{datadesc}{accept2dyear}
+Boolean value indicating whether two-digit year values will be
+accepted.  This is true by default, but will be set to false if the
+environment variable \envvar{PYTHONY2K} has been set to a non-empty
+string.  It may also be modified at run time.
+\end{datadesc}
+
+\begin{datadesc}{altzone}
+The offset of the local DST timezone, in seconds west of UTC, if one
+is defined.  This is negative if the local DST timezone is east of UTC
+(as in Western Europe, including the UK).  Only use this if
+\code{daylight} is nonzero.
+\end{datadesc}
+
+\begin{funcdesc}{asctime}{\optional{t}}
+Convert a tuple or \class{struct_time} representing a time as returned
+by \function{gmtime()}
+or \function{localtime()} to a 24-character string of the following form:
+\code{'Sun Jun 20 23:21:05 1993'}.  If \var{t} is not provided, the
+current time as returned by \function{localtime()} is used.
+Locale information is not used by \function{asctime()}.
+\note{Unlike the C function of the same name, there is no trailing
+newline.}
+\versionchanged[Allowed \var{t} to be omitted]{2.1}
+\end{funcdesc}
+
+\begin{funcdesc}{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''\index{CPU time}\index{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\index{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 \cfunction{QueryPerformanceCounter()}.
+The resolution is typically better than one microsecond.
+\end{funcdesc}
+
+\begin{funcdesc}{ctime}{\optional{secs}}
+Convert a time expressed in seconds since the epoch to a string
+representing local time. If \var{secs} is not provided or
+\constant{None}, the current time as returned by \function{time()} is
+used.  \code{ctime(\var{secs})} is equivalent to
+\code{asctime(localtime(\var{secs}))}.
+Locale information is not used by \function{ctime()}.
+\versionchanged[Allowed \var{secs} to be omitted]{2.1}
+\versionchanged[If \var{secs} is \constant{None}, the current time is
+                used]{2.4}
+\end{funcdesc}
+
+\begin{datadesc}{daylight}
+Nonzero if a DST timezone is defined.
+\end{datadesc}
+
+\begin{funcdesc}{gmtime}{\optional{secs}}
+Convert a time expressed in seconds since the epoch to a \class{struct_time}
+in UTC in which the dst flag is always zero.  If \var{secs} is not
+provided or \constant{None}, the current time as returned by
+\function{time()} is used.  Fractions of a second are ignored.  See
+above for a description of the \class{struct_time} object. See
+\function{calendar.timegm()} for the inverse of this function.
+\versionchanged[Allowed \var{secs} to be omitted]{2.1}
+\versionchanged[If \var{secs} is \constant{None}, the current time is
+                used]{2.4}
+\end{funcdesc}
+
+\begin{funcdesc}{localtime}{\optional{secs}}
+Like \function{gmtime()} but converts to local time.  If \var{secs} is
+not provided or \constant{None}, the current time as returned by
+\function{time()} is used.  The dst flag is set to \code{1} when DST
+applies to the given time.
+\versionchanged[Allowed \var{secs} to be omitted]{2.1}
+\versionchanged[If \var{secs} is \constant{None}, the current time is
+                used]{2.4}
+\end{funcdesc}
+
+\begin{funcdesc}{mktime}{t}
+This is the inverse function of \function{localtime()}.  Its argument
+is the \class{struct_time} or full 9-tuple (since the dst flag is
+needed; use \code{-1} as the dst flag if it is unknown) which
+expresses the time in
+\emph{local} time, not UTC.  It returns a floating point number, for
+compatibility with \function{time()}.  If the input value cannot be
+represented as a valid time, either \exception{OverflowError} or
+\exception{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.
+\end{funcdesc}
+
+\begin{funcdesc}{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 \function{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.
+\end{funcdesc}
+
+\begin{funcdesc}{strftime}{format\optional{, t}}
+Convert a tuple or \class{struct_time} representing a time as returned
+by \function{gmtime()} or \function{localtime()} to a string as
+specified by the \var{format} argument.  If \var{t} is not
+provided, the current time as returned by \function{localtime()} is
+used.  \var{format} must be a string.  \exception{ValueError} is raised
+if any field in \var{t} is outside of the allowed range.
+\versionchanged[Allowed \var{t} to be omitted]{2.1}
+\versionchanged[\exception{ValueError} raised if a field in \var{t} is
+out of range]{2.4}
+\versionchanged[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.]{2.5}
+
+
+The following directives can be embedded in the \var{format} string.
+They are shown without the optional field width and precision
+specification, and are replaced by the indicated characters in the
+\function{strftime()} result:
+
+\begin{tableiii}{c|p{24em}|c}{code}{Directive}{Meaning}{Notes}
+  \lineiii{\%a}{Locale's abbreviated weekday name.}{}
+  \lineiii{\%A}{Locale's full weekday name.}{}
+  \lineiii{\%b}{Locale's abbreviated month name.}{}
+  \lineiii{\%B}{Locale's full month name.}{}
+  \lineiii{\%c}{Locale's appropriate date and time representation.}{}
+  \lineiii{\%d}{Day of the month as a decimal number [01,31].}{}
+  \lineiii{\%H}{Hour (24-hour clock) as a decimal number [00,23].}{}
+  \lineiii{\%I}{Hour (12-hour clock) as a decimal number [01,12].}{}
+  \lineiii{\%j}{Day of the year as a decimal number [001,366].}{}
+  \lineiii{\%m}{Month as a decimal number [01,12].}{}
+  \lineiii{\%M}{Minute as a decimal number [00,59].}{}
+  \lineiii{\%p}{Locale's equivalent of either AM or PM.}{(1)}
+  \lineiii{\%S}{Second as a decimal number [00,61].}{(2)}
+  \lineiii{\%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)}
+  \lineiii{\%w}{Weekday as a decimal number [0(Sunday),6].}{}
+  \lineiii{\%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)}
+  \lineiii{\%x}{Locale's appropriate date representation.}{}
+  \lineiii{\%X}{Locale's appropriate time representation.}{}
+  \lineiii{\%y}{Year without century as a decimal number [00,99].}{}
+  \lineiii{\%Y}{Year with century as a decimal number.}{}
+  \lineiii{\%Z}{Time zone name (no characters if no time zone exists).}{}
+  \lineiii{\%\%}{A literal \character{\%} character.}{}
+\end{tableiii}
+
+\noindent
+Notes:
+
+\begin{description}
+  \item[(1)]
+    When used with the \function{strptime()} function, the \code{\%p}
+    directive only affects the output hour field if the \code{\%I} directive
+    is used to parse the hour.
+  \item[(2)]
+    The range really is \code{0} to \code{61}; this accounts for leap
+    seconds and the (very rare) double leap seconds.
+  \item[(3)]
+    When used with the \function{strptime()} function, \code{\%U} and \code{\%W}
+    are only used in calculations when the day of the week and the year are
+    specified.
+\end{description}
+
+Here is an example, a format for dates compatible with that specified 
+in the \rfc{2822} Internet email standard.
+	\footnote{The use of \code{\%Z} is now
+	deprecated, but the \code{\%z} escape that expands to the preferred 
+	hour/minute offset is not supported by all ANSI C libraries. Also,
+	a strict reading of the original 1982 \rfc{822} standard calls for
+	a two-digit year (\%y rather than \%Y), but practice moved to
+	4-digit years long before the year 2000.  The 4-digit year has
+        been mandated by \rfc{2822}, which obsoletes \rfc{822}.}
+
+\begin{verbatim}
+>>> from time import gmtime, strftime
+>>> strftime("%a, %d %b %Y %H:%M:%S +0000", gmtime())
+'Thu, 28 Jun 2001 14:17:15 +0000'
+\end{verbatim}
+
+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 \character{\%} of a
+directive in the following order; this is also not portable.
+The field width is normally 2 except for \code{\%j} where it is 3.
+\end{funcdesc}
+
+\begin{funcdesc}{strptime}{string\optional{, format}}
+Parse a string representing a time according to a format.  The return 
+value is a \class{struct_time} as returned by \function{gmtime()} or
+\function{localtime()}.  The \var{format} parameter uses the same
+directives as those used by \function{strftime()}; it defaults to
+\code{"\%a \%b \%d \%H:\%M:\%S \%Y"} which matches the formatting
+returned by \function{ctime()}.  If \var{string} cannot be parsed
+according to \var{format}, \exception{ValueError} is raised.  If the
+string to be parsed has excess data after parsing,
+\exception{ValueError} is raised.  The default values used to fill in
+any missing data when more accurate values cannot be inferred are
+\code{(1900, 1, 1, 0, 0, 0, 0, 1, -1)} .
+
+Support for the \code{\%Z} directive is based on the values contained in
+\code{tzname} and whether \code{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).
+\end{funcdesc}
+
+\begin{datadesc}{struct_time}
+The type of the time value sequence returned by \function{gmtime()},
+\function{localtime()}, and \function{strptime()}.
+\versionadded{2.2}
+\end{datadesc}
+
+\begin{funcdesc}{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.
+\end{funcdesc}
+
+\begin{datadesc}{timezone}
+The offset of the local (non-DST) timezone, in seconds west of UTC
+(negative in most of Western Europe, positive in the US, zero in the
+UK).
+\end{datadesc}
+
+\begin{datadesc}{tzname}
+A tuple of two strings: the first is the name of the local non-DST
+timezone, the second is the name of the local DST timezone.  If no DST
+timezone is defined, the second string should not be used.
+\end{datadesc}
+
+\begin{funcdesc}{tzset}{}
+Resets the time conversion rules used by the library routines.
+The environment variable \envvar{TZ} specifies how this is done.
+\versionadded{2.3}
+
+Availability: \UNIX.
+
+\begin{notice}
+Although in many cases, changing the \envvar{TZ} environment variable
+may affect the output of functions like \function{localtime} without calling 
+\function{tzset}, this behavior should not be relied on.
+
+The \envvar{TZ} environment variable should contain no whitespace.
+\end{notice}
+
+The standard format of the \envvar{TZ} environment variable is:
+(whitespace added for clarity)
+\begin{itemize}
+    \item[std offset [dst [offset] [,start[/time], end[/time]]]]
+\end{itemize}
+
+Where:
+
+\begin{itemize}
+  \item[std and dst]
+    Three or more alphanumerics giving the timezone abbreviations.
+    These will be propagated into time.tzname
+
+  \item[offset]
+    The offset has the form: \plusminus{} hh[:mm[:ss]].
+    This indicates the value added the local time to arrive at UTC. 
+    If preceded by a '-', the timezone is east of the Prime 
+    Meridian; otherwise, it is west. If no offset follows
+    dst, summer time is assumed to be one hour ahead of standard time.
+
+  \item[start[/time],end[/time]]
+    Indicates when to change to and back from DST. The format of the
+    start and end dates are one of the following:
+
+    \begin{itemize}
+      \item[J\var{n}]
+        The Julian day \var{n} (1 <= \var{n} <= 365). Leap days are not 
+        counted, so in all years February 28 is day 59 and
+        March 1 is day 60.
+
+    \item[\var{n}]
+        The zero-based Julian day (0 <= \var{n} <= 365). Leap days are
+        counted, and it is possible to refer to February 29.
+
+      \item[M\var{m}.\var{n}.\var{d}]
+        The \var{d}'th day (0 <= \var{d} <= 6) or week \var{n} 
+        of month \var{m} of the year (1 <= \var{n} <= 5, 
+        1 <= \var{m} <= 12, where week 5 means "the last \var{d} day
+        in month \var{m}" which may occur in either the fourth or 
+        the fifth week). Week 1 is the first week in which the 
+        \var{d}'th day occurs. Day zero is Sunday.
+    \end{itemize}
+
+    time has the same format as offset except that no leading sign ('-' or
+    '+') is allowed. The default, if time is not given, is 02:00:00.
+\end{itemize}
+
+
+\begin{verbatim}
+>>> os.environ['TZ'] = 'EST+05EDT,M4.1.0,M10.5.0'
+>>> time.tzset()
+>>> time.strftime('%X %x %Z')
+'02:07:36 05/08/03 EDT'
+>>> os.environ['TZ'] = 'AEST-10AEDT-11,M10.5.0,M3.5.0'
+>>> time.tzset()
+>>> time.strftime('%X %x %Z')
+'16:08:12 05/08/03 AEST'
+\end{verbatim}
+
+On many \UNIX{} systems (including *BSD, Linux, Solaris, and Darwin), it
+is more convenient to use the system's zoneinfo (\manpage{tzfile}{5}) 
+database to specify the timezone rules. To do this, set the 
+\envvar{TZ} environment variable to the path of the required timezone 
+datafile, relative to the root of the systems 'zoneinfo' timezone database,
+usually located at \file{/usr/share/zoneinfo}. For example, 
+\code{'US/Eastern'}, \code{'Australia/Melbourne'}, \code{'Egypt'} or 
+\code{'Europe/Amsterdam'}.
+
+\begin{verbatim}
+>>> os.environ['TZ'] = 'US/Eastern'
+>>> time.tzset()
+>>> time.tzname
+('EST', 'EDT')
+>>> os.environ['TZ'] = 'Egypt'
+>>> time.tzset()
+>>> time.tzname
+('EET', 'EEST')
+\end{verbatim}
+
+\end{funcdesc}
+
+
+\begin{seealso}
+  \seemodule{datetime}{More object-oriented interface to dates and times.}
+  \seemodule{locale}{Internationalization services.  The locale
+                     settings can affect the return values for some of 
+                     the functions in the \module{time} module.}
+  \seemodule{calendar}{General calendar-related functions.  
+                       \function{timegm()} is the inverse of
+                       \function{gmtime()} from this module.}
+\end{seealso}