# 8.2. `calendar` --- Fungsi-fungsi umum yang terkait dengan modul calendar

Source code: Lib/calendar.py

Modul ini mengijinkan saudara untuk mendapatkan keluaran kalender-kalender seperti halnya di program Unix cal, dan menyediakan fungsi-fungsi tambahan yang berguna yang terkait dengan kalender. Secara bawaan, kalender-kalender ini telah ditentukan dimulai dari hari Senin sebagai hari pertama dalam seminggu, dan Sabtu sebagai hari terakhir (merupakan sistem yang dianut oleh Eropa). Gunakan `setfirstweekday()` untuk mengatur hari pertama dalam seminggu ke hari Sabtu (6) atau ke nama hari yang lain. Parameter-parameter yang menentukan tanggal-tanggal diberikan dalam bentuk bilangan bulat. Untuk fungsionalitas yang lain, lihat juga modul-modul `datetime` dan `time`.

Most of these functions and classes rely on the `datetime` module which uses an idealized calendar, the current Gregorian calendar extended in both directions. This matches the definition of the "proleptic Gregorian" calendar in Dershowitz and Reingold's book "Calendrical Calculations", where it's the base calendar for all computations.

class `calendar.``Calendar`(firstweekday=0)

  Membuat suatu objek `Calendar`. firstweekday adalah suatu bilangan bulat yang menentukan hari pertama dalam suatu pekan. `0` mewakili Senin (nilai bawaan), `6` mewakili Minggu.

  Suatu object `Calendar` menyediakan beberapa metode yang dapat digunakan untuk mempersiapkan data kalender yang akan digunakan untuk proses pemformatan setelahnya. Kelas ini tidak dapat melakukan penformatan dengan sendirinya. Proses penformatan merupakan tugas dari subkelas-subkelas di dalam kelas tersebut.

  Instanse-instanse `Calendar` memiliki metode-metode berikut:

  `iterweekdays`()

    Memberikan keluaran suatu iterator berupa nomor hari dalam sepekan yang akan digunakan dalam sepekan. Nilai pertama iterator tersebut sama dengan nilai milik `firstweekday`.

  `itermonthdates`(year, month)

    Memberikan keluaran suatu iterator untuk bulan month (1--12) dalam suatu tahun year. Iterator ini akan memberikan keluaran semua hari (berupa objek `datetime.date`) dalam sebulan dan semua hari sebelum dimulainya bulan tersebut dan sesudah berakhir bulan tersebut yang diperlukan untuk melengkapi 7 hari lengkap dalam sepekan.

  `itermonthdays2`(year, month)

    Return an iterator for the month month in the year year similar to `itermonthdates()`. Days returned will be tuples consisting of a day number and a week day number.

  `itermonthdays`(year, month)

    Return an iterator for the month month in the year year similar to `itermonthdates()`. Days returned will simply be day numbers.

  `monthdatescalendar`(year, month)

    Memberikan keluaran berupa suatu list pekan-pekan dalam suatu bulan month di suatu tahun year sebagai hari-hari lengkap dalam sepekan. Pekan-pekan adalah lists tujuh objek-object `datetime.date`.

  `monthdays2calendar`(year, month)

    Memberikan keluaran berupa suatu list pekan-pekan dalam satu bulan month di suatu tahun year sebagai hari lengkap dalam sepekan. Pekan-pekan adalah lists tujuh tuples tanggal dan nomor hari dalam sepekan.

  `monthdayscalendar`(year, month)

    Memberikan keluaran berupa suatu list pekan-pekan dalam satu bulan month di suatu tahun year sebagai hari lengkap dalam sepekan. Pekan-pekan adalah lists tujuh nomor tanggal.

  `yeardatescalendar`(year, width=3)

    Memberikan keluaran data berdasarkan tahun yang telah ditentukan yang dapat digunakan sebagai input dalam proses penformatan. Nilai keluaran tersebut adalah suatu list bulan tersusun dalam baris-baris. Setiap baris memuat banyaknya width bulan (dipasang secara default di 3). Setiap bulan memuat antara 4 sampai 6 pekan dan setiap pekan memuat 1--7 hari. Hari-hari merupakan objek `datetime.date`.

  `yeardays2calendar`(year, width=3)

    Memberikan keluaran data yang berdasarkan tahun yang telah ditentukan yang dapat digunakan sebagai input dalam proses penformatan (serupa dengan `yeardatescalendar()`). Keluaran yang diberikan di dalam lists pekan berupa tuples yang memuat nomor-nomor hari dan nomor-nomor hari dalam sepekan. Nomor-nomor hari diluar bulan yang ditentukan dipasang pada nilai nol.

  `yeardayscalendar`(year, width=3)

    Memberikan keluaran data yang berdasarkan tahun yang telah ditentukan yang dapat digunakan sebagai input dalam proses penformatan (serupa dengan `yeardatescalendar()`). Keluaran yang diberikan di dalam lists pekan berupa nomor hari. Nomor hari diluar bulan yang ditentukan dipasang pada nilai nol.

class `calendar.``TextCalendar`(firstweekday=0)

  Kelas ini digunakan untuk menbangkitkan kalender-kalender berformat teks biasa / berkas ASCII.

  Instanse-instanse `TextCalendar` memiliki metode-metode berikut:

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

    Memberikan keluaran suatu kalender bulan dalam bentuk suatu string multi-baris. Jika nilai w diberikan, nilai ini akan menentukan lebar dari lajur-lajur tanggal, yang mana string akan disejajarkan rata tengah. Jika nilai l diberikan, nilai ini akan menentukan banyaknya baris yang digunakan untuk tiap pekan. Metode ini bergantung pada penentuan hari pertama dalam sepekan sebagaimana yang telah dipilih dalam constructor atau yang telah diatur dengan metode `setfirstweekday()`.

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

    Mencetak suatu kalender bulan sebagaimana yang diberikan oleh `formatmonth()`.

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

    Memberikan keluaran suatu m-lajur kalender setahun dalam bentuk string multi-baris. Parameter-parameter opsional w, l, dan c adalah lebar lajur tanggal, banyaknya baris tiap minggu, dan banyaknya spasi antara lajur-lajur bulan, berturut-turut. Metode ini bergantung pada penentuan hari pertama dalam sepekan sebagaimana yang telah dipilih dalam constructor atau yang telah diatur dengan metode `setfirstweekday()`. Tahun-tahun awal yang mana suatu kalender dapat dibangkitkan bergantung pada platform yang digunakan.

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

    Mencetak kalender untuk satu tahun penuh sebagaimana yang diberikan oleh `formatyear()`.

class `calendar.``HTMLCalendar`(firstweekday=0)

  Kelas ini dapat digunakan untuk membangkitkan kalender-kalender berformat HTML.

  `HTMLCalendar` instances have the following methods:

  `formatmonth`(theyear, themonth, withyear=True)

    Memberikan keluaran suatu kalender bulan dalam bentuk suatu tabel HTML. Jika nilai withyear adalah logika benar, tahun akan ditampilkan di bagian tajuk. Demikian sebaliknya hanya nama bulan yang ditampilkan.

  `formatyear`(theyear, width=3)

    Memberikan keluaran suatu kalender tahunan dalam bentuk suatu tabel HTML. Argumen width (nilai bawaan adalah 3) menentukan banyaknya bulan tiap baris.

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

    Memberikan keluaran suatu kalender tahunan dalam bentuk suatu halaman HTML lengkap. width (nilai bawaan adalah 3) menentukan banyaknya bulan tiap baris. css adalah nama untuk cascading style sheet yang digunakan. `None` dapat diberikan pada argumen css jika tidak ada style sheet yang digunakan. encoding menentukan pengodean yang digunakan untuk keluaran (nilai bawaan pada sistem adalah nilai bawaan pengodean ini).

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

  Subkelas `TextCalendar` ini dapat ditambahkan suatu nama lokal pada konstruktornya dan akan memberikan keluaran nama-nama bulan dan hari dalam sepekan yang bersesuaian dengan sistem lokal dari komputer. Jika lokal ini memuat suatu pengkodean semua string untuk bulan dan hari dalam sepekan, nama bulan dan hari tersebut akan diberikan dalam unicode.

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

  Subkelas `HTMLCalendar` ini dapat ditambahkan suatu nama lokal pada konstruktornya dan akan memberikan keluaran nama-nama bulan dan hari dalam sepekan yang bersesuaian dengan sistem lokal dari komputer. Jika lokal ini memuat suatu pengkodean semua string untuk bulan dan hari dalam sepekan, nama bulan dan hari tersebut akan diberikan dalam unicode.

Catatan

Metode-metode `formatweekday()` dan `formatmonthname()` dari dua kelas di atas mengubah secara sementara lokal saat itu ke locale yang diberikan. Dikarenakan lokal saat itu merupakan pengaturan process keseluruhan, metode-metode di atas tidak thread-safe.

Untuk kalender-kalender dengan teks sederhana, modul ini menyediakan fungsi-fungsi berikut.

`calendar.``setfirstweekday`(weekday)

  Menetapkan hari dimulainya hitungan minggu (`0` adalah Senin, `6` adalah Minggu). Nilai-nilai `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, dan `SUNDAY` disediakan secara bawaan demi kenyamanan. Sebagai contoh, untuk mengatur hari dimulainya hitungan minggu di hari Minggu:

      import calendar
      calendar.setfirstweekday(calendar.SUNDAY)

`calendar.``firstweekday`()

  Memberikan keluaran-keluaran pengaturan saat ini untuk hari dimulainya hitungan sepekan.

`calendar.``isleap`(year)

  Memberikan keluaran-keluaran `True` jika year adalah suatu tahun kabisat, sebaliknya `False`.

`calendar.``leapdays`(y1, y2)

  Memberikan keluaran banyaknya tahun-tahun kabisat dalam rentang dari y1 sampai y2 (ekslusif, batas rentang tidak ikut diperhitungkan), dengan y1 dan y2 adalah angka tahun.

  Fungsi ini berlaku untuk rentang tahun sampai satu abad.

`calendar.``weekday`(year, month, day)

  Memberikan keluaran hari dalam sepekan (`0` adalah Senin) untuk year (`1970`--...), month (`1`--`12`), day (`1`--`31`).

`calendar.``weekheader`(n)

  Memberikan keluaran suatu tajuk yang memuat singkatan nama-nama hari dalam sepekan. n mengatur lebar dari karakter-karakter tiap nama-nama hari dalam sepekan.

`calendar.``monthrange`(year, month)

  Memberikan keluaran-keluaran hari dari tanggal pertama di bulan yang dipilih dan banyaknya hari dalam bulan tersebut, dengan year dan month sebagai argumen yand diisi oleh pengguna.

`calendar.``monthcalendar`(year, month)

  Returns a matrix representing a month's calendar. Each row represents a week; days outside of the month a represented by zeros. Each week begins with Monday unless set by `setfirstweekday()`.

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

  Mencetak suatu kalender bulan sebagaimana yang diberikan oleh `month()`.

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

  Memberikan keluaran suatu kalender bulan dalam bentuk string multi-baris menggunakan metode `formatmonth()` dari kelas `TextCalendar`.

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

  Mencetak kalender untuk satu tahun penuh sebagaimana yang diberikan oleh fungsi `calendar()`.

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

  Memberikan keluaran suatu kalender 3 lajur untuk satu tahun penuh sebagai suatu string multi-baris menggunakan metode `formatyear()` dari kelas `TextCalendar`.

`calendar.``timegm`(tuple)

  Fungsi yang tak terkait dengan fungsi lain tapi berguna yang menggunakan masukan suatu tuple waktu seperti yang diberikan oleh keluaran fungsi `gmtime()` dalam modul `time`, dan memberikan keluaran yang bersesuaian dengan nilai cap waktu Unix, dengan mengasumsikan zaman dimulai dari tahun 1970, dan penyandian POSIX. Secara fakta, fungsi `time.gmtime()` dan `timegm()` adalah saling invers satu sama lain.

Module `calendar` mengekspor data atribut-atribut berikut:

`calendar.``day_name`

  Suatu array yang mewakili nama hari dalam sepekan berdasarkan pengaturan lokal yang sedang dipakai.

`calendar.``day_abbr`

  Suatu array yang mewakili singkatan nama hari dalam sepekan berdasarkan pengaturan lokal yang sedang dipakai.

`calendar.``month_name`

  Suatu array yang mewakili bulan-bulan dalam suatu tahun berdasarkan pengaturan lokal yang sedang dipakai. Array ini mengikuti aturan normal bahwa Januari merupakan bulan pertama, ditandai dengan angka 1, sehingga array ini akan memiliki panjang 13 item dan `month_name[0]` adalah suatu string kosong.

`calendar.``month_abbr`

  Suatu array yang mewakili singkatan bulan-bulan dalam suatu tahun berdasarkan pengaturan lokal yang sedang dipakai. Array ini mengikuti aturan normal bahwa Januari merupakan bulan pertama, ditandai dengan angka 1, sehingga array ini akan memiliki panjang 13 item dan `month_abbr[0]` adalah suatu string kosong.

Lihat juga

Modul `datetime`

  Antarmuka berorientasi objek untuk penanggalan dan waktu dengan fungsionalitas mirip modul `time`.

Modul `time`

  Fungsi-fungsi waktu tingkat rendah.