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

   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:

   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)

      Return a year's calendar as a complete HTML page. *width*
      (defaulting to 3) specifies the number of months per row. *css*
      is the name for the cascading style sheet to be used. "None" can
      be passed if no style sheet should be used. *encoding* specifies
      the encoding to be used for the output (defaulting to the system
      default encoding).

   formatmonthname(theyear, themonth, withyear=True)

      Return a month name as an HTML table row. If *withyear* is true
      the year will be included in the row, otherwise just the month
      name will be used.

   "HTMLCalendar" has the following attributes you can override to
   customize the CSS classes used by the calendar:

   cssclasses

      A list of CSS classes used for each weekday. The default class
      list is:

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

      more styles can be added for each day:

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

      Note that the length of this list must be seven items.

   cssclass_noday

      The CSS class for a weekday occurring in the previous or coming
      month.

      Adicionado na versão 3.7.

   cssclasses_weekday_head

      A list of CSS classes used for weekday names in the header row.
      The default is the same as "cssclasses".

      Adicionado na versão 3.7.

   cssclass_month_head

      The month's head CSS class (used by "formatmonthname()"). The
      default value is ""month"".

      Adicionado na versão 3.7.

   cssclass_month

      The CSS class for the whole month's table (used by
      "formatmonth()"). The default value is ""month"".

      Adicionado na versão 3.7.

   cssclass_year

      The CSS class for the whole year's table of tables (used by
      "formatyear()"). The default value is ""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]
                      [-f FIRST_WEEKDAY] [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.

--first-weekday FIRST_WEEKDAY, -f FIRST_WEEKDAY

   The weekday to start each week. Must be a number between 0 (Monday)
   and 6 (Sunday). Defaults to 0.

   Adicionado na versão 3.13.

year

   The year to print the calendar for. 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.
