# `calendar` --- 一般的なカレンダーに関する関数群

ソースコード: 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 は整数で週の始まりの曜日を指定するものです。 `0` が月曜(デフォルト)、 `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 には出力に使うエンコーディングを指定します (デフォルトではシステムデフォルトのエンコーディングです)。

  `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)

  この `TextCalendar` のサブクラスではコンストラクタにロケール名を渡すことができ、メソッドの返り値で月や曜日が指定されたロケールのものになります。このロケールがエンコーディングを含む場合には、月や曜日の入った文字列はユニコードとして返されます。

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

  この `HTMLCalendar` のサブクラスではコンストラクタにロケール名を渡すことができ、メソッドの返り値で月や曜日が指定されたロケールのものになります。このロケールがエンコーディングを含む場合には、月や曜日の入った文字列はユニコードとして返されます。

注釈

これら2つのクラスの `formatweekday()` と `formatmonthname()` メソッドは、一時的に現在の locale を指定された locale に変更します。現在の locale はプロセス全体に影響するので、これらはスレッドセーフではありません。

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

`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)

  `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()` 関数が返す形式の時刻を表すタプルを引数に取り、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]` が空文字列になります。

参考

`datetime` モジュール

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

`time` モジュール

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