305 lines
12 KiB
TeX
305 lines
12 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 and classses 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{classdesc}{Calendar}{\optional{firstweekday}}
|
|
Creates a \class{Calendar} object. \var{firstweekday} is an integer
|
|
specifying the first day of the week. \code{0} is Monday (the default),
|
|
\code{6} is Sunday.
|
|
|
|
A \class{Calendar} object provides several methods that can
|
|
be used for preparing the calendar data for formatting. This
|
|
class doesn't do any formatting itself. This is the job of
|
|
subclasses.
|
|
\versionadded{2.5}
|
|
\end{classdesc}
|
|
|
|
\class{Calendar} instances have the following methods:
|
|
|
|
\begin{methoddesc}{iterweekdays}{weekday}
|
|
Return an iterator for the week day numbers that will be used
|
|
for one week. The first number from the iterator will be the
|
|
same as the number returned by \method{firstweekday()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{itermonthdates}{year, month}
|
|
Return an iterator for the month \var{month} (1-12) in the
|
|
year \var{year}. This iterator will return all days (as
|
|
\class{datetime.date} objects) for the month and all days
|
|
before the start of the month or after the end of the month
|
|
that are required to get a complete week.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{itermonthdays2}{year, month}
|
|
Return an iterator for the month \var{month} in the year
|
|
\var{year} similar to \method{itermonthdates()}. Days returned
|
|
will be tuples consisting of a day number and a week day
|
|
number.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{itermonthdays}{year, month}
|
|
Return an iterator for the month \var{month} in the year
|
|
\var{year} similar to \method{itermonthdates()}. Days returned
|
|
will simply be day numbers.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{monthdatescalendar}{year, month}
|
|
Return a list of the weeks in the month \var{month} of
|
|
the \var{year} as full weeks. Weeks are lists of seven
|
|
\class{datetime.date} objects.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{monthdays2calendar}{year, month}
|
|
Return a list of the weeks in the month \var{month} of
|
|
the \var{year} as full weeks. Weeks are lists of seven
|
|
tuples of day numbers and weekday numbers.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{monthdayscalendar}{year, month}
|
|
Return a list of the weeks in the month \var{month} of
|
|
the \var{year} as full weeks. Weeks are lists of seven
|
|
day numbers.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}}
|
|
Return the data for the specified year ready for formatting. The return
|
|
value is a list of month rows. Each month row contains up to \var{width}
|
|
months (defaulting to 3). Each month contains between 4 and 6 weeks and
|
|
each week contains 1--7 days. Days are \class{datetime.date} objects.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}}
|
|
Return the data for the specified year ready for formatting (similar to
|
|
\method{yeardatescalendar()}). Entries in the week lists are tuples of
|
|
day numbers and weekday numbers. Day numbers outside this month are zero.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}}
|
|
Return the data for the specified year ready for formatting (similar to
|
|
\method{yeardatescalendar()}). Entries in the week lists are day numbers.
|
|
Day numbers outside this month are zero.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{classdesc}{TextCalendar}{\optional{firstweekday}}
|
|
This class can be used to generate plain text calendars.
|
|
|
|
\versionadded{2.5}
|
|
\end{classdesc}
|
|
|
|
\class{TextCalendar} instances have the following methods:
|
|
|
|
\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}}
|
|
Return 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()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
|
|
Print a month's calendar as returned by \method{formatmonth()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{,
|
|
l\optional{, c\optional{, m}}}}}
|
|
Return a \var{m}-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
|
|
\method{setfirstweekday()}. The earliest year for which a calendar can
|
|
be generated is platform-dependent.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{,
|
|
c\optional{, m}}}}}
|
|
Print the calendar for an entire year as returned by \method{formatyear()}.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}}
|
|
This class can be used to generate HTML calendars.
|
|
|
|
\versionadded{2.5}
|
|
\end{classdesc}
|
|
|
|
\class{HTMLCalendar} instances have the following methods:
|
|
|
|
\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}}
|
|
Return a month's calendar as an HTML table. If \var{withyear} is
|
|
true the year will be included in the header, otherwise just the
|
|
month name will be used.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}}
|
|
Return a year's calendar as an HTML table. \var{width} (defaulting to 3)
|
|
specifies the number of months per row.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{,
|
|
width\optional{, css\optional{, encoding}}}}
|
|
Return a year's calendar as a complete HTML page. \var{width}
|
|
(defaulting to 3) specifies the number of months per row. \var{css}
|
|
is the name for the cascading style sheet to be used. \constant{None}
|
|
can be passed if no style sheet should be used. \var{encoding}
|
|
specifies the encoding to be used for the output (defaulting
|
|
to the system default encoding).
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{classdesc}{LocaleTextCalendar}{\optional{firstweekday\optional{, locale}}}
|
|
This subclass of \class{TextCalendar} can be passed a locale name in the
|
|
constructor and will return month and weekday names in the specified locale.
|
|
If this locale includes an encoding all strings containing month and weekday
|
|
names will be returned as unicode.
|
|
\versionadded{2.5}
|
|
\end{classdesc}
|
|
|
|
|
|
\begin{classdesc}{LocaleHTMLCalendar}{\optional{firstweekday\optional{, locale}}}
|
|
This subclass of \class{HTMLCalendar} can be passed a locale name in the
|
|
constructor and will return month and weekday names in the specified locale.
|
|
If this locale includes an encoding all strings containing month and weekday
|
|
names will be returned as unicode.
|
|
\versionadded{2.5}
|
|
\end{classdesc}
|
|
|
|
|
|
For simple text calendars this module provides the following functions.
|
|
|
|
\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 using the
|
|
\method{formatmonth} of the \class{TextCalendar} class.
|
|
\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
|
|
using the \method{formatyear} of the \class{TextCalendar} class.
|
|
\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}
|