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.