diff options
| -rw-r--r-- | Modules/timemodule.c | 125 |
1 files changed, 114 insertions, 11 deletions
diff --git a/Modules/timemodule.c b/Modules/timemodule.c index 7b411ae..43b247f 100644 --- a/Modules/timemodule.c +++ b/Modules/timemodule.c @@ -150,6 +150,12 @@ time_time(self, args) return PyFloat_FromDouble(secs); } +static char time_doc[] = +"time() -> floating point number\n\ +\n\ +Return the current time in seconds since the Epoch.\n\ +Fractions of a second may be present if the system clock provides them."; + #ifdef HAVE_CLOCK #ifndef CLOCKS_PER_SEC @@ -205,9 +211,18 @@ time_clock(self, args) return PyFloat_FromDouble((double)diff.LowPart + ((double)rem.LowPart / (double)divisor.LowPart)); } + #define HAVE_CLOCK /* So it gets included in the methods */ #endif /* MS_WIN32 */ +#ifdef HAVE_CLOCK +static char clock_doc[] = +"clock() -> floating point number\n\ +\n\ +Return the CPU time or real time since the start of the process or since\n\ +the first call to clock(). This has as much precision as the system records."; +#endif + static PyObject * time_sleep(self, args) PyObject *self; @@ -222,6 +237,12 @@ time_sleep(self, args) return Py_None; } +static char sleep_doc[] = +"sleep(seconds)\n\ +\n\ +Delay execution for a given number of seconds. The argument may be\n\ +a floating point number for subsecond precision."; + static PyObject * tmtotuple(p) struct tm *p; @@ -267,6 +288,11 @@ time_gmtime(self, args) return time_convert((time_t)when, gmtime); } +static char gmtime_doc[] = +"gmtime(seconds) -> tuple\n\ +\n\ +Convert seconds since the Epoch to a time tuple expressing UTC (a.k.a. GMT)."; + static PyObject * time_localtime(self, args) PyObject *self; @@ -278,6 +304,10 @@ time_localtime(self, args) return time_convert((time_t)when, localtime); } +static char localtime_doc[] = +"localtime(seconds) -> tuple\n\ +Convert seconds since the Epoch to a time tuple expressing local time."; + static int gettmarg(args, p) PyObject *args; @@ -352,6 +382,12 @@ time_strftime(self, args) "bad strftime format or result too big"); return NULL; } + +static char strftime_doc[] = +"strftime(format, tuple) -> string\n\ +\n\ +Convert a time tuple to a string according to a format specification.\n\ +See the library reference manual for formatting codes."; #endif /* HAVE_STRFTIME */ #ifdef HAVE_STRPTIME @@ -383,6 +419,11 @@ time_strptime(self, args) } return tmtotuple(&tm); } + +static char strptime_doc[] = +"strptime(format, string) -> tuple\n\ +Parse a string to a time tuple according to a format specification.\n\ +See the library reference manual for formatting codes (same as strftime())."; #endif /* HAVE_STRPTIME */ static PyObject * @@ -400,6 +441,11 @@ time_asctime(self, args) return PyString_FromString(p); } +static char asctime_doc[] = +"asctime(tuple) -> string\n\ +\n\ +Convert a time tuple to a string, e.g. 'Sat Jun 06 16:26:11 1998'."; + static PyObject * time_ctime(self, args) PyObject *self; @@ -421,6 +467,12 @@ time_ctime(self, args) return PyString_FromString(p); } +static char ctime_doc[] = +"ctime(seconds) -> string\n\ +\n\ +Convert a time in seconds since the Epoch to a string in local time.\n\ +This is equivalent to asctime(localtime(seconds))."; + #ifdef HAVE_MKTIME static PyObject * time_mktime(self, args) @@ -441,26 +493,31 @@ time_mktime(self, args) } return PyFloat_FromDouble((double)tt); } + +static char mktime_doc[] = +"mktime(tuple) -> floating point number\n\ +\n\ +Convert a time tuple in local time to seconds since the Epoch."; #endif /* HAVE_MKTIME */ static PyMethodDef time_methods[] = { - {"time", time_time}, + {"time", time_time, 0, time_doc}, #ifdef HAVE_CLOCK - {"clock", time_clock}, + {"clock", time_clock, 0, clock_doc}, #endif - {"sleep", time_sleep}, - {"gmtime", time_gmtime}, - {"localtime", time_localtime}, - {"asctime", time_asctime}, - {"ctime", time_ctime}, + {"sleep", time_sleep, 0, sleep_doc}, + {"gmtime", time_gmtime, 0, gmtime_doc}, + {"localtime", time_localtime, 0, localtime_doc}, + {"asctime", time_asctime, 0, asctime_doc}, + {"ctime", time_ctime, 0, ctime_doc}, #ifdef HAVE_MKTIME - {"mktime", time_mktime}, + {"mktime", time_mktime, 0, mktime_doc}, #endif #ifdef HAVE_STRFTIME - {"strftime", time_strftime, 1}, + {"strftime", time_strftime, 1, strftime_doc}, #endif #ifdef HAVE_STRPTIME - {"strptime", time_strptime, 1}, + {"strptime", time_strptime, 1, strptime_doc}, #endif {NULL, NULL} /* sentinel */ }; @@ -479,11 +536,57 @@ ins(d, name, v) Py_DECREF(v); } +static char module_doc[] = +"This module provides various functions to manipulate time values.\n\ +\n\ +There are two standard representations of time. One is the number\n\ +of seconds since the Epoch, in UTC (a.k.a. GMT). It may be an integer\n\ +or a floating point number (to represent fractions of seconds).\n\ +The Epoch is system-defined; on Unix, it is generally January 1st, 1970.\n\ +The actual value can be retrieved by calling gmtime(0).\n\ +\n\ +The other representation is a tuple of 9 integers giving local time.\n\ +The tuple items are:\n\ + year (four digits, e.g. 1998)\n\ + month (1-12)\n\ + day (1-31)\n\ + hours (0-23)\n\ + minutes (0-59)\n\ + seconds (0-61, to allow for leap seconds)\n\ + weekday (0-6, Monday is 0)\n\ + Julian day (day in the year, 1-366)\n\ + DST (Daylight Savings Time) flag (-1, 0 or 1)\n\ +If the DST flag is 0, the time is given in the regular time zone;\n\ +if it is 1, the time is given in the DST time zone;\n\ +if it is -1, mktime() should guess based on the date and time.\n\ +\n\ +Variables:\n\ +\n\ +timezone -- difference in seconds between UTC and local standard time\n\ +altzone -- difference in seconds between UTC and local DST time\n\ +daylight -- whether local time should reflect DST\n\ +tzname -- tuple of (standard time zone name, DST time zone name)\n\ +\n\ +Functions:\n\ +\n\ +time() -- return current time in seconds since the Epoch as a float\n\ +clock() -- return CPU time since process start as a float\n\ +sleep() -- delay for a number of seconds given as a float\n\ +gmtime() -- convert seconds since Epoch to UTC tuple\n\ +localtime() -- convert seconds since Epoch to local time tuple\n\ +asctime() -- convert time tuple to string\n\ +ctime() -- convert time in seconds to string\n\ +mktime() -- convert local time tuple to seconds since Epoch\n\ +strftime() -- convert time tuple to string according to format specification\n\ +strptime() -- parse string to time tuple according to format specification\n\ +"; + + void inittime() { PyObject *m, *d; - m = Py_InitModule("time", time_methods); + m = Py_InitModule3("time", time_methods, module_doc); d = PyModule_GetDict(m); #ifdef HAVE_TZNAME tzset(); |