147 lines
5.5 KiB
TeX
147 lines
5.5 KiB
TeX
\section{\module{calendar} ---
|
|
General calendar-related functions}
|
|
|
|
\declaremodule{standard}{calendar}
|
|
\modulesynopsis{Functions for working with calendars,
|
|
including some emulation of the \UNIX\ \program{cal}
|
|
program.}
|
|
\sectionauthor{Drew Csillag}{drew_csillag@geocities.com}
|
|
|
|
This module allows you to output calendars like the \UNIX{}
|
|
\program{cal} program, and provides additional useful functions
|
|
related to the calendar. By default, these calendars have Monday as
|
|
the first day of the week, and Sunday as the last (the European
|
|
convention). Use \function{setfirstweekday()} to set the first day of the
|
|
week to Sunday (6) or to any other weekday. Parameters that specify
|
|
dates are given as integers.
|
|
|
|
Most of these functions rely on the \module{datetime} module which
|
|
uses an idealized calendar, the current Gregorian calendar indefinitely
|
|
extended in both directions. This matches the definition of the
|
|
"proleptic Gregorian" calendar in Dershowitz and Reingold's book
|
|
"Calendrical Calculations", where it's the base calendar for all
|
|
computations.
|
|
|
|
\begin{funcdesc}{setfirstweekday}{weekday}
|
|
Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start
|
|
each week. The values \constant{MONDAY}, \constant{TUESDAY},
|
|
\constant{WEDNESDAY}, \constant{THURSDAY}, \constant{FRIDAY},
|
|
\constant{SATURDAY}, and \constant{SUNDAY} are provided for
|
|
convenience. For example, to set the first weekday to Sunday:
|
|
|
|
\begin{verbatim}
|
|
import calendar
|
|
calendar.setfirstweekday(calendar.SUNDAY)
|
|
\end{verbatim}
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{firstweekday}{}
|
|
Returns the current setting for the weekday to start each week.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isleap}{year}
|
|
Returns \constant{True} if \var{year} is a leap year, otherwise
|
|
\constant{False}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{leapdays}{y1, y2}
|
|
Returns the number of leap years in the range
|
|
[\var{y1}\ldots\var{y2}), where \var{y1} and \var{y2} are years.
|
|
\versionchanged[This function didn't work for ranges spanning
|
|
a century change in Python 1.5.2]{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{weekday}{year, month, day}
|
|
Returns the day of the week (\code{0} is Monday) for \var{year}
|
|
(\code{1970}--\ldots), \var{month} (\code{1}--\code{12}), \var{day}
|
|
(\code{1}--\code{31}).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{weekheader}{n}
|
|
Return a header containing abbreviated weekday names. \var{n} specifies
|
|
the width in characters for one weekday.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{monthrange}{year, month}
|
|
Returns weekday of first day of the month and number of days in month,
|
|
for the specified \var{year} and \var{month}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{monthcalendar}{year, month}
|
|
Returns a matrix representing a month's calendar. Each row represents
|
|
a week; days outside of the month a represented by zeros.
|
|
Each week begins with Monday unless set by \function{setfirstweekday()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
|
|
Prints a month's calendar as returned by \function{month()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}}
|
|
Returns a month's calendar in a multi-line string. If \var{w} is
|
|
provided, it specifies the width of the date columns, which are
|
|
centered. If \var{l} is given, it specifies the number of lines that
|
|
each week will use. Depends on the first weekday as set by
|
|
\function{setfirstweekday()}.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{prcal}{year\optional{, w\optional{, l\optional{c}}}}
|
|
Prints the calendar for an entire year as returned by
|
|
\function{calendar()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}}
|
|
Returns a 3-column calendar for an entire year as a multi-line string.
|
|
Optional parameters \var{w}, \var{l}, and \var{c} are for date column
|
|
width, lines per week, and number of spaces between month columns,
|
|
respectively. Depends on the first weekday as set by
|
|
\function{setfirstweekday()}. The earliest year for which a calendar can
|
|
be generated is platform-dependent.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{timegm}{tuple}
|
|
An unrelated but handy function that takes a time tuple such as
|
|
returned by the \function{gmtime()} function in the \refmodule{time}
|
|
module, and returns the corresponding \UNIX{} timestamp value, assuming
|
|
an epoch of 1970, and the POSIX encoding. In fact,
|
|
\function{time.gmtime()} and \function{timegm()} are each others' inverse.
|
|
\versionadded{2.0}
|
|
\end{funcdesc}
|
|
|
|
The \module{calendar} module exports the following data attributes:
|
|
|
|
\begin{datadesc}{day_name}
|
|
An array that represents the days of the week in the
|
|
current locale.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{day_abbr}
|
|
An array that represents the abbreviated days of the week
|
|
in the current locale.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{month_name}
|
|
An array that represents the months of the year in the
|
|
current locale. This follows normal convention
|
|
of January being month number 1, so it has a length of 13 and
|
|
\code{month_name[0]} is the empty string.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{month_abbr}
|
|
An array that represents the abbreviated months of the year
|
|
in the current locale. This follows normal convention
|
|
of January being month number 1, so it has a length of 13 and
|
|
\code{month_abbr[0]} is the empty string.
|
|
\end{datadesc}
|
|
|
|
\begin{seealso}
|
|
\seemodule{datetime}{Object-oriented interface to dates and times
|
|
with similar functionality to the
|
|
\refmodule{time} module.}
|
|
\seemodule{time}{Low-level time related functions.}
|
|
\end{seealso}
|