"formatter" --- Formateo de salida genérica
*******************************************

Obsoleto desde la versión 3.4: Debido a la falta de uso, el módulo
formateador ha quedado obsoleto.

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

Este módulo admite dos definiciones de interfaz, cada una con
múltiples implementaciones: la interfaz *formateador* y la interfaz
*escritor* que es requerida por la interfaz formateadora.

Los objetos formateadores transforman un flujo abstracto de eventos de
formato en eventos de salida específicos en los objetos del escritor.
Los formateadores gestionan varias estructuras de pila para permitir
cambiar y restaurar varias propiedades de un objeto escritor; los
escritores no necesitan poder manejar cambios relativos ni ningún tipo
de operación de "retroceso". Las propiedades específicas del escritor
que se pueden controlar a través de los objetos del formateador son la
alineación horizontal, la fuente y las sangrías del margen izquierdo.
Se proporciona un mecanismo que también permite proporcionar
configuraciones de estilo arbitrarias y no exclusivas a un escritor.
Las interfaces adicionales facilitan el formateo de eventos que no son
reversibles, como la separación de párrafos.

Los objetos escritores encapsulan las interfaces de los dispositivos.
Se admiten dispositivos abstractos, como formatos de archivo, así como
dispositivos físicos. Todas las implementaciones proporcionadas
funcionan con dispositivos abstractos. La interfaz pone a disposición
mecanismos para establecer las propiedades que administran los objetos
del formateador e insertar datos en la salida.


La interfaz Formateador
=======================

Las interfaces para crear formateadores dependen de la clase de
formateador específica que se instancia. Las interfaces que se
describen a continuación son las interfaces necesarias que todos los
formateadores deben admitir una vez inicializados.

Un elemento de datos se define a nivel de módulo:

formatter.AS_IS

   Valor que se puede usar en la especificación de fuente pasada al
   método "push_font ()" descrito a continuación, o como el nuevo
   valor a cualquier otro método "push_property()". Al presionar el
   valor "AS_IS", se puede llamar al método correspondiente
   "pop_property()" sin tener que rastrear si se cambió la propiedad.

Los siguientes atributos están definidos para los objetos de instancia
del formateador:

formatter.writer

   La instancia de escritor con la que interactúa el formateador.

formatter.end_paragraph(blanklines)

   Cierra todos los párrafos abiertos e inserta al menos *blanklines*
   antes del siguiente párrafo.

formatter.add_line_break()

   Agrega un salto de línea duro si aún no existe uno. Esto no rompe
   el párrafo lógico.

formatter.add_hor_rule(*args, **kw)

   Inserta una regla horizontal en la salida. Se inserta una ruptura
   dura si hay datos en el párrafo actual, pero el párrafo lógico no
   está roto. Los argumentos y palabras clave se pasan al método del
   escritor "send_line_break()".

formatter.add_flowing_data(data)

   Proporciona datos que deben formatearse con espacios en blanco
   contraídos. Los espacios en blanco de llamadas anteriores y
   sucesivas a "add_flowing_data()" también se consideran cuando se
   realiza el colapso de espacios en blanco. Se espera que los datos
   que se pasan a este método estén envueltos en palabras por el
   dispositivo de salida. Tenga en cuenta que el objeto escritor debe
   realizar cualquier ajuste de texto debido a la necesidad de
   depender de la información del dispositivo y la fuente.

formatter.add_literal_data(data)

   Proporciona datos que deben pasarse al escritor sin cambios. Los
   espacios en blanco, incluidos los caracteres de nueva línea y
   tabulación, se consideran legales en el valor de *data*.

formatter.add_label_data(format, counter)

   Inserta una etiqueta que debe colocarse a la izquierda del margen
   izquierdo actual. Esto debe usarse para construir listas numeradas
   o con viñetas. Si el valor de *format* es una cadena, se interpreta
   como una especificación de formato para *counter*, que debe ser un
   número entero. El resultado de este formato se convierte en el
   valor de la etiqueta; si *format* no es una cadena, se utiliza
   directamente como valor de etiqueta. El valor de la etiqueta se
   pasa como el único argumento del método del escritor
   "send_label_data()". La interpretación de valores de etiquetas que
   no son cadenas depende del escritor asociado.

   Las especificaciones de formato son cadenas que, en combinación con
   un valor de contador, se utilizan para calcular valores de
   etiqueta. Cada carácter de la cadena de formato se copia al valor
   de la etiqueta, y algunos caracteres se reconocen para indicar una
   transformación en el valor del contador. Específicamente, el
   carácter "'1'" representa el formateador del valor del contador
   como un número arábigo, los caracteres "'A'" y "'a'" representan
   representaciones alfabéticas del valor del contador en mayúsculas y
   minúsculas , respectivamente, y "'I'" y "'i'" representan el valor
   del contador en números romanos, en mayúsculas y minúsculas. Tenga
   en cuenta que las transformaciones alfabética y romana requieren
   que el valor del contador sea mayor que cero.

formatter.flush_softspace()

   Envía cualquier espacio en blanco pendiente almacenado en búfer de
   una llamada anterior a "add_flowing_data()" al objeto escritor
   asociado. Esto debe llamarse antes de cualquier manipulación
   directa del objeto de escritura.

formatter.push_alignment(align)

   Empuja una nueva configuración de alineación en la pila de
   alineación. Puede ser "AS_IS" si no se desea ningún cambio. Si el
   valor de alineación se cambia con respecto a la configuración
   anterior, se llama al método del escritor "new_alignment()" con el
   valor *align*.

formatter.pop_alignment()

   Restaura la alineación anterior.

formatter.push_font((size, italic, bold, teletype))

   Cambia algunas o todas las propiedades de fuente del objeto de
   escritura. Las propiedades que no se establecen en "AS_IS" se
   establecen en los valores pasados, mientras que otras se mantienen
   en su configuración actual. Se llama al método del escritor
   "new_font()" con la especificación de fuente completamente
   resuelta.

formatter.pop_font()

   Restaura la fuente anterior.

formatter.push_margin(margin)

   Aumenta el número de sangrías del margen izquierdo en uno,
   asociando la etiqueta lógica *margin* con la nueva sangría. El
   nivel de margen inicial es "0". Los valores modificados de la
   etiqueta lógica deben ser valores verdaderos; los valores falsos
   distintos de "AS_IS" no son suficientes para cambiar el margen.

formatter.pop_margin()

   Restaura el margen anterior.

formatter.push_style(*styles)

   Empuja cualquier número de especificaciones de estilo arbitrarias.
   Todos los estilos se insertan en la pila de estilos en orden. Una
   tupla que representa la pila completa, incluidos los valores
   "AS_IS", se pasa al método "new_styles()" del escritor.

formatter.pop_style(n=1)

   Muestra las últimas *n* especificaciones de estilo pasadas a
   "push_style()". Una tupla que representa la pila revisada, que
   incluye los valores "AS_IS", se pasa al método "new_styles()" del
   escritor.

formatter.set_spacing(spacing)

   Establece el estilo de espaciado para el escritor.

formatter.assert_line_data(flag=1)

   Informa al formateador que se han agregado datos al párrafo actual
   fuera de banda. Esto debe usarse cuando el escritor haya sido
   manipulado directamente. El argumento *flag* opcional se puede
   establecer en falso si las manipulaciones del escritor produjeron
   un salto de línea duro al final de la salida.


Implementaciones del formateador
================================

Este módulo proporciona dos implementaciones de objetos formateadores.
La mayoría de las aplicaciones pueden utilizar una de estas clases sin
modificación ni subclases.

class formatter.NullFormatter(writer=None)

   Un formateador que no hace nada. Si se omite *writer*, se crea una
   instancia "NullWriter". Ningún método del escritor es llamado por
   instancias "NullFormatter". Las implementaciones deben heredar de
   esta clase si implementan una interfaz de escritor, pero no
   necesitan heredar ninguna implementación.

class formatter.AbstractFormatter(writer)

   El formateador estándar. Esta implementación ha demostrado una
   amplia aplicabilidad para muchos escritores y puede usarse
   directamente en la mayoría de las circunstancias. Se ha utilizado
   para implementar un navegador World Wide Web con todas las
   funciones.


La interfaz Escritor
====================

Las interfaces para crear escritores dependen de la clase de escritor
específica que se instancia. Las interfaces que se describen a
continuación son las interfaces necesarias que todos los escritores
deben admitir una vez inicializadas. Tenga en cuenta que, si bien la
mayoría de las aplicaciones pueden usar la clase "AbstractFormatter"
como formateador, el escritor generalmente debe ser proporcionado por
la aplicación.

writer.flush()

   Vacía cualquier salida almacenada o eventos de control de
   dispositivos.

writer.new_alignment(align)

   Define el estilo de alineación. El valor *align* puede ser
   cualquier objeto, pero por convención es una cadena o "None", donde
   "None" indica que se debe usar la alineación "preferida" del
   escritor. Los valores de *align* convencionales son *'left'`*,
   "'center'", "'right'", y "'justify'".

writer.new_font(font)

   Establece el estilo de fuente. El valor de *font* será "None", lo
   que indica que se debe usar la fuente predeterminada del
   dispositivo, o una tupla de la forma "(tamaño, cursiva, negrita,
   teletipo)". El tamaño será una cadena que indica el tamaño de
   fuente que se debe utilizar; cadenas específicas y su
   interpretación deben ser definidas por la aplicación. Los valores
   *cursiva*, *negrita* y *teletipo* son valores booleanos que
   especifican cuál de esos atributos de fuente debe usarse.

writer.new_margin(margin, level)

   Establece el nivel de margen en el entero *level* y la etiqueta
   lógica en *margin*. La interpretación de la etiqueta lógica queda a
   discreción del escritor; la única restricción sobre el valor de la
   etiqueta lógica es que no sea un valor falso para valores distintos
   de cero de *level*.

writer.new_spacing(spacing)

   Establece el estilo de espaciado en *spacing*.

writer.new_styles(styles)

   Establece estilos adicionales. El valor de *styles* es una tupla de
   valores arbitrarios; el valor "AS_IS" debe ignorarse. La tupla
   *styles* se puede interpretar como un conjunto o como una pila
   dependiendo de los requisitos de la aplicación y la implementación
   del escritor.

writer.send_line_break()

   Rompe la línea actual.

writer.send_paragraph(blankline)

   Produce una separación de párrafos de al menos *blankline* líneas
   en blanco, o su equivalente. El valor de *blankline* será un número
   entero. Tenga en cuenta que la implementación recibirá una llamada
   a "send_line_break()" antes de esta llamada si se necesita un salto
   de línea; este método no debe incluir terminar la última línea del
   párrafo. Solo es responsable del espacio vertical entre párrafos.

writer.send_hor_rule(*args, **kw)

   Muestra una regla horizontal en el dispositivo de salida. Los
   argumentos de este método son completamente específicos de la
   aplicación y del escritor, y deben interpretarse con cuidado. La
   implementación del método puede asumir que ya se ha emitido un
   salto de línea a través de "send_line_break()".

writer.send_flowing_data(data)

   Datos de caracteres de salida que se pueden ajustar en palabras y
   volver a fluir según sea necesario. Dentro de cualquier secuencia
   de llamadas a este método, el escritor puede asumir que se han
   contraído tramos de múltiples caracteres de espacio en blanco a
   caracteres de un solo espacio.

writer.send_literal_data(data)

   Salida de datos de caracteres que ya se formatearon para su
   visualización. En general, esto debe interpretarse en el sentido de
   que los saltos de línea indicados por caracteres de nueva línea
   deben conservarse y no deben introducirse nuevos saltos de línea.
   Los datos pueden contener caracteres de tabulación y nueva línea
   incrustados, a diferencia de los datos proporcionados en la
   interfaz "send_formatted_data()".

writer.send_label_data(data)

   Establece *data* a la izquierda del margen izquierdo actual, si es
   posible. El valor de *data* no está restringido; el tratamiento de
   los valores que no son cadenas depende completamente de la
   aplicación y del escritor. Este método solo se llamará al comienzo
   de una línea.


Implementaciones del escritor
=============================

Este módulo proporciona tres implementaciones de la interfaz de
objetos del escritor como ejemplos. La mayoría de las aplicaciones
necesitarán derivar nuevas clases de escritor de la clase
"NullWriter".

class formatter.NullWriter

   Un escritor que solo proporciona la definición de la interfaz; no
   se toman acciones sobre ningún método. Esta debería ser la clase
   base para todos los escritores que no necesitan heredar ningún
   método de implementación.

class formatter.AbstractWriter

   Un escritor que se puede utilizar para depurar formateadores, pero
   no mucho más. Cada método simplemente se anuncia a sí mismo
   imprimiendo su nombre y argumentos en la salida estándar.

class formatter.DumbWriter(file=None, maxcol=72)

   Clase de escritor simple que escribe la salida en el *file object*
   pasado como *file* o, si se omite *file*, en la salida estándar. La
   salida simplemente se ajusta en palabras al número de columnas
   especificado por *maxcol*. Esta clase es adecuada para reajustar
   una secuencia de párrafos.
