calendar --- General calendar-related functions

Code source : Lib/calendar.py


Ce module permet d'afficher un calendrier comme le fait le programme Unix cal, et il fournit des fonctions utiles relatives au calendrier. Par défaut, ces calendriers ont le lundi comme premier jour de la semaine et le dimanche comme dernier jour. Utilisez setfirstweekday() pour définir le premier jour de la semaine à dimanche (6) ou à tout autre jour de la semaine. Les paramètres pour spécifier les dates sont donnés sous forme de nombres entiers. Voir aussi les modules datetime et time.

Les fonctions et les classes définies dans ce module utilisent un calendrier idéalisé, le calendrier grégorien actuel s'étendant indéfiniment dans les deux sens. Cela correspond à la définition du calendrier grégorien proleptique dans le livre de Dershowitz et Reingold « Calendrical Calculations », œuvre dans lequel il est le calendrier de référence de tous les calculs. Les années zéros et les années négatives sont interprétées comme prescrit par la norme ISO 8601. L'année 0 est 1 avant JC, l'année -1 est 2 avant JC et ainsi de suite.

class calendar.Calendar(firstweekday=0)

Crée un objet Calendar. firstweekday est un entier spécifiant le premier jour de la semaine, valant par défaut 0 (lundi), pouvant aller jusqu'à 6 (dimanche).

L'objet Calendar fournit plusieurs méthodes pouvant être utilisées pour préparer les données du calendrier pour le formatage. Cette classe ne fait pas de formatage elle-même. Il s'agit du travail des sous-classes.

Les instances de Calendar ont les méthodes suivantes :

iterweekdays()

Renvoie un itérateur sur les numéros des jours d'une semaine. La première valeur est donc la même que la valeur de la propriété firstweekday.

itermonthdates(year, month)

Renvoie un itérateur sur les jours du mois month (1 à 12) de l'année year. Cet itérateur renvoie tous les jours du mois (sous forme d'instances de datetime.date) ainsi que tous les jours avant le début du mois et après la fin du mois nécessaires pour obtenir des semaines complètes.

itermonthdays(year, month)

Renvoie un itérateur sur les jours du mois month de l'année year, comme itermonthdates(), sans être limité par l'intervalle de datetime.date. Les jours renvoyés sont simplement les numéros des jours du mois. Pour les jours en dehors du mois spécifié, le numéro du jour est 0.

itermonthdays2(year, month)

Renvoie un itérateur sur les jours du mois month de l'année year comme itermonthdates(), sans être limité par la plage datetime.date. Les jours renvoyés sont des paires composées du numéro du jour dans le mois et du numéro du jour dans la semaine.

itermonthdays3(year, month)

Renvoie un itérateur sur les jours du month de l'année year, comme itermonthdates(), sans être limité par l'intervalle de datetime.date. Les jours sont renvoyés sous forme de triplets composés du numéro de l'année, du mois et du jour dans le mois.

Nouveau dans la version 3.7.

itermonthdays4(year, month)

Renvoie un itérateur sur les jours du mois month de l'année year, comme itermonthdates(), sans être limité par l'intervalle de datetime.date. Le jours sont renvoyés sous forme de quadruplets contenant le numéro de l'année, du mois, du jour du mois et du jour de la semaine.

Nouveau dans la version 3.7.

monthdatescalendar(year, month)

Renvoie la liste des semaines complètes du mois month de l'année year. Les semaines sont des listes de sept objets datetime.date.

monthdays2calendar(year, month)

Renvoie la liste des semaines complètes du mois month de l'année year. Les semaines sont des listes de sept paires contenant le numéro du jour dans le mois et du numéro du jour dans la semaine.

monthdayscalendar(year, month)

Renvoie la liste des semaines complètes du mois month de l'année year. Les semaines sont une liste de sept numéros de jours.

yeardatescalendar(year, width=3)

Renvoie ce qu'il faut pour afficher correctement une année. La valeur renvoyée est une liste de lignes de mois. Chaque ligne mensuelle contient jusqu'à width mois (avec une valeur par défaut à 3). Chaque mois contient de 4 à 6 semaines et chaque semaine 1 à 7 jours. Les jours sont des objets datetime.date.

yeardays2calendar(year, width=3)

Renvoie ce qu'il faut pour afficher correctement une année, (similaire à yeardatescalendar()). Les listes des semaines contiennent des paires contenant le numéro du jour du mois et le numéro du jour de la semaine. Les numéro des jours en dehors de ce mois sont à zéro.

yeardayscalendar(year, width=3)

Renvoie ce qu'il faut pour afficher correctement une année, (similaire à yeardatescalendar()). Les listes de semaines contiennent des numéros de jours. Les numéros de jours en dehors de ce mois sont de zéro.

class calendar.TextCalendar(firstweekday=0)

Cette classe peut être utilisée pour générer des calendriers en texte brut.

Les instances TextCalendar exposent les méthodes suivantes :

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

Donne le calendrier d'un mois dans une chaîne multi-ligne. Si w est fourni, il spécifie la largeur des colonnes de date, qui sont centrées. Si l est donné, il spécifie le nombre de lignes que chaque semaine utilisera. Le résultat varie en fonction du premier jour de la semaine spécifié dans le constructeur ou défini par la méthode setfirstweekday().

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

Affiche le calendrier d'un mois tel que renvoyé par formatmonth().

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

Renvoie un calendrier de m colonnes pour une année entière sous forme de chaîne multi-ligne. Les paramètres facultatifs w, l et c correspondent respectivement à la largeur de la colonne date, les lignes par semaines, le nombre d'espace entre les colonnes de mois. Le résultat varie en fonction du premier jour de la semaine spécifié dans le constructeur ou défini par la méthode setfirstweekday(). La première année pour laquelle un calendrier peut être généré, dépend de la plateforme.

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

Affiche le calendrier pour une année entière comme renvoyé par formatyear().

class calendar.HTMLCalendar(firstweekday=0)

Cette classe peut être utilisée pour générer des calendriers HTML.

Les instances de HTMLCalendar utilisent les méthodes suivantes :

formatmonth(theyear, themonth, withyear=True)

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

formatyear(theyear, width=3)

Return a year's calendar as an HTML table. width (defaulting to 3) specifies the number of months per row.

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

Return a year's calendar as a complete HTML page. width (defaulting to 3) specifies the number of months per row. css is the name for the cascading style sheet to be used. None can be passed if no style sheet should be used. encoding specifies the encoding to be used for the output (defaulting to the system default 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.

Nouveau dans la version 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.

Nouveau dans la version 3.7.

cssclass_month_head

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

Nouveau dans la version 3.7.

cssclass_month

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

Nouveau dans la version 3.7.

cssclass_year

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

Nouveau dans la version 3.7.

cssclass_year_head

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

Nouveau dans la version 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. If this locale includes an encoding all strings containing month and weekday names will be returned as unicode.

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. If this locale includes an encoding all strings containing month and weekday names will be returned as unicode.

Note

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

For simple text calendars this module provides the following functions.

calendar.setfirstweekday(weekday)

Sets the weekday (0 is Monday, 6 is Sunday) to start each week. The values MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, and SUNDAY are provided for convenience. For example, to set the first weekday to Sunday:

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

Returns the current setting for the weekday to start each week.

calendar.isleap(year)

Returns True if year is a leap year, otherwise False.

calendar.leapdays(y1, y2)

Returns the number of leap years in the range from y1 to y2 (exclusive), where y1 and y2 are years.

This function works for ranges spanning a century change.

calendar.weekday(year, month, day)

Returns the day of the week (0 is Monday) for year (1970--...), month (1--12), day (1--31).

calendar.weekheader(n)

Return a header containing abbreviated weekday names. n specifies the width in characters for one weekday.

calendar.monthrange(year, month)

Returns weekday of first day of the month and number of days in month, for the specified year and month.

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)

Prints a month's calendar as returned by 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)

Prints the calendar for an entire year as returned by 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)

An unrelated but handy function that takes a time tuple such as returned by the gmtime() function in the time module, and returns the corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In fact, time.gmtime() and timegm() are each others' inverse.

The calendar module exports the following data attributes:

calendar.day_name

An array that represents the days of the week in the current locale.

calendar.day_abbr

An array that represents the abbreviated days of the week in the current locale.

calendar.month_name

An array that represents the months of the year in the current locale. This follows normal convention of January being month number 1, so it has a length of 13 and month_name[0] is the empty string.

calendar.month_abbr

An array that represents the abbreviated months of the year in the current locale. This follows normal convention of January being month number 1, so it has a length of 13 and month_abbr[0] is the empty string.

Voir aussi

Module datetime
Object-oriented interface to dates and times with similar functionality to the time module.
Module time
Low-level time related functions.