# `calendar` --- General calendar-related functions

ソースコード: Lib/calendar.py

このモジュールは Unix の cal プログラムのようなカレンダー出力を行い、それに加えてカレンダーに関する有益な関数群を提供します。標準ではこれらのカレンダーは（ヨーロッパの慣例に従って）月曜日を週の始まりとし、日曜日を最後の日としています。 `setfirstweekday()` を用いることで、日曜日(6)や他の曜日を週の始まりに設定することができます。日付を表す引数は整数値で与えます。関連する機能として、 `datetime` と `time` モジュールも参照してください。

このモジュールに定義された関数やクラスは理想化されたカレンダー、つまり現在のグレゴリオ暦を過去と未来両方に無限に拡張したものを使っています。これはすべての計算の基礎のカレンダーとなっている、 Dershowitz と Reingold の本 "Calendrical Calculations" 中の "proleptic Gregorian" のカレンダーの定義に合致します。ゼロと負の年は ISO 8601 の基準に定められている通りに扱われます。0 年は 1 BC、-1 年は 2 BC、のように続きます。

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)

    Return an iterator for the month month in the year year similar to `itermonthdates()`, but not restricted by the `datetime.date` range. Days returned will simply be day of the month numbers. For the days outside of the specified month, the day number is `0`.

  itermonthdays2(year, month)

    Return an iterator for the month month in the year year similar to `itermonthdates()`, but not restricted by the `datetime.date` range. Days returned will be tuples consisting of a day of the month number and a week day number.

  itermonthdays3(year, month)

    Return an iterator for the month month in the year year similar to `itermonthdates()`, but not restricted by the `datetime.date` range. Days returned will be tuples consisting of a year, a month and a day of the month numbers.

    バージョン 3.7 で追加.

  itermonthdays4(year, month)

    Return an iterator for the month month in the year year similar to `itermonthdates()`, but not restricted by the `datetime.date` range. Days returned will be tuples consisting of a year, a month, a day of the month, and a day of the week numbers.

    バージョン 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` インスタンスには以下のメソッドがあります:

  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 が真であればヘッダには年も含まれます。そうでなければ月の名前だけが使われます。

  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)

    Return a month name as an HTML table row. If withyear is true the year will be included in the row, otherwise just the month name will be used.

  `HTMLCalendar` has the following attributes you can override to customize the CSS classes used by the calendar:

  cssclasses

    A list of CSS classes used for each weekday. The default class list is:

        cssclasses = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]

    more styles can be added for each day:

        cssclasses = ["mon text-bold", "tue", "wed", "thu", "fri", "sat", "sun red"]

    Note that the length of this list must be seven items.

  cssclass_noday

    The CSS class for a weekday occurring in the previous or coming month.

    バージョン 3.7 で追加.

  cssclasses_weekday_head

    A list of CSS classes used for weekday names in the header row. The default is the same as `cssclasses`.

    バージョン 3.7 で追加.

  cssclass_month_head

    The month's head CSS class (used by `formatmonthname()`). The default value is `"month"`.

    バージョン 3.7 で追加.

  cssclass_month

    The CSS class for the whole month's table (used by `formatmonth()`). The default value is `"month"`.

    バージョン 3.7 で追加.

  cssclass_year

    The CSS class for the whole year's table of tables (used by `formatyear()`). The default value is `"year"`.

    バージョン 3.7 で追加.

  cssclass_year_head

    The CSS class for the table head for the whole year (used by `formatyear()`). The default value is `"year"`.

    バージョン 3.7 で追加.

  Note that although the naming for the above described class attributes is singular (e.g. `cssclass_month` `cssclass_noday`), one can replace the single CSS class with a space separated list of CSS classes, for example:

      "text-bold text-red"

  Here is an example how `HTMLCalendar` can be customized:

      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)

  This subclass of `TextCalendar` can be passed a locale name in the constructor and will return month and weekday names in the specified locale.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

  This subclass of `HTMLCalendar` can be passed a locale name in the constructor and will return month and weekday names in the specified locale.

注釈

The constructor, `formatweekday()` and `formatmonthname()` methods of these two classes temporarily change the `LC_TIME` locale to the given locale. Because the current locale is a process-wide setting, they are not thread-safe.

単純なテキストのカレンダーに関して、このモジュールには以下のような関数が提供されています。

calendar.setfirstweekday(weekday)

  週の最初の曜日(`0` は月曜日, `6` は日曜日)を設定します。定数 `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY` 及び `SUNDAY` は便宜上提供されています。例えば、日曜日を週の開始日に設定するときは:

      import calendar
      calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

  現在設定されている週の最初の曜日を返します。

calendar.isleap(year)

  year が閏年なら `True` を、そうでなければ `False` を返します。

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)

  月のカレンダーを行列で返します。各行が週を表し、月の範囲外の日は0になります。それぞれの週は `setfirstweekday()` で設定をしていない限り月曜日から始まります。

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

  `month()` 関数によって返される月のカレンダーを出力します。

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

  Returns a month's calendar in a multi-line string using the `formatmonth()` of the `TextCalendar` class.

calendar.prcal(year, w=0, l=0, c=6, m=3)

  `calendar()` 関数で返される一年間のカレンダーを出力します。

calendar.calendar(year, w=2, l=1, c=6, m=3)

  Returns a 3-column calendar for an entire year as a multi-line string using the `formatyear()` of the `TextCalendar` class.

calendar.timegm(tuple)

  カレンダーと直接は関係無いが、 `time` モジュールの `gmtime()` 関数が返す形式の時刻を表すタプルを引数に取り、1970 を基点とするエポック時刻で POSIX エンコーディングであると仮定して、対応する Unix タイムスタンプの値を返します。実際には、 `time.gmtime()` と `timegm()` はお互いの逆関数です。

`calendar` モジュールの以下のデータ属性を利用することができます:

calendar.day_name

  現在のロケールでの曜日を表す配列です。

calendar.day_abbr

  現在のロケールでの短縮された曜日を表す配列です。

calendar.month_name

  現在のロケールでの月の名を表す配列です。この配列は通常の約束事に従って、1月を数字の 1 で表しますので、長さが 13 ある代わりに `month_name[0]` が空文字列になります。

calendar.month_abbr

  現在のロケールでの短縮された月の名を表す配列です。この配列は通常の約束事に従って、1月を数字の 1 で表しますので、長さが 13 ある代わりに `month_abbr[0]` が空文字列になります。

calendar.MONDAY
calendar.TUESDAY
calendar.WEDNESDAY
calendar.THURSDAY
calendar.FRIDAY
calendar.SATURDAY
calendar.SUNDAY

  Aliases for day numbers, where `MONDAY` is `0` and `SUNDAY` is `6`.

The `calendar` module defines the following exceptions:

exception calendar.IllegalMonthError(month)

  A subclass of `ValueError`, raised when the given month number is outside of the range 1-12 (inclusive).

  month

    The invalid month number.

exception calendar.IllegalWeekdayError(weekday)

  A subclass of `ValueError`, raised when the given weekday number is outside of the range 0-6 (inclusive).

  weekday

    The invalid weekday number.

参考

`datetime` モジュール

  `time` モジュールと似た機能を持った日付と時間用のオブジェクト指向インターフェース。

`time` モジュール

  時間に関連した低水準の関数群。

## コマンドラインからの使用

バージョン 2.5 で追加.

The `calendar` module can be executed as a script from the command line to interactively print a calendar.

    python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
                       [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
                       [year] [month]

For example, to print a calendar for the year 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

  The locale to use for month and weekday names. Defaults to English.

--encoding ENCODING, -e ENCODING

  The encoding to use for output. `--encoding` is required if `--locale` is set.

--type {text,html}, -t {text,html}

  Print the calendar to the terminal as text, or as an HTML document.

year

  The year to print the calendar for. Must be a number between 1 and 9999. Defaults to the current year.

month

  The month of the specified `year` to print the calendar for. Must be a number between 1 and 12, and may only be used in text mode. Defaults to printing a calendar for the full year.

Text-mode options:

--width WIDTH, -w WIDTH

  The width of the date column in terminal columns. The date is printed centred in the column. Any value lower than 2 is ignored. Defaults to 2.

--lines LINES, -l LINES

  The number of lines for each week in terminal rows. The date is printed top-aligned. Any value lower than 1 is ignored. Defaults to 1.

--spacing SPACING, -s SPACING

  The space between months in columns. Any value lower than 2 is ignored. Defaults to 6.

--months MONTHS, -m MONTHS

  The number of months printed per row. Defaults to 3.

HTML-mode options:

--css CSS, -c CSS

  The path of a CSS stylesheet to use for the calendar. This must either be relative to the generated HTML, or an absolute HTTP or `file:///` URL.