`calendar` — Funções gerais relacionadas ao calendário¶

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

Cria um objeto Calendar. firstweekday é um inteiro que especifica o primeiro dia da semana. MONDAY é 0 (o padrão), SUNDAY é 6.

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.

Calendar instances have the following methods and attributes:

firstweekday¶

The first weekday as an integer (0–6).

This property can also be set and read using setfirstweekday() and getfirstweekday() respectively.

getfirstweekday()¶

Return an int for the current first weekday (0–6).

Identical to reading the firstweekday property.

setfirstweekday(firstweekday)¶

Set the first weekday to firstweekday, passed as an int (0–6)

Identical to setting the firstweekday property.

iterweekdays()¶: Return an iterator for the week day numbers that will be used for one week. The first value from the iterator will be the same as the value of the firstweekday property.

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 de datetime.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 de datetime.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 de datetime.date. Os dias retornados serão tuplas consistindo de números de um ano, um mês e um dia do mês.

Adicionado 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 de datetime.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.

Adicionado 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 ano 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 ano year como semanas completas. As semanas são listas de números de sete 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)¶: Retorna os dados para o ano especificado prontos para formatação (semelhante a yeardatescalendar()). Entradas nas listas semanais são tuplas de números de dias e números de dias de semana. Números de dias fora deste mês são zero.

yeardayscalendar(year, width=3)¶: Retorna a data para o ano especificado prontos para formatação (semelhante a yeardatescalendar()). Entradas nas listas de semanas são números de dias. Números de dias fora deste mês são zero.

class calendar.TextCalendar(firstweekday=0)¶

Esta classe pode ser usada para gerar texto plano para calendários.

Instâncias de TextCalendar têm os seguintes métodos:

formatday(theday, weekday, width)¶: Retorna uma string representando um único dia formatado com a largura fornecida em width. Se theday for 0, retorna uma string de espaços da largura especificada, representando um dia vazio. O parâmetro weekday não é usado.

formatweek(theweek, w=0)¶: Retorna uma única semana em uma string sem nova linha. Se w for providenciado, isto especifica a largura das colunas de data, que são centrais. Dependendo do primeiro dia da semana conforme especificado no construtor ou configurado pelo método setfirstweekday().

formatweekday(weekday, width)¶: Retorna uma string representando o nome de um único dia da semana formatado para a largura especificada em width. O parâmetro weekday é um inteiro representando o dia da semana, onde 0 é segunda-feira e 6 é domingo.

formatweekheader(width)¶: Retorna uma string contendo a linha de cabeçalho dos nomes dos dias da semana, formatada com a largura fornecida por width para cada coluna. Os nomes dependem das configurações de localidade e são preenchidos até a largura especificada.

formatmonth(theyear, themonth, w=0, l=0)¶: Retorna o calendário do mês em uma string multilinha. Se w for providenciado, isto especifica a largura das colunas de data, que são centrais. Se l for dado, este especifica o número de linhas que cada semana vai usar. Dependendo do primeiro dia da semana conforme especificado no construtor ou configurado pelo método setfirstweekday().

formatmonthname(theyear, themonth, width=0, withyear=True)¶: Retorna uma string representando o nome do mês centralizado dentro da largura especificada em width. Se withyear for True, inclui o ano na saída. Os parâmetros theyear e themonth especificam o ano e o mês para o nome a ser formatado, respectivamente.

prmonth(theyear, themonth, w=0, l=0)¶: Imprime um calendário do mês conforme retornado pelo formatmonth().

formatyear(theyear, w=2, l=1, c=6, m=3)¶: Retorna um calendário com m colunas para um ano inteiro conforme uma string multilinha. Parâmetros opcionais w, l e c definem a largura da coluna data, linhas por semana e números de espaços entre as colunas dos meses, respectivamente. Depende do primeiro dia da semana conforme especificado no construtor ou definido pelo método setfirstweekday(). O ano mais novo para o qual o calendário pode ser gerado depende da plataforma.

pryear(theyear, w=2, l=1, c=6, m=3)¶: Imprime o calendário para um ano inteiro conforme retornado por formatyear().

class calendar.HTMLCalendar(firstweekday=0)¶

Esta classse pode ser usada para gerar calendários HTML.

Instâncias de HTMLCalendar têm os seguintes métodos:

formatmonth(theyear, themonth, withyear=True)¶: Retorna um calendário do mês como uma tabela HTML. Se withyear for verdadeiro, o ano será incluído no cabeçalho, senão apenas o nome do mês será utilizado.

formatyear(theyear, width=3)¶: Retorna um calendário do ano como uma tabela HTML. width (padronizada para 3) especifica o número de meses por linha.

formatyearpage(theyear, width=3, css='calendar.css', encoding=None)¶: Retorna o calendário de um ano como uma página HTML completa. width (padrão 3) especifica o número de meses por linha. css é o nome da folha de estilo em cascata a ser usada. None pode ser passado se nenhuma folha de estilo deve ser usada. encoding especifica a codificação a ser usada para a saída (padrão para a codificação padrão do sistema).

formatmonthname(theyear, themonth, withyear=True)¶: Retorna um nome de mês como uma linha de tabela HTML. Se withyear for verdadeiro, o ano será incluído na linha, senão apenas o nome do mês será utilizado.

HTMLCalendar tem os seguintes atributos que você pode substituir para personalizar as classes CSS usadas pelo calendário:

cssclasses¶

Uma lista de classes CSS usadas para cada dia da semana. A lista de classes padrão é:

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

mais estilos podem ser adicionados para cada dia:

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

Observe que o comprimento desta lista deve ser de sete itens.

cssclass_noday¶: A classe CSS para um dia da semana que ocorre no mês anterior ou seguinte.

Adicionado na versão 3.7.

cssclasses_weekday_head¶: Uma lista de classes CSS usadas para nomes de dias da semana na linha de cabeçalho. O padrão é o mesmo que cssclasses.

Adicionado na versão 3.7.

cssclass_month_head¶: A classe CSS principal do mês (usada por formatmonthname()). O valor padrão é "month".

Adicionado na versão 3.7.

cssclass_month¶: A classe CSS para a tabela do mês inteiro (usada por formatmonth()). O valor padrão é "month".

Adicionado na versão 3.7.

cssclass_year¶: A classe CSS para a tabela de tabelas do ano inteiro (usada por formatyear()). O valor padrão é "year".

Adicionado 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".

Adicionado 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.

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.

Nota

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.

Para calendários de texto simples, 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 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 are 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¶

A sequence that represents the days of the week in the current locale, where Monday is day number 0.

>>> import calendar
>>> list(calendar.day_name)
['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']

calendar.day_abbr¶

A sequence that represents the abbreviated days of the week in the current locale, where Mon is day number 0.

>>> import calendar
>>> list(calendar.day_abbr)
['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']

calendar.MONDAY¶
calendar.TUESDAY¶
calendar.WEDNESDAY¶
calendar.THURSDAY¶
calendar.FRIDAY¶
calendar.SATURDAY¶
calendar.SUNDAY¶: Aliases for the days of the week, where MONDAY is 0 and SUNDAY is 6.

Adicionado na versão 3.12.

class calendar.Day¶: Enumeration defining days of the week as integer constants. The members of this enumeration are exported to the module scope as MONDAY through SUNDAY.

Adicionado na versão 3.12.

calendar.month_name¶

A sequence 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.

>>> import calendar
>>> list(calendar.month_name)
['', 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December']

calendar.month_abbr¶

A sequence 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.

>>> import calendar
>>> list(calendar.month_abbr)
['', 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

calendar.JANUARY¶
calendar.FEBRUARY¶
calendar.MARCH¶
calendar.APRIL¶
calendar.MAY¶
calendar.JUNE¶
calendar.JULY¶
calendar.AUGUST¶
calendar.SEPTEMBER¶
calendar.OCTOBER¶
calendar.NOVEMBER¶
calendar.DECEMBER¶: Aliases for the months of the year, where JANUARY is 1 and DECEMBER is 12.

Adicionado na versão 3.12.

class calendar.Month¶: Enumeration defining months of the year as integer constants. The members of this enumeration are exported to the module scope as JANUARY through DECEMBER.

Adicionado na versão 3.12.

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.

Ver também

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

Uso na linha de comando¶

Adicionado na versão 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

As seguintes opções são aceitas:

--help, -h¶: Mostra a mensagem de ajuda e sai.

--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.

`calendar` — Funções gerais relacionadas ao calendário¶

Uso na linha de comando¶

Tabela de Conteúdo

Tópico anterior

Próximo tópico

Esta página

calendar — Funções gerais relacionadas ao calendário¶

Uso na linha de comando¶

`calendar` — Funções gerais relacionadas ao calendário¶