"calendar" --- Funciones generales relacionadas con el calendario
*****************************************************************

**Código fuente:** Lib/calendar.py

======================================================================

Este módulo te permite generar calendarios como el programa Unix
**cal**, y proporciona funciones útiles adicionales relacionadas con
el calendario. Por defecto, estos calendarios tienen el lunes como el
primer día de la semana, y el domingo como el último (la convención
europea). Use "setfirstweekday()" para establecer el primer día de la
semana en domingo (6) o en cualquier otro día de la semana. Los
parámetros que especifican fechas se indican como enteros. Para la
funcionalidad relacionada, consulta también los módulos "datetime" y
"time".

Las funciones y clases definidas en este módulo utilizan un calendario
idealizado, el calendario gregoriano actual extendido indefinidamente
en ambas direcciones. Esto coincide con la definición del calendario
"Gregoriano proléptico" en el libro "Calendrical Calculations" de
Dershowitz y Reingold, donde es el calendario base para todos los
cálculos. Los años cero y negativos se interpretan según lo prescrito
por la norma ISO 8601. El año 0 es 1 A. C., el año -1 es 2 a. C., y
así sucesivamente.

class calendar.Calendar(firstweekday=0)

   Crea un objeto "Calendar". *firstweekday* es un entero que
   especifica el primer día de la semana. "MONDAY" es "0" (por
   defecto), "SUNDAY" es "6".

   Un objeto "Calendar" proporciona varios métodos que se pueden
   utilizar para preparar los datos del calendario para dar formato.
   Esta clase no hace ningún formato en sí. Este es el trabajo de las
   subclases.

   Las instancias de "Calendar" tienen los siguientes métodos:

   iterweekdays()

      Retorna un iterador para los números del día de la semana que se
      usará durante una semana. El primer valor del iterador será el
      mismo que el valor de la propiedad "firstweekday".

   itermonthdates(year, month)

      Retorna un iterador para el mes *month* (1--12) en el año
      *year*. Este iterador retornará todos los días (como objetos
      "datetime.date") para el mes y todos los días antes del inicio
      del mes o después del final del mes que se requieren para
      obtener una semana completa.

   itermonthdays(year, month)

      Retorna un iterador para el mes *month* en el año *year* similar
      a "itermonthdates()", pero no restringido por el intervalo
      "datetime.date". Los días retornados serán simplemente el día de
      los números del mes. Para los días fuera del mes especificado,
      el número de día es "0".

   itermonthdays2(year, month)

      Retorna un iterador para el mes *month* del año *year* similar a
      "itermonthdates()", pero no restringido por el rango
      "datetime.date". Los días retornados serán tuplas que consisten
      en un número de día del mes y un número de día de la semana.

   itermonthdays3(year, month)

      Retorna un iterador para el mes *month* del año *year* similar a
      "itermonthdates()", pero no restringido por el rango
      "datetime.date". Los días retornados serán tuplas que consisten
      en un año, un mes y un día del mes.

      Nuevo en la versión 3.7.

   itermonthdays4(year, month)

      Retorna un iterador para el mes *month* del año *year* similar a
      "itermonthdates()", pero no restringido por el rango
      "datetime.date". Los días retornados serán tuplas que consisten
      en un año, un mes, un día del mes y un día de la semana.

      Nuevo en la versión 3.7.

   monthdatescalendar(year, month)

      Retorna una lista de las semanas del mes *month* del año *year*
      como semanas completas. Las semanas son listas de siete objetos
      "datetime.date".

   monthdays2calendar(year, month)

      Retorna una lista de las semanas del mes *month* del año *year*
      como semanas completas. Las semanas son listas de siete tuplas
      de números de días y números de días de la semana.

   monthdayscalendar(year, month)

      Retorna una lista de las semanas del mes *month* del año *year*
      como semanas completas. Las semanas son listas de números de
      siete días.

   yeardatescalendar(year, width=3)

      Retorna los datos del año especificado listos para ser
      formateados. El valor de retorno es una lista de filas de mes.
      Cada fila de mes contiene hasta *width* meses (por defecto hasta
      3). Cada mes contiene entre 4 y 6 semanas y cada semana contiene
      1--7 días. Los días son objetos "datetime.date".

   yeardays2calendar(year, width=3)

      Retorna los datos del año especificado listos para ser
      formateados (similar a "yeardatescalendar()"). Las entradas en
      las listas de la semana son tuplas de números de días y números
      de días de la semana. Los números de los días fuera de este mes
      son cero.

   yeardayscalendar(year, width=3)

      Retorna los datos del año especificado listos para ser
      formateados (similar a "yeardatescalendar()"). Las entradas en
      las listas de la semana son números de día. Los números de día
      fuera de este mes son cero.

class calendar.TextCalendar(firstweekday=0)

   Esta clase puede ser usada para generar calendarios de texto
   simple.

   Las instancias de "TextCalendar" tienen los siguientes métodos:

   formatmonth(theyear, themonth, w=0, l=0)

      Retorna el calendario de un mes en una cadena de varias líneas.
      Si se proporciona *w*, especifica el ancho de las columnas de
      fecha, que están centradas. Si se proporciona *l*, especifica el
      número de líneas que se utilizarán cada semana. Depende del
      primer día de la semana como se especifica en el constructor o
      se establece por el método "setfirstweekday()".

   prmonth(theyear, themonth, w=0, l=0)

      Imprime el calendario de un mes como lo retorna "formatmonth()".

   formatyear(theyear, w=2, l=1, c=6, m=3)

      Retorna un calendario de *m* columnas para todo un año como una
      cadena de varias líneas. Los parámetros opcionales *w*, *l* y
      *c* son para el ancho de la columna de la fecha, las líneas por
      semana y el número de espacios entre las columnas del mes,
      respectivamente. Depende del primer día de la semana como se
      especifica en el constructor o se establece por el método
      "setfirstweekday()". El primer año para el que se puede generar
      un calendario depende de la plataforma.

   pryear(theyear, w=2, l=1, c=6, m=3)

      Imprime el calendario de un año entero como lo retorna
      "formatyear()".

class calendar.HTMLCalendar(firstweekday=0)

   Esta clase puede utilizarse para generar calendarios HTML.

   Las instancias de "HTMLCalendar" tienen los siguientes métodos:

   formatmonth(theyear, themonth, withyear=True)

      Retorna el calendario de un mes como una tabla HTML. Si
      *withyear* es verdadero, el año será incluido en el encabezado,
      de lo contrario sólo se usará el nombre del mes.

   formatyear(theyear, width=3)

      Retorna el calendario de un año como una tabla HTML. *width*
      (por defecto a 3) especifica el número de meses por fila.

   formatyearpage(theyear, width=3, css='calendar.css', encoding=None)

      Retorna el calendario de un año como una página HTML completa.
      *width* (por defecto a 3) especifica el número de meses por
      fila. *css* es el nombre de la hoja de estilo en cascada que se
      debe usar. "None" puede ser pasada si no se debe usar una hoja
      de estilo. *encoding* especifica la codificación a ser usada
      para la salida (por defecto a la codificación por defecto del
      sistema).

   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" tiene los siguientes atributos que puedes
   sobrescribir para personalizar las clases CSS utilizadas por el
   calendario:

   cssclasses

      Una lista de clases CSS utilizadas para cada día de la semana.
      La lista de clases predeterminada es:

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

      se pueden añadir más estilos para cada día:

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

      Ten en cuenta que la longitud de esta lista debe ser de siete
      elementos.

   cssclass_noday

      La clase CSS para un día de la semana que ocurre en el mes
      anterior o siguiente.

      Nuevo en la versión 3.7.

   cssclasses_weekday_head

      Una lista de clases CSS utilizadas para los nombres de los días
      de la semana en la fila del encabezado. El valor por defecto es
      el mismo que "cssclasses".

      Nuevo en la versión 3.7.

   cssclass_month_head

      La clase de CSS del mes (usada por "formatmonthname()"). El
      valor por defecto es ""month"".

      Nuevo en la versión 3.7.

   cssclass_month

      La clase de CSS para la tabla de todo el mes (usada por
      "formatmonth()"). El valor por defecto es ""month"".

      Nuevo en la versión 3.7.

   cssclass_year

      La clase de CSS para la tabla de tablas de todo el año (usada
      por "formatyear()"). El valor por defecto es ""year"".

      Nuevo en la versión 3.7.

   cssclass_year_head

      La clase de CSS para el encabezado de la tabla para todo el año
      (usado por "formatyear()"). El valor por defecto es ""year"".

      Nuevo en la versión 3.7.

   Nótese que aunque la denominación de los atributos de clase
   descritos anteriormente es singular (por ejemplo, "cssclass_month"
   "cssclass_noday"), uno puede reemplazar la clase CSS única con una
   lista de clases CSS separadas por espacios, por ejemplo:

      "text-bold text-red"

   Aquí hay un ejemplo de cómo "HTMLCalendar" puede 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 subclase de "TextCalendar" se le puede pasar un nombre de
   configuración regional en el constructor y retornará los nombres de
   los meses y días de la semana en la configuración regional
   especificada.

class calendar.LocaleHTMLCalendar(firstweekday=0, locale=None)

   Esta subclase de "HTMLCalendar" se le puede pasar un nombre de
   configuración regional en el constructor y retornará los nombres de
   los meses y días de la semana en la configuración regional
   especificada.

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 los calendarios de texto simples este módulo proporciona las
siguientes funciones.

calendar.setfirstweekday(weekday)

   Establece el día de la semana (el "0" es el lunes, el "6" es el
   domingo) para empezar cada semana. Los valores "MONDAY", "TUESDAY",
   "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", y "SUNDAY" se
   proporcionan por conveniencia. Por ejemplo, para fijar el primer
   día de la semana en domingo:

      import calendar
      calendar.setfirstweekday(calendar.SUNDAY)

calendar.firstweekday()

   Retorna la configuración actual para el día de la semana para
   empezar cada semana.

calendar.isleap(year)

   Retorna "True" si *year* es un año bisiesto, si no "False".

calendar.leapdays(y1, y2)

   Retorna el número de años bisiestos en el rango de *y1* a *y2*
   (exclusivo), donde *y1* y *y2* son años.

   Esta función opera para rangos que abarcan un cambio de siglo.

calendar.weekday(year, month, day)

   Retorna el día de la semana ("0" es lunes) para *year*
   ("1970"--...), *month* ("1"--"12"), *day* ("1"--"31").

calendar.weekheader(n)

   Retorna un encabezado con nombres abreviados de los días de la
   semana. *n* especifica el ancho en caracteres de un día de la
   semana.

calendar.monthrange(year, month)

   Retorna el día de la semana del primer día del mes y el número de
   días del mes, para el *year* y *month* especificados.

calendar.monthcalendar(year, month)

   Retorna una matriz que representa el calendario de un mes. Cada
   fila representa una semana; los días fuera del mes se representan
   con ceros. Cada semana comienza con el lunes a menos que lo
   establezca "setfirstweekday()".

calendar.prmonth(theyear, themonth, w=0, l=0)

   Imprime el calendario de un mes según lo retorna "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 el calendario de todo un año como lo retorna "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)

   Una función no relacionada pero útil que toma una tupla de tiempo
   como la retornada por la función "gmtime()" en el módulo "time", y
   retorna el valor correspondiente a la marca de tiempo (*timestamp*)
   Unix, asumiendo una época de 1970, y la codificación POSIX. De
   hecho, "time.gmtime()" y "timegm()" son el inverso de cada uno de
   ellos.

El módulo "calendar" exporta los siguientes atributos de datos:

calendar.day_name

   Un arreglo que representa los días de la semana en la configuración
   regional actual.

calendar.day_abbr

   Un vector que representa los días abreviados de la semana en la
   configuración regional actual.

calendar.month_name

   Un vector que representa los meses del año en la configuración
   regional actual. Esto sigue la convención normal de que enero es el
   mes número 1, por lo que tiene una longitud de 13 y "month_name[0]"
   es la cadena vacía.

calendar.month_abbr

   Una matriz que representa los meses abreviados del año en la
   configuración regional actual. Esto sigue la convención normal de
   que enero es el mes número 1, por lo que tiene una longitud de 13 y
   "month_abbr[0]" es la cadena vacía.

calendar.MONDAY
calendar.TUESDAY
calendar.WEDNESDAY
calendar.THURSDAY
calendar.FRIDAY
calendar.SATURDAY
calendar.SUNDAY

   Aliases para nombres de los días, donde "MONDAY" es "0" y "SUNDAY"
   es "6".

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 también:

  Módulo "datetime"
     Interfaz orientada a objetos para fechas y horas con una
     funcionalidad similar a la del módulo "time".

  Módulo "time"
     Funciones de bajo nivel relacionadas con el tiempo.


Command-Line Usage
==================

Nuevo en la versión 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]
                      [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

The following options are accepted:

--help, -h

   Show the help message and exit.

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

year

   The year to print the calendar for. Must be a number between 1 and
   9999. 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.
