calendar
--- 通用日曆相關函式¶
原始碼: Lib/calendar.py
該模組可以讓你像 Unix cal 程式一樣輸出日曆,並提供了其他與日曆相關的實用函式。預設情況下,這些日曆以星期一為一週的第一天,星期日為一週的最後一天(歐洲慣例)。可以使用 setfirstweekday()
將一週的第一天設定為星期日(6)或任何其他工作日。指定日期的形參以整數形式給出。對於相關的功能,另請參閱 datetime
和 time
模組。
該模組中定義的函式和類使用一個理想化的日曆,即當前格列高利曆在兩個方向上無限延伸。這與 Dershowitz 和 Reingold 的著作《Calendrical Calculations》中“proleptic Gregorian”日曆的定義相匹配,在該書中,它是所有計算的基礎日曆。零和負數年份的解釋遵循 ISO 8601 標準。0 年是公元前 1 年,-1 年是公元前 2 年,以此類推。
- class calendar.Calendar(firstweekday=0)¶
建立一個
Calendar
物件。firstweekday 是一個指定一週第一天的整數。MONDAY
是0
(預設值),SUNDAY
是6
。一個
Calendar
物件提供了幾種可用於準備日曆資料以進行格式化的方法。這個類本身不做任何格式化。這是子類的工作。Calendar
例項擁有以下方法和屬性:- firstweekday¶
作為整數的一週的第一天 (0–6)。
此屬性也可以分別使用
setfirstweekday()
和getfirstweekday()
來設定和讀取。
- getfirstweekday()¶
返回當前一週第一天的
int
值 (0–6)。與讀取
firstweekday
屬性相同。
- setfirstweekday(firstweekday)¶
將一週的第一天設定為以
int
(0–6) 形式傳入的 firstweekday。與設定
firstweekday
屬性相同。
- 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
例項具有以下方法:- formatday(theday, weekday, width)¶
返回一個表示單個日期的字串,其格式化寬度為給定的 width。如果 theday 為
0
,則返回一個指定寬度的空格字串,表示一個空日期。weekday 引數未使用。
- formatweek(theweek, w=0)¶
返回一個不帶換行符的單週字串。如果提供了 w,它指定了日期列的寬度,日期列會居中顯示。這取決於建構函式中指定的或透過
setfirstweekday()
方法設定的第一天。
- formatweekday(weekday, width)¶
返回一個表示單個工作日名稱的字串,其格式化寬度為指定的 width。weekday 引數是一個表示星期幾的整數,其中
0
是星期一,6
是星期日。
- formatweekheader(width)¶
返回一個包含星期幾名稱的標題行的字串,每列的格式化寬度為給定的 width。名稱取決於區域設定,並會填充到指定的寬度。
- formatmonth(theyear, themonth, w=0, l=0)¶
以多行字串的形式返回一個月的日曆。如果提供了 w,它指定了日期列的寬度,日期列會居中顯示。如果給定了 l,它指定了每週將使用的行數。這取決於建構函式中指定的或透過
setfirstweekday()
方法設定的第一天。
- formatmonthname(theyear, themonth, width=0, withyear=True)¶
返回一個表示月份名稱的字串,該字串在指定的 width 內居中。如果 withyear 為
True
,則在輸出中包含年份。theyear 和 themonth 引數分別指定了要格式化的名稱的年份和月份。
- 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 為真,則年份將包含在標題中,否則只使用月份名稱。
- 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 為真,則年份將包含在行中,否則只使用月份名稱。
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_month
、cssclass_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(不含)範圍內的閏年數,其中 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)¶
使用
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¶
一週中各天的別名,其中
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¶
無效的月份編號。
- exception calendar.IllegalWeekdayError(weekday)¶
ValueError
的子類,當給定的星期幾編號超出 0-6(含)範圍時引發。- 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。
在 3.14 版本發生變更: 預設情況下,今天的日期會以顏色高亮顯示,並可以透過環境變數進行控制。
HTML 模式選項
- --css CSS, -c CSS¶
用於日曆的 CSS 樣式表的路徑。此路徑必須是相對於生成的 HTML 的相對路徑,或者是絕對的 HTTP 或
file:///
URL。