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

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)

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

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)

Imprime o calendário para um ano inteiro conforme retornado por 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)

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.

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.