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

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.

Instâncias de Calendar têm 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 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.

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

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

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

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.

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

Novo na versão 3.7.

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

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

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

Novo na versão 3.7.

cssclass_year_head¶: A classe CSS para o cabeçalho da tabela para o ano inteiro (usado por formatyear()). O valor padrão é "year".

Novo na versão 3.7.

Observe que, embora a nomenclatura dos atributos de classe descritos acima seja singular (por exemplo, cssclass_month cssclass_noday), é possível substituir a única classe CSS por uma lista de classes CSS separadas por espaços, por exemplo:

"text-bold text-red"

Aqui está um exemplo de como HTMLCalendar pode ser personalizado:

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)¶: Esta subclasse de TextCalendar pode receber um nome de localidade no construtor e retornará nomes de meses e dias da semana na localidade especificada.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)¶: Esta subclasse de HTMLCalendar pode receber um nome de localidade no construtor e retornará nomes de meses e dias da semana na localidade especificada.

Nota

Os métodos construtores formatweekday() e formatmonthname() dessas duas classes alteram temporariamente a localidade LC_TIME para o locale fornecido. Como a localidade atual é uma configuração de todo o processo, eles não são seguros para threads.

Para calendários de texto simples, este módulo fornece as seguintes funções.

calendar.setfirstweekday(weekday)¶

Define o dia da semana (0 é segunda-feira, 6 é domingo) para começar cada semana. Os valores MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY e SUNDAY são fornecidos para conveniência. Por exemplo, para definir o primeiro dia da semana como domingo:

import calendar
calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()¶: Retorna a configuração atual para o dia da semana que inicia cada semana.

calendar.isleap(year)¶: Retorna True se year for um ano bissexto, caso contrário, False.

calendar.leapdays(y1, y2)¶

Retorna o número de anos bissextos no intervalo de y1 a y2 (exclusivo), onde y1 e y2 são anos.

Esta função funciona para intervalos que abrangem uma mudança de século.

calendar.weekday(year, month, day)¶: Retorna o dia da semana (0 é segunda-feira) para year (1970–…), month (1–12), day (1–31).

calendar.weekheader(n)¶: Retorna um cabeçalho contendo nomes abreviados de dias da semana. n especifica a largura em caracteres para um dia da semana.

calendar.monthrange(year, month)¶: Retorna o dia da semana do primeiro dia do mês e o número de dias do mês, para o year e month especificados.

calendar.monthcalendar(year, month)¶: Retorna uma matriz representando o calendário de um mês. Cada linha representa uma semana; dias fora do mês são representados por zeros. Cada semana começa com segunda-feira, a menos que seja definida por setfirstweekday().

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

calendar.month(theyear, themonth, w=0, l=0)¶: Retorna o calendário de um mês em uma string de várias linhas usando formatmonth() da classe TextCalendar.

calendar.prcal(year, w=0, l=0, c=6, m=3)¶: Imprime o calendário para um ano inteiro conforme retornado por calendar().

calendar.calendar(year, w=2, l=1, c=6, m=3)¶: Retorna um calendário de 3 colunas para um ano inteiro como uma string de várias linhas usando formatyear() da classe TextCalendar.

calendar.timegm(tuple)¶: Uma função não relacionada, mas útil, que pega uma tupla de tempo, como a retornada pela função gmtime() no módulo time, e retorna o valor de registro de data e hora Unix correspondente, persumindo uma época de 1970 e a codificação POSIX. Na verdade, time.gmtime() e timegm() são inversos um do outro.

O módulo calendar exporta os seguintes atributos de dados:

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.

calendar.MONDAY¶
calendar.TUESDAY¶
calendar.WEDNESDAY¶
calendar.THURSDAY¶
calendar.FRIDAY¶
calendar.SATURDAY¶
calendar.SUNDAY¶: Aliases for day numbers, where MONDAY is 0 and SUNDAY is 6.

O módulo calendar define as seguintes exceções:

exception calendar.IllegalMonthError(month)¶

Uma subclasse de ValueError, levantada quando o número do mês fornecido está fora do intervalo de 1 a 12 (inclusive).

month¶: O número de meses inválidos.

exception calendar.IllegalWeekdayError(weekday)¶

Uma subclasse de ValueError, levantada quando o número do dia da semana fornecido está fora do intervalo de 0 a 6 (inclusive).

weekday¶: O número de dias da semana inválidos.

Ver também

Módulo datetime: Interface orientada a objetos para datas e horas com funcionalidade semelhante ao módulo time.
Módulo time: Funções de baixo nível relacionadas ao tempo.

Uso na linha de comando¶

Novo na versão 2.5.

O módulo calendar pode ser executado como um script na linha de comando para exibir interativamente um calendário.

python -m calendar [-h] [-L LOCALE] [-e ENCODING] [-t {text,html}]
                   [-w WIDTH] [-l LINES] [-s SPACING] [-m MONTHS] [-c CSS]
                   [year] [month]

Por exemplo, para exibir um calendário para o ano 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¶: A localidade a ser usada para nomes de meses e dias da semana. O padrão é inglês.

--encoding ENCODING, -e ENCODING¶: A codificação a ser usada para saída. --encoding é necessário se --locale estiver definido.

--type {text,html}, -t {text,html}¶: Exibe o calendário no terminal como texto ou como um documento HTML.

year¶: O ano para exibir o calendário. Deve ser um número entre 1 e 9999.

month¶: O mês do year especificado para exibir o calendário. Deve ser um número entre 1 e 12 e pode ser usado somente no modo texto. O padrão é exibir um calendário para o ano inteiro.

Opções de modo texto:

--width WIDTH, -w WIDTH¶: A largura da coluna de data em colunas terminais. A data é exibida centralizada na coluna. Qualquer valor menor que 2 é ignorado. O padrão é 2.

--lines LINES, -l LINES¶: O número de linhas para cada semana em linhas terminais. A data é exibida alinhada no topo. Qualquer valor menor que 1 é ignorado. O padrão é 1.

--spacing SPACING, -s SPACING¶: O espaço entre os meses em colunas. Qualquer valor menor que 2 é ignorado. O padrão é 6.

--months MONTHS, -m MONTHS¶: O número de meses exibidos por linha. O padrão é 3.

Opções de modo HTML:

--css CSS, -c CSS¶: O caminho de uma folha de estilo CSS a ser usada para o calendário. Isso deve ser relativo ao HTML gerado ou um HTTP absoluto ou URL file:///.

`calendar` — General calendar-related functions¶

Uso na linha de comando¶

Tabela de Conteúdo

Tópico anterior

Próximo tópico

Esta página

calendar — General calendar-related functions¶

Uso na linha de comando¶

`calendar` — General calendar-related functions¶