Skip to content

Commit 58917a6

Browse files
committed
Bug #947906: An object oriented interface has been added to the calendar
module. It's possible to generate HTML calendar now and the module can be called as a script (e.g. via ``python -mcalendar``).
1 parent 3f144f9 commit 58917a6

File tree

4 files changed

+703
-169
lines changed

4 files changed

+703
-169
lines changed

Doc/lib/libcalendar.tex

Lines changed: 135 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,137 @@ \section{\module{calendar} ---
1515
week to Sunday (6) or to any other weekday. Parameters that specify
1616
dates are given as integers.
1717

18-
Most of these functions rely on the \module{datetime} module which
19-
uses an idealized calendar, the current Gregorian calendar indefinitely
20-
extended in both directions. This matches the definition of the
21-
"proleptic Gregorian" calendar in Dershowitz and Reingold's book
22-
"Calendrical Calculations", where it's the base calendar for all
23-
computations.
18+
Most of these functions and classses rely on the \module{datetime}
19+
module which uses an idealized calendar, the current Gregorian
20+
calendar indefinitely extended in both directions. This matches
21+
the definition of the "proleptic Gregorian" calendar in Dershowitz
22+
and Reingold's book "Calendrical Calculations", where it's the
23+
base calendar for all computations.
24+
25+
\begin{classdesc}{Calendar}{\optional{firstweekday}}
26+
Creates a \class{Calendar} object. \var{firstweekday} is an integer
27+
specifying the first day of the week. 0 is Monday, 6 is Sunday.
28+
29+
A \class{Calendar} object provides several method that can
30+
be used for preparing the calendar data for formatting. This
31+
class doesn't do any formatting itself. This is the job of
32+
subclasses.
33+
\versionadded{2.5}
34+
35+
\begin{methoddesc}{firstweekday}{}
36+
Return the first day of the week (as specified in the constructor
37+
or changed via \method{setfirstweekday()}.
38+
39+
\begin{methoddesc}{setfirstweekday}{weekday}
40+
Set the first day of the week.
41+
42+
\begin{methoddesc}{iterweekdays}{weekday}
43+
Return an iterator for the week day numbers that will be used
44+
for one week. The first number from the iterator will be the
45+
same as the number return by \method{firstweekday()}.
46+
47+
\begin{methoddesc}{itermonthdates}{year, month}
48+
Return an iterator for the month \var{month} (1-12) in the
49+
year \var{year}. This iterator will return all days (as
50+
\class{datetime.date} objects) for the month and all days
51+
before the start of the month or after the end of the month
52+
that are required to get a complete week.
53+
54+
\begin{methoddesc}{itermonthdays2}{year, month}
55+
Return an iterator for the month \var{month} in the year
56+
\var{year} similar to \method{itermonthdates()}. Days returned
57+
will be tuple consisting of a day number and a week day
58+
number.
59+
60+
\begin{methoddesc}{itermonthdays}{year, month}
61+
Return an iterator for the month \var{month} in the year
62+
\var{year} similar to \method{itermonthdates()}. Days returned
63+
will simply be day numbers.
64+
65+
\begin{methoddesc}{monthdatescalendar}{year, month}
66+
Return a list of the weeks in the month \var{month} of
67+
the \var{year} as full weeks. Weeks are lists of seven
68+
\class{datetime.date} objects.
69+
70+
\begin{methoddesc}{monthdays2calendar}{year, month}
71+
Return a list of the weeks in the month \var{month} of
72+
the \var{year} as full weeks. Weeks are lists of seven
73+
tuples of day numbers and weekday numbers.
74+
75+
\begin{methoddesc}{monthdayscalendar}{year, month}
76+
Return a list of the weeks in the month \var{month} of
77+
the \var{year} as full weeks. Weeks are lists of seven
78+
day numbers.
79+
80+
\begin{methoddesc}{yeardatescalendar}{year, month\optional{, width}}
81+
Return the data for the specified year ready for formatting. The return
82+
value is a list of month rows. Each month row contains upto \var{width}
83+
months (defaulting to 3). Each month contains between 4 and 6 weeks and
84+
each week contains 1-7 days. Days are \class{datetime.date} objects.
85+
86+
\begin{methoddesc}{yeardays2calendar}{year, month\optional{, width}}
87+
Return the data for the specified year ready for formatting (similar to
88+
\method{yeardatescalendar()}). Entries in the week lists are tuples of
89+
day numbers and weekday numbers. Day numbers outside this month are zero.
90+
91+
\begin{methoddesc}{yeardayscalendar}{year, month\optional{, width}}
92+
Return the data for the specified year ready for formatting (similar to
93+
\method{yeardatescalendar()}). Entries in the week lists are day numbers.
94+
Day numbers outside this month are zero.
95+
96+
97+
\begin{classdesc}{TextCalendar}{\optional{firstweekday}}
98+
This class can be used for generating plain text calendars.
99+
100+
\versionadded{2.5}
101+
102+
\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, w\optional{, l}}}
103+
Returns a month's calendar in a multi-line string. If \var{w} is
104+
provided, it specifies the width of the date columns, which are
105+
centered. If \var{l} is given, it specifies the number of lines that
106+
each week will use. Depends on the first weekday as set by
107+
\function{setfirstweekday()}.
108+
109+
\begin{methoddesc}{prmonth}{theyear, themonth\optional{, w\optional{, l}}}
110+
Prints a month's calendar as returned by \method{formatmonth()}.
111+
112+
\begin{methoddesc}{formatyear}{theyear, themonth\optional{, w\optional{, l\optional{, c\optional{, m}}}}}
113+
Returns a \var{m}-column calendar for an entire year as a multi-line string.
114+
Optional parameters \var{w}, \var{l}, and \var{c} are for date column
115+
width, lines per week, and number of spaces between month columns,
116+
respectively. Depends on the first weekday as set by
117+
\method{setfirstweekday()}. The earliest year for which a calendar can
118+
be generated is platform-dependent.
119+
120+
\begin{methoddesc}{pryear}{theyear\optional{, w\optional{, l\optional{, c\optional{, m}}}}}
121+
Prints the calendar for an entire year as returned by \method{formatyear()}.
122+
\end{funcdesc}
123+
124+
125+
\begin{classdesc}{HTMLCalendar}{\optional{firstweekday}}
126+
This class can be used for generating HTML calendars.
127+
128+
\versionadded{2.5}
129+
130+
\begin{methoddesc}{formatmonth}{theyear, themonth\optional{, withyear}}
131+
Returns a month's calendar as an HTML table. If \var{withyear} is
132+
true the year will be included in the header, otherwise just the
133+
monthname will be used.
134+
135+
\begin{methoddesc}{formatyear}{theyear, themonth\optional{, width}}
136+
Returns a year's calendar as an HTML table. \var{width} (defaulting to 3)
137+
specifies the number of months per row.
138+
139+
\begin{methoddesc}{formatyearpage}{theyear, themonth\optional{, width\optional{, css\optional{, encoding}}}}
140+
Returns a year's calendar as an complete HTML page. \var{width}
141+
(defaulting to 3) specifies the number of months per row. \var{css}
142+
is the name for the cascading style sheet to be used. \constant{None}
143+
can be passed, if no style sheet should be used. \var{encoding}
144+
specifies the encoding to be used for the output (defaulting
145+
the the system default encoding).
146+
147+
148+
For simple text calendars this module provides the following functions.
24149

25150
\begin{funcdesc}{setfirstweekday}{weekday}
26151
Sets the weekday (\code{0} is Monday, \code{6} is Sunday) to start
@@ -80,11 +205,8 @@ \section{\module{calendar} ---
80205
\end{funcdesc}
81206

82207
\begin{funcdesc}{month}{theyear, themonth\optional{, w\optional{, l}}}
83-
Returns a month's calendar in a multi-line string. If \var{w} is
84-
provided, it specifies the width of the date columns, which are
85-
centered. If \var{l} is given, it specifies the number of lines that
86-
each week will use. Depends on the first weekday as set by
87-
\function{setfirstweekday()}.
208+
Returns a month's calendar in a multi-line string using the
209+
\method{formatmonth} of the \class{TextCalendar} class.
88210
\versionadded{2.0}
89211
\end{funcdesc}
90212

@@ -94,12 +216,8 @@ \section{\module{calendar} ---
94216
\end{funcdesc}
95217

96218
\begin{funcdesc}{calendar}{year\optional{, w\optional{, l\optional{c}}}}
97-
Returns a 3-column calendar for an entire year as a multi-line string.
98-
Optional parameters \var{w}, \var{l}, and \var{c} are for date column
99-
width, lines per week, and number of spaces between month columns,
100-
respectively. Depends on the first weekday as set by
101-
\function{setfirstweekday()}. The earliest year for which a calendar can
102-
be generated is platform-dependent.
219+
Returns a 3-column calendar for an entire year as a multi-line string
220+
using the \method{formatyear} of the \class{TextCalendar} class.
103221
\versionadded{2.0}
104222
\end{funcdesc}
105223

0 commit comments

Comments
 (0)