calendar --- 通用日曆相關函式

原始碼: Lib/calendar.py


該模組可以讓你像 Unix cal 程式一樣輸出日曆,並提供了其他與日曆相關的實用函式。預設情況下,這些日曆以星期一為一週的第一天,星期日為一週的最後一天(歐洲慣例)。可以使用 setfirstweekday() 將一週的第一天設定為星期日(6)或任何其他工作日。指定日期的形參以整數形式給出。對於相關的功能,另請參閱 datetimetime 模組。

該模組中定義的函式和類使用一個理想化的日曆,即當前格列高利曆在兩個方向上無限延伸。這與 Dershowitz 和 Reingold 的著作《Calendrical Calculations》中“proleptic Gregorian”日曆的定義相匹配,在該書中,它是所有計算的基礎日曆。零和負數年份的解釋遵循 ISO 8601 標準。0 年是公元前 1 年,-1 年是公元前 2 年,以此類推。

class calendar.Calendar(firstweekday=0)

建立一個 Calendar 物件。firstweekday 是一個指定一週第一天的整數。MONDAY0(預設值),SUNDAY6

一個 Calendar 物件提供了幾種可用於準備日曆資料以進行格式化的方法。這個類本身不做任何格式化。這是子類的工作。

Calendar 例項擁有以下方法和屬性:

firstweekday

作為整數的一週的第一天 (0–6)。

此屬性也可以分別使用 setfirstweekday()getfirstweekday() 來設定和讀取。

getfirstweekday()

返回當前一週第一天的 int 值 (0–6)。

與讀取 firstweekday 屬性相同。

setfirstweekday(firstweekday)

將一週的第一天設定為以 int (0–6) 形式傳入的 firstweekday

與設定 firstweekday 屬性相同。

iterweekdays()

返回一週內將要使用的星期幾數字的迭代器。迭代器的第一個值將與 firstweekday 屬性的值相同。

itermonthdates(year, month)

返回 yearmonth 月(1-12)的迭代器。這個迭代器將返回該月的所有日期(作為 datetime.date 物件),以及該月開始前或結束後為構成完整一週所需的所有日期。

itermonthdays(year, month)

返回 yearmonth 月的迭代器,類似於 itermonthdates(),但不受 datetime.date 範圍的限制。返回的日期將只是月份中的天數。對於指定月份之外的日期,天數為 0

itermonthdays2(year, month)

返回 yearmonth 月的迭代器,類似於 itermonthdates(),但不受 datetime.date 範圍的限制。返回的日期將是由月份中的天數和星期幾數字組成的元組。

itermonthdays3(year, month)

返回 yearmonth 月的迭代器,類似於 itermonthdates(),但不受 datetime.date 範圍的限制。返回的日期將是由年份、月份和月份中的天陣列成的元組。

在 3.7 版本加入。

itermonthdays4(year, month)

返回 yearmonth 月的迭代器,類似於 itermonthdates(),但不受 datetime.date 範圍的限制。返回的日期將是由年份、月份、月份中的天數和星期幾數字組成的元組。

在 3.7 版本加入。

monthdatescalendar(year, month)

返回 yearmonth 月的周列表,這些周都是完整的。周是由七個 datetime.date 物件組成的列表。

monthdays2calendar(year, month)

返回 yearmonth 月的周列表,這些周都是完整的。周是由七個日期和星期幾組成的元組列表。

monthdayscalendar(year, month)

返回 yearmonth 月的周列表,這些周都是完整的。周是由七個日期數字組成的列表。

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 例項具有以下方法:

formatday(theday, weekday, width)

返回一個表示單個日期的字串,其格式化寬度為給定的 width。如果 theday0,則返回一個指定寬度的空格字串,表示一個空日期。weekday 引數未使用。

formatweek(theweek, w=0)

返回一個不帶換行符的單週字串。如果提供了 w,它指定了日期列的寬度,日期列會居中顯示。這取決於建構函式中指定的或透過 setfirstweekday() 方法設定的第一天。

formatweekday(weekday, width)

返回一個表示單個工作日名稱的字串,其格式化寬度為指定的 widthweekday 引數是一個表示星期幾的整數,其中 0 是星期一,6 是星期日。

formatweekheader(width)

返回一個包含星期幾名稱的標題行的字串,每列的格式化寬度為給定的 width。名稱取決於區域設定,並會填充到指定的寬度。

formatmonth(theyear, themonth, w=0, l=0)

以多行字串的形式返回一個月的日曆。如果提供了 w,它指定了日期列的寬度,日期列會居中顯示。如果給定了 l,它指定了每週將使用的行數。這取決於建構函式中指定的或透過 setfirstweekday() 方法設定的第一天。

formatmonthname(theyear, themonth, width=0, withyear=True)

返回一個表示月份名稱的字串,該字串在指定的 width 內居中。如果 withyearTrue,則在輸出中包含年份。theyearthemonth 引數分別指定了要格式化的名稱的年份和月份。

prmonth(theyear, themonth, w=0, l=0)

列印由 formatmonth() 返回的一個月的日曆。

formatyear(theyear, w=2, l=1, c=6, m=3)

以多行字串的形式返回一個 m 列的全年日曆。可選引數 wlc 分別用於日期列寬、每週行數和月份列之間的空格數。這取決於建構函式中指定的或透過 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 為真,則年份將包含在標題中,否則只使用月份名稱。

formatyear(theyear, width=3)

以 HTML 表格的形式返回一年的日曆。width(預設為 3)指定每行的月份數。

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

以完整的 HTML 頁面形式返回一年的日曆。width(預設為 3)指定每行的月份數。css 是要使用的級聯樣式表的名稱。如果不需要使用樣式表,可以傳遞 Noneencoding 指定用於輸出的編碼(預設為系統預設編碼)。

formatmonthname(theyear, themonth, withyear=True)

以 HTML 表格行的形式返回月份名稱。如果 withyear 為真,則年份將包含在行中,否則只使用月份名稱。

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 為星期日)。為方便起見,提供了 MONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAY 的值。例如,要將每週的第一天設定為星期日:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)
calendar.firstweekday()

返回每週開始日的當前設定。

calendar.isleap(year)

如果 year 是閏年則返回 True,否則返回 False

calendar.leapdays(y1, y2)

返回從 y1y2(不含)範圍內的閏年數,其中 y1y2 是年份。

該函式適用於跨越世紀變化的範圍。

calendar.weekday(year, month, day)

返回 year1970–…)、month112)、day131)的星期幾(0 為星期一)。

calendar.weekheader(n)

返回一個包含縮寫星期名稱的標題。n 指定了一個星期的字元寬度。

calendar.monthrange(year, month)

對於指定的 yearmonth,返回該月第一天的星期幾和該月的天數。

calendar.monthcalendar(year, month)

返回一個表示月份日曆的矩陣。每一行代表一週;月份之外的日期由零表示。除非由 setfirstweekday() 設定,否則每週從星期一開始。

calendar.prmonth(theyear, themonth, w=0, l=0)

列印由 month() 返回的月份日曆。

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)

使用 TextCalendar 類的 formatyear() 方法,以多行字串的形式返回一個3列的全年日曆。

calendar.timegm(tuple)

一個不相關但很方便的函式,它接受一個時間元組(例如由 time 模組中的 gmtime() 函式返回的時間元組),並返回相應的 Unix 時間戳值,假設紀元為 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

一個表示當前區域設定中一週中各天縮寫的序列,其中星期一為第 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

一週中各天的別名,其中 MONDAY0SUNDAY6

3.12 新版功能.

class calendar.Day

將星期幾定義為整數常量的列舉。此列舉的成員作為 MONDAYSUNDAY 匯出到模組作用域。

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

一年中各個月份的別名,其中 JANUARY1DECEMBER12

3.12 新版功能.

class calendar.Month

將一年中的月份定義為整數常量的列舉。此列舉的成員作為 JANUARYDECEMBER 匯出到模組作用域。

3.12 新版功能.

calendar 模組定義了以下異常:

exception calendar.IllegalMonthError(month)

ValueError 的子類,當給定的月份編號超出 1-12(含)範圍時引發。

month

無效的月份編號。

exception calendar.IllegalWeekdayError(weekday)

ValueError 的子類,當給定的星期幾編號超出 0-6(含)範圍時引發。

weekday

無效的星期幾編號。

參見

模組 datetime

提供了面向物件的日期和時間介面,功能與 time 模組類似。

模組 time

低級別的時間相關函式。

命令列用法

在 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

要列印日曆的年份。預設為當前年份。

month

指定要列印日曆的 year 的月份。必須是 1 到 12 之間的數字,且只能在文字模式下使用。預設為列印全年的日曆。

文字模式選項

--width WIDTH, -w WIDTH

日期列在終端列中的寬度。日期在列中居中列印。任何小於 2 的值都將被忽略。預設為 2。

--lines LINES, -l LINES

每週在終端行中的行數。日期頂部對齊列印。任何小於 1 的值都將被忽略。預設為 1。

--spacing SPACING, -s SPACING

月份之間的列間距。任何小於 2 的值都將被忽略。預設為 6。

--months MONTHS, -m MONTHS

每行列印的月份數。預設為 3。

在 3.14 版本發生變更: 預設情況下,今天的日期會以顏色高亮顯示,並可以透過環境變數進行控制

HTML 模式選項

--css CSS, -c CSS

用於日曆的 CSS 樣式表的路徑。此路徑必須是相對於生成的 HTML 的相對路徑,或者是絕對的 HTTP 或 file:/// URL。