calendar — 通用日曆相關函式¶
原始碼: Lib/calendar.py
此模組允許您輸出類似 Unix cal 程式的日曆，並提供與日曆相關的其他有用函式。預設情況下，這些日曆將星期一作為一週的第一天，星期日作為最後一天（歐洲慣例）。使用 setfirstweekday() 將一週的第一天設定為星期日 (6) 或任何其他工作日。指定日期的引數以整數形式給出。有關相關功能，另請參閱 datetime 和 time 模組。
此模組中定義的函式和類使用理想化的日曆，即當前格里高利曆在兩個方向上無限延伸。這與 Dershowitz 和 Reingold 的著作《Calendrical Calculations》中“前攝格里高利”日曆的定義相匹配，其中它是所有計算的基本日曆。零年和負年按照 ISO 8601 標準的規定進行解釋。0 年是公元前 1 年，-1 年是公元前 2 年，依此類推。
- class calendar.Calendar(firstweekday=0)¶
建立一個
Calendar物件。firstweekday 是一個整數，指定一週的第一天。MONDAY為0（預設值），SUNDAY為6。Calendar物件提供幾個可用於準備格式化日曆資料的方法。這個類本身不做任何格式化。這是子類的工作。Calendar例項具有以下方法- iterweekdays()¶
返回一個用於一週工作日數字的迭代器。迭代器的第一個值將與
firstweekday屬性的值相同。
- itermonthdates(year, month)¶
返回年份 year 中月份 month (1–12) 的迭代器。此迭代器將返回該月份的所有日期（作為
datetime.date物件）以及該月份開始之前或結束之後的所有日期，這些日期需要構成完整的一週。
- itermonthdays(year, month)¶
返回年份 year 中月份 month 的迭代器，類似於
itermonthdates()，但不受datetime.date範圍的限制。返回的日期將只是月份的日期數字。對於指定月份之外的日期，日期數字為0。
- itermonthdays2(year, month)¶
返回年份 year 中月份 month 的迭代器，類似於
itermonthdates()，但不受datetime.date範圍的限制。返回的日期將是由月份的日期數字和工作日數字組成的元組。
- itermonthdays3(year, month)¶
返回年份 year 中月份 month 的迭代器，類似於
itermonthdates()，但不受datetime.date範圍的限制。返回的日期將是由年份、月份和月份的日期數字組成的元組。3.7 版本新增。
- itermonthdays4(year, month)¶
返回年份 year 中月份 month 的迭代器，類似於
itermonthdates()，但不受datetime.date範圍的限制。返回的日期將是由年份、月份、月份的日期和工作日數字組成的元組。3.7 版本新增。
- monthdatescalendar(year, month)¶
返回 year 年的 month 月份中所有完整週的列表。周是七個
datetime.date物件的列表。
- monthdays2calendar(year, month)¶
返回給定year年份中month月份的完整週列表。周列表包含七個元素的元組，每個元組包含日期數字和星期幾數字。
- monthdayscalendar(year, month)¶
返回給定year年份中month月份的完整週列表。周列表包含七個元素的日期數字列表。
- yeardatescalendar(year, width=3)¶
返回指定年份的格式化資料。返回值是一個月份行列表。每個月份行最多包含width個月（預設為 3）。每個月包含 4 到 6 周，每週包含 1 到 7 天。日期是
datetime.date物件。
- yeardays2calendar(year, width=3)¶
返回指定年份的格式化資料（類似於
yeardatescalendar()）。周列表中的條目是日期數字和星期幾數字的元組。當月之外的日期數字為零。
- yeardayscalendar(year, width=3)¶
返回指定年份的格式化資料（類似於
yeardatescalendar()）。周列表中的條目是日期數字。當月之外的日期數字為零。
- class calendar.TextCalendar(firstweekday=0)¶
此類可用於生成純文字日曆。
TextCalendar例項具有以下方法- formatweek(theweek, w=0)¶
以不帶換行符的字串形式返回單個星期。如果提供了w，則指定日期列的寬度，這些列是居中的。取決於建構函式中指定的或由
setfirstweekday()方法設定的第一天是星期幾。
- formatmonth(theyear, themonth, w=0, l=0)¶
以多行字串形式返回一個月的日曆。如果提供了w，則指定日期列的寬度，這些列是居中的。如果提供了l，則指定每週將使用的行數。取決於建構函式中指定的或由
setfirstweekday()方法設定的第一天是星期幾。
- prmonth(theyear, themonth, w=0, l=0)¶
列印由
formatmonth()返回的月份日曆。
- formatyear(theyear, w=2, l=1, c=6, m=3)¶
以多行字串形式返回整個年份的m列日曆。可選引數w、l和c分別用於日期列寬度、每週行數和月份列之間的空格數。取決於建構函式中指定的或由
setfirstweekday()方法設定的第一天是星期幾。可以生成日曆的最早年份取決於平臺。
- pryear(theyear, w=2, l=1, c=6, m=3)¶
列印由
formatyear()返回的整個年份的日曆。
- class calendar.HTMLCalendar(firstweekday=0)¶
此類可用於生成 HTML 日曆。
HTMLCalendar例項具有以下方法- formatmonth(theyear, themonth, withyear=True)¶
以 HTML 表格形式返回一個月的日曆。如果withyear為 true，則年份將包含在標題中，否則只使用月份名稱。
- formatyear(theyear, width=3)¶
以 HTML 表格形式返回一年的日曆。width（預設為 3）指定每行中的月份數。
- formatyearpage(theyear, width=3, css='calendar.css', encoding=None)¶
以完整的 HTML 頁面形式返回一年的日曆。width（預設為 3）指定每行中的月份數。css 是要使用的層疊樣式表的名稱。如果沒有要使用的樣式表，則可以傳遞
None。encoding 指定要用於輸出的編碼（預設為系統預設編碼）。
- formatmonthname(theyear, themonth, withyear=True)¶
返回一個 HTML 表格行中的月份名稱。如果 withyear 為 true，則該行將包含年份，否則只使用月份名稱。
HTMLCalendar具有以下屬性，您可以覆蓋這些屬性來自定義日曆使用的 CSS 類- cssclasses¶
用於每個工作日的 CSS 類列表。預設的類列表是
cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
可以為每一天新增更多樣式
cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]
請注意，此列表的長度必須為七項。
- cssclass_noday¶
前一個月或下個月中出現的工作日的 CSS 類。
3.7 版本新增。
- cssclasses_weekday_head¶
用於標題行中工作日名稱的 CSS 類列表。預設值與
cssclasses相同。3.7 版本新增。
- cssclass_month_head¶
月份標題 CSS 類（由
formatmonthname()使用）。預設值為"month"。3.7 版本新增。
- cssclass_month¶
整個月份表格的 CSS 類（由
formatmonth()使用）。預設值為"month"。3.7 版本新增。
- cssclass_year¶
整個年份表格的 CSS 類（由
formatyear()使用）。預設值為"year"。3.7 版本新增。
- cssclass_year_head¶
整個年份的表格標題 CSS 類（由
formatyear()使用）。預設值為"year"。3.7 版本新增。
請注意，儘管上述類屬性的命名是單數形式（例如
cssclass_monthcssclass_noday），但可以將單個 CSS 類替換為空格分隔的 CSS 類列表，例如"text-bold text-red"以下是如何自定義
HTMLCalendar的示例class CustomHTMLCal(calendar.HTMLCalendar): cssclasses = [style + " text-nowrap" for style in calendar.HTMLCalendar.cssclasses] cssclass_month_head = "text-center month-head" cssclass_month = "text-center month" cssclass_year = "text-italic lead"
- class calendar.LocaleTextCalendar(firstweekday=0, locale=None)¶
這個
TextCalendar的子類可以在建構函式中傳遞一個區域設定名稱，並將返回指定區域設定中的月份和工作日名稱。
- class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)¶
這個
HTMLCalendar的子類可以在建構函式中傳遞一個區域設定名稱，並將返回指定區域設定中的月份和工作日名稱。
注意
這兩個類的建構函式、formatweekday() 和 formatmonthname() 方法會臨時將 LC_TIME 區域設定更改為給定的 locale。由於當前區域設定是程序範圍的設定，因此它們不是執行緒安全的。
對於簡單的文字日曆，此模組提供以下函式。
- calendar.setfirstweekday(weekday)¶
設定每週開始的工作日（
0是星期一，6是星期日）。為了方便起見，提供了MONDAY、TUESDAY、WEDNESDAY、THURSDAY、FRIDAY、SATURDAY和SUNDAY。 例如，要將第一個工作日設定為星期日import calendar calendar.setfirstweekday(calendar.SUNDAY)
- calendar.firstweekday()¶
返回每週開始的工作日的當前設定。
- calendar.leapdays(y1, y2)¶
返回從 y1 到 y2（不包括 y2）範圍內的閏年數，其中 y1 和 y2 是年份。
此函式適用於跨越世紀變化的範圍。
- calendar.weekday(year, month, day)¶
返回 year (
1970–…)、month (1–12)、day (1–31) 的星期幾（0是星期一）。
- calendar.weekheader(n)¶
返回包含縮寫工作日名稱的標題。 n 指定一個工作日的字元寬度。
- calendar.monthrange(year, month)¶
返回指定 year 和 month 的月份第一天的工作日和月份中的天數。
- calendar.monthcalendar(year, month)¶
返回表示月份日曆的矩陣。每一行代表一週；月份之外的日期用零表示。除非由
setfirstweekday()設定，否則每週從星期一開始。
- calendar.month(theyear, themonth, w=0, l=0)¶
使用
TextCalendar類的formatmonth()返回一個多行字串形式的月份日曆。
- calendar.prcal(year, w=0, l=0, c=6, m=3)¶
列印由
calendar()返回的整年日曆。
- calendar.calendar(year, w=2, l=1, c=6, m=3)¶
返回使用
formatyear()方法的TextCalendar類生成的，包含整年日曆的三列多行字串。
- calendar.timegm(tuple)¶
一個不相關但很方便的函式，它接受一個時間元組（例如由
gmtime()函式在time模組中返回的），並返回相應的 Unix 時間戳值，假設 epoch 為 1970 年，並且使用 POSIX 編碼。實際上，time.gmtime()和timegm()互為逆運算。
calendar 模組匯出以下資料屬性
- calendar.day_name¶
一個序列，表示當前語言環境下的星期幾，其中星期一為第 0 天。
>>> import calendar >>> list(calendar.day_name) ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
- calendar.day_abbr¶
一個序列，表示當前語言環境下星期幾的縮寫，其中 Mon 為第 0 天。
>>> import calendar >>> list(calendar.day_abbr) ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
- calendar.MONDAY¶
- calendar.TUESDAY¶
- calendar.WEDNESDAY¶
- calendar.THURSDAY¶
- calendar.FRIDAY¶
- calendar.SATURDAY¶
- calendar.SUNDAY¶
星期幾的別名，其中
MONDAY為0，SUNDAY為6。3.12 版本新增。
- calendar.month_name¶
一個序列，表示當前語言環境下的月份。這遵循一月為 1 月的正常慣例，所以它的長度為 13，並且
month_name[0]為空字串。>>> import calendar >>> list(calendar.month_name) ['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']
- calendar.month_abbr¶
一個序列，表示當前語言環境下月份的縮寫。這遵循一月為 1 月的正常慣例，所以它的長度為 13，並且
month_abbr[0]為空字串。>>> import calendar >>> list(calendar.month_abbr) ['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
- calendar.JANUARY¶
- calendar.FEBRUARY¶
- calendar.MARCH¶
- calendar.APRIL¶
- calendar.MAY¶
- calendar.JUNE¶
- calendar.JULY¶
- calendar.AUGUST¶
- calendar.SEPTEMBER¶
- calendar.OCTOBER¶
- calendar.NOVEMBER¶
- calendar.DECEMBER¶
月份的別名，其中
JANUARY為1，DECEMBER為12。3.12 版本新增。
calendar 模組定義了以下異常
- exception calendar.IllegalMonthError(month)¶
是
ValueError的子類，當給定的月份數字超出 1-12（含）範圍時引發。- month¶
無效的月份數字。
- 異常 calendar.IllegalWeekdayError(weekday)¶
當給定的工作日數字超出 0-6（含）範圍時引發的
ValueError的子類。- weekday¶
無效的工作日數字。
命令列用法¶
在 2.5 版本中新增。
可以從命令列將 calendar 模組作為指令碼執行，以互動方式列印日曆。
python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
[-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
[-f FIRST_WEEKDAY] [year] [month]
例如，要列印 2000 年的日曆
$ python -m calendar 2000
2000
January February March
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 1 2 3 4 5 6 1 2 3 4 5
3 4 5 6 7 8 9 7 8 9 10 11 12 13 6 7 8 9 10 11 12
10 11 12 13 14 15 16 14 15 16 17 18 19 20 13 14 15 16 17 18 19
17 18 19 20 21 22 23 21 22 23 24 25 26 27 20 21 22 23 24 25 26
24 25 26 27 28 29 30 28 29 27 28 29 30 31
31
April May June
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 1 2 3 4 5 6 7 1 2 3 4
3 4 5 6 7 8 9 8 9 10 11 12 13 14 5 6 7 8 9 10 11
10 11 12 13 14 15 16 15 16 17 18 19 20 21 12 13 14 15 16 17 18
17 18 19 20 21 22 23 22 23 24 25 26 27 28 19 20 21 22 23 24 25
24 25 26 27 28 29 30 29 30 31 26 27 28 29 30
July August September
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 2 1 2 3 4 5 6 1 2 3
3 4 5 6 7 8 9 7 8 9 10 11 12 13 4 5 6 7 8 9 10
10 11 12 13 14 15 16 14 15 16 17 18 19 20 11 12 13 14 15 16 17
17 18 19 20 21 22 23 21 22 23 24 25 26 27 18 19 20 21 22 23 24
24 25 26 27 28 29 30 28 29 30 31 25 26 27 28 29 30
31
October November December
Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su
1 1 2 3 4 5 1 2 3
2 3 4 5 6 7 8 6 7 8 9 10 11 12 4 5 6 7 8 9 10
9 10 11 12 13 14 15 13 14 15 16 17 18 19 11 12 13 14 15 16 17
16 17 18 19 20 21 22 20 21 22 23 24 25 26 18 19 20 21 22 23 24
23 24 25 26 27 28 29 27 28 29 30 25 26 27 28 29 30 31
30 31
接受以下選項
- --help, -h¶
顯示幫助訊息並退出。
- --locale LOCALE, -L LOCALE¶
用於月份和工作日名稱的區域設定。預設為英語。
- --encoding ENCODING, -e ENCODING¶
用於輸出的編碼。如果設定了
--locale，則必須使用--encoding。
- --type {text,html}, -t {text,html}¶
將日曆以文字或 HTML 文件的形式列印到終端。
- --first-weekday FIRST_WEEKDAY, -f FIRST_WEEKDAY¶
每週開始的工作日。必須是 0（星期一）和 6（星期日）之間的數字。預設為 0。
在 3.13 版本中新增。
- year¶
要列印日曆的年份。預設為當前年份。
文字模式選項
- --width WIDTH, -w WIDTH¶
終端列中日期列的寬度。日期在列中居中列印。任何低於 2 的值都將被忽略。預設為 2。
- --lines LINES, -l LINES¶
終端行中每週的行數。日期頂部對齊列印。任何低於 1 的值都將被忽略。預設為 1。
- --spacing SPACING, -s SPACING¶
列中月份之間的空格。任何低於 2 的值都將被忽略。預設為 6。
- --months MONTHS, -m MONTHS¶
每行列印的月份數。預設為 3。
HTML 模式選項
- --css CSS, -c CSS¶
用於日曆的 CSS 樣式表的路徑。這必須是相對於生成的 HTML 的路徑，或者是一個絕對 HTTP 或
file:///URL。