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

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.
