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

  Instâncias de `Calendar` têm os seguintes métodos e atributos:

  firstweekday

    O primeiro dia da semana como um inteiro (0–6).

    Esta propriedade também pode ser definida e lida usando `setfirstweekday()` e `getfirstweekday()` respectivamente.

  getfirstweekday()

    Retorna um `int` para o primeiro dia da semana atual (0-6).

    Idêntico à leitura da propriedade `firstweekday`.

  setfirstweekday(firstweekday)

    Define o primeiro dia da semana como firstweekday, passado como `int` (0–6)

    Idêntico à definição da propriedade `firstweekday`.

  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.

    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

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

    Adicionado 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, presumindo 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

  Uma sequência que representa os dias da semana no local atual, onde Monday é o dia número 0.

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

calendar.day_abbr

  Uma sequência que representa os dias abreviados da semana no local atual, onde Mon é o dia número 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

  Apelidos para os dias da semana, onde `MONDAY` é `0` e `SUNDAY` é `6`.

  Adicionado na versão 3.12.

class calendar.Day

  Enumeração que define os dias da semana como constantes inteiras. Os membros dessa enumeração são exportados para o escopo do módulo como `MONDAY` até `SUNDAY`.

  Adicionado na versão 3.12.

calendar.month_name

  Uma sequência que representa os meses do ano na localidade atual. Isso segue a convenção normal de janeiro sendo o mês número 1, então tem um comprimento de 13 e `month_name[0]` é a string vazia.

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

calendar.month_abbr

  Uma sequência que representa os meses abreviados do ano na localidade atual. Isso segue a convenção normal de janeiro sendo o mês número 1, então tem um comprimento de 13 e `month_abbr[0]` é a string vazia.

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

  Apelidos para os meses do ano, onde `JANUARY` é `1` e `DECEMBER` é `12`.

  Adicionado na versão 3.12.

class calendar.Month

  Enumeração que define os meses do ano como constantes inteiras. Os membros dessa enumeração são exportados para o escopo do módulo como `JANUARY` até `DECEMBER`.

  Adicionado na versão 3.12.

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

Adicionado 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]
                       [-f FIRST_WEEKDAY] [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.

--first-weekday FIRST_WEEKDAY, -f FIRST_WEEKDAY

  O dia da semana para começar cada semana. Deve ser um número entre 0 (segunda-feira) e 6 (domingo). O padrão é 0.

  Adicionado na versão 3.13.

year

  O ano para exibir o calendário. O padrão é o ano atual.

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.

Alterado na versão 3.14: Por padrão, a data de hoje é destacada em cor e pode ser controlada usando variáveis de ambiente.

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:///`.