calendar
— General calendar-related functions¶
Código-fonte: Lib/calendar.py
Este módulo permite que você exiba calendários como o programa Unix cal, e fornece funções adicionais úteis relacionadas ao calendário. Por padrão, esses calendários têm a segunda-feira como o primeiro dia da semana, e Domingo como o último (a convenção Europeia). Use setfirstweekday()
para colocar o primeiro dia da semana como Domingo (6) ou para qualquer outro dia da semana. Parâmetros que especificam datas são dados como inteiros. Para funcionalidade relacionada, veja também os módulos datetime
e time
.
As funções e classes definidas neste módulo usam um calendário idealizado, o calendário Gregoriano atual estendido indefinidamente nas duas direções. Isso corresponde à definição do calendário “proleptic Gregorian” (gregoriano proléptico) no livro “Calendrical Calculations” de Dershowitz e Reingold, onde está o calendário base para todas os cálculos. Anos com zero ou negativos são interpretados e prescritos pelo padrão ISO 8601. Ano 0 é 1 A.C., ano -1 é 2 A.C, e de assim em diante.
-
class
calendar.
Calendar
(firstweekday=0)¶ Creates a
Calendar
object. firstweekday is an integer specifying the first day of the week.0
is Monday (the default),6
is Sunday.Um objeto
Calendar
fornece vários métodos que podem ser usados para preparar os dados do calendário para formatação. Esta classe não realiza nenhuma formatação por si mesma. Esse é o trabalho das subclasses.Instâncias de
Calendar
possuem os seguintes métodos:-
iterweekdays
()¶ Retorna um iterador para os números dos dias da semana que serão usados em uma semana. O primeiro valor do iterador será o mesmo que o valor da propriedade
firstweekday
.
-
itermonthdates
(year, month)¶ Retorna um iterador para o mês month (1–12) no ano year. Este iterador retornará todos os dias (como objetos
datetime.date
) para o mês e todos os dias antes do início do mês ou após o final do mês que são necessários para obter uma semana completa.
-
itermonthdays
(year, month)¶ Retorna um iterador para o mês month no ano year semelhante a
itermonthdates()
, mas não restrito pelo intervalo dedatetime.date
. Os dias retornados serão simplesmente os números dos dias do mês. Para os dias fora do mês especificado, o número do dia será0
.
-
itermonthdays2
(year, month)¶ Retorna um iterador para o mês month no ano year semelhante a
itermonthdates()
, mas não restrito pelo intervalo dedatetime.date
. Os dias retornados serão tuplas consistindo de um número de dia do mês e um número de dia da semana.
-
itermonthdays3
(year, month)¶ Retorna um iterador para o mês month no ano year semelhante a
itermonthdates()
, mas não restrito pelo intervalo dedatetime.date
. Os dias retornados serão tuplas consistindo de números de um ano, um mês e um dia do mês.Novo na versão 3.7.
-
itermonthdays4
(year, month)¶ Retorna um iterador para o mês month no ano year semelhante a
itermonthdates()
, mas não restrito pelo intervalo dedatetime.date
. Os dias retornados serão tuplas consistindo de números de um ano, um mês, um dia do mês e um dia da semana.Novo na versão 3.7.
-
monthdatescalendar
(year, month)¶ Retorna uma lista das semanas do mês month do year como semanas completas. As semanas são listas de sete objetos
datetime.date
.
-
monthdays2calendar
(year, month)¶ Retorna uma lista das semanas do mês month do year como semanas completas. As semanas são listas de sete tuplas de números dias e de dias de semanas.
-
monthdayscalendar
(year, month)¶ Retorna uma lista das semanas do mês month do year como semanas completas. As semanas são listas de números de 7 dias.
-
yeardatescalendar
(year, width=3)¶ Retorna os dados para o ano especificado prontos para formatação. O valor de retorno é uma lista de linhas de meses. Cada linha de mês contém até width meses (padrão é 3). Cada mês contém entre 4 e 6 semanas, e cada semana contém 1–7 dias. Os dias são objetos
datetime.date
.
-
yeardays2calendar
(year, width=3)¶ Return the data for the specified year ready for formatting (similar to
yeardatescalendar()
). Entries in the week lists are tuples of day numbers and weekday numbers. Day numbers outside this month are zero.
-
yeardayscalendar
(year, width=3)¶ Return the data for the specified year ready for formatting (similar to
yeardatescalendar()
). Entries in the week lists are day numbers. Day numbers outside this month are zero.
-
-
class
calendar.
TextCalendar
(firstweekday=0)¶ This class can be used to generate plain text calendars.
TextCalendar
instances have the following methods:-
formatmonth
(theyear, themonth, w=0, l=0)¶ Return a month’s calendar in a multi-line string. If w is provided, it specifies the width of the date columns, which are centered. If l is given, it specifies the number of lines that each week will use. Depends on the first weekday as specified in the constructor or set by the
setfirstweekday()
method.
-
prmonth
(theyear, themonth, w=0, l=0)¶ Print a month’s calendar as returned by
formatmonth()
.
-
formatyear
(theyear, w=2, l=1, c=6, m=3)¶ Return a m-column calendar for an entire year as a multi-line string. Optional parameters w, l, and c are for date column width, lines per week, and number of spaces between month columns, respectively. Depends on the first weekday as specified in the constructor or set by the
setfirstweekday()
method. The earliest year for which a calendar can be generated is platform-dependent.
-
pryear
(theyear, w=2, l=1, c=6, m=3)¶ Print the calendar for an entire year as returned by
formatyear()
.
-
-
class
calendar.
HTMLCalendar
(firstweekday=0)¶ This class can be used to generate HTML calendars.
HTMLCalendar
instances have the following methods:-
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.
Novo na versão 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
.Novo na versão 3.7.
-
cssclass_month_head
¶ The month’s head CSS class (used by
formatmonthname()
). The default value is"month"
.Novo na versão 3.7.
-
cssclass_month
¶ The CSS class for the whole month’s table (used by
formatmonth()
). The default value is"month"
.Novo na versão 3.7.
-
cssclass_year
¶ The CSS class for the whole year’s table of tables (used by
formatyear()
). The default value is"year"
.Novo na versão 3.7.
-
cssclass_year_head
¶ The CSS class for the table head for the whole year (used by
formatyear()
). The default value is"year"
.Novo na versão 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.
Nota
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.
Para simples calendários de texto, este módulo fornece as seguintes funções.
-
calendar.
setfirstweekday
(weekday)¶ Sets the weekday (
0
is Monday,6
is Sunday) to start each week. The valuesMONDAY
,TUESDAY
,WEDNESDAY
,THURSDAY
,FRIDAY
,SATURDAY
, andSUNDAY
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.
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 are represented by zeros. Each week begins with Monday unless set by
setfirstweekday()
.
-
calendar.
month
(theyear, themonth, w=0, l=0)¶ Returns a month’s calendar in a multi-line string using the
formatmonth()
of theTextCalendar
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 theTextCalendar
class.
-
calendar.
timegm
(tuple)¶ An unrelated but handy function that takes a time tuple such as returned by the
gmtime()
function in thetime
module, and returns the corresponding Unix timestamp value, assuming an epoch of 1970, and the POSIX encoding. In fact,time.gmtime()
andtimegm()
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.