textwrap — Envoltura y relleno de texto

Source code: Lib/textwrap.py

El módulo textwrap proporciona algunas funciones de conveniencia, así como TextWrapper, la clase que hace todo el trabajo. Si sólo estás envolviendo o rellenando una o dos cadenas de texto, las funciones de conveniencia deberían ser lo suficientemente buenas; de lo contrario, deberías usar una instancia de TextWrapper para mayor eficiencia.

textwrap.wrap(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Envuelve el párrafo individual en text (una cadena) para que cada línea tenga como máximo width de caracteres de largo. Retorna una lista de líneas de salida, sin las nuevas líneas finales.

Los argumentos de palabras clave opcionales corresponden a los atributos de instancia de TextWrapper, que se documentan a continuación.

Ver el método TextWrapper.wrap() para más detalles sobre el comportamiento de wrap().

textwrap.fill(text, width=70, *, initial_indent='', subsequent_indent='', expand_tabs=True, replace_whitespace=True, fix_sentence_endings=False, break_long_words=True, drop_whitespace=True, break_on_hyphens=True, tabsize=8, max_lines=None, placeholder=' [...]')

Envuelve el único párrafo en text, y retorna una sola cadena que contiene el párrafo envuelto. fill() es la abreviatura de

"\n".join(wrap(text, ...))

En particular, fill() acepta exactamente los mismos argumentos de palabras clave que wrap().

textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')

Colapsa y trunca el text dado para que encaje en el width dado.

First the whitespace in text is collapsed (all whitespace is replaced by single spaces). If the result fits in the width, it is returned. Otherwise, enough words are dropped from the end so that the remaining words plus the placeholder fit within width:

>>> textwrap.shorten("Hello  world!", width=12)
'Hello world!'
>>> textwrap.shorten("Hello  world!", width=11)
'Hello [...]'
>>> textwrap.shorten("Hello world", width=10, placeholder="...")
'Hello...'

Los argumentos opcionales de las palabras clave corresponden a los atributos de la instancia de TextWrapper, documentados a continuación. Observe que el espacio en blanco se colapsa antes de pasar el texto a la función TextWrapper fill(), por lo que cambiar el valor de tabsize, expand_tabs, drop_whitespace, y replace_whitespace no tendrá ningún efecto.

Nuevo en la versión 3.4.

textwrap.dedent(text)

Elimina cualquier espacio en blanco común de cada línea de text.

Esto puede utilizarse para hacer que las cadenas con comillas triples se alineen con el borde izquierdo de la pantalla, mientras que se siguen presentando en el código fuente en forma indentada.

Nótese que los tabuladores y los espacios se tratan como espacios en blanco, pero no son iguales: las líneas "  hello" y "\thello" se consideran que no tienen un espacio en blanco común.

Las líneas que sólo contienen espacios en blanco se ignoran en la entrada y se normalizan a un solo carácter de nueva línea en la salida.

Por ejemplo:

def test():
    # end first line with \ to avoid the empty line!
    s = '''\
    hello
      world
    '''
    print(repr(s))          # prints '    hello\n      world\n    '
    print(repr(dedent(s)))  # prints 'hello\n  world\n'
textwrap.indent(text, prefix, predicate=None)

Añade prefix al principio de las líneas seleccionadas en text.

Las líneas se separan llamando a text.splitlines(True).

Por defecto, se añade prefix a todas las líneas que no consisten únicamente en espacios en blanco (incluyendo cualquier terminación de línea).

Por ejemplo:

>>> s = 'hello\n\n \nworld'
>>> indent(s, '  ')
'  hello\n\n \n  world'

El argumento opcional predicate puede ser usado para controlar qué líneas están indentadas. Por ejemplo, es fácil añadir prefix incluso a las líneas vacías y de espacio en blanco:

>>> print(indent(s, '+ ', lambda line: True))
+ hello
+
+
+ world

Nuevo en la versión 3.3.

wrap(), fill() y shorten() funcionan creando una instancia TextWrapper y llamando a un solo método en ella. Esa instancia no se reutiliza, por lo que para las aplicaciones que procesan muchas cadenas de texto usando wrap() y/o fill(), puede ser más eficiente crear su propio objeto TextWrapper.

El texto se envuelve preferentemente en espacios en blanco y justo después de los guiones en palabras con guión; sólo entonces se romperán las palabras largas si es necesario, a menos que TextWrapper.break_long_words sea falso.

class textwrap.TextWrapper(**kwargs)

El constructor TextWrapper acepta un número de argumentos de palabras clave opcionales. Cada argumento de palabra clave corresponde a un atributo de la instancia, por ejemplo

wrapper = TextWrapper(initial_indent="* ")

es lo mismo que

wrapper = TextWrapper()
wrapper.initial_indent = "* "

Puedes reutilizar el mismo objeto TextWrapper muchas veces, y puedes cambiar cualquiera de sus opciones a través de la asignación directa de atributos de instancia entre usos.

Los atributos de la instancia TextWrapper (y los argumentos de las palabras clave para el constructor) son los siguientes:

width

(default: 70) La longitud máxima de las líneas envueltas. Mientras no haya palabras individuales en el texto de entrada más largas que width, TextWrapper garantiza que ninguna línea de salida será más larga que los caracteres width.

expand_tabs

(default: True) If true, then all tab characters in text will be expanded to spaces using the expandtabs() method of text.

tabsize

(default: 8) Si expand_tabs es verdadero, entonces todos los caracteres de tabulación en text se expandirán a cero o más espacios, dependiendo de la columna actual y el tamaño de tabulación dado.

Nuevo en la versión 3.3.

replace_whitespace

(default: True) Si es verdadero, después de la expansión por tabulador pero antes de envolver, el método wrap() reemplazará cada carácter de espacio en blanco con un espacio sencillo. Los caracteres de los espacios en blanco reemplazados son los siguientes: tab, nueva línea, tab vertical, formfeed y carriage return ('\t\n\v\f\r').

Nota

Si expand_tabs es falso y replace_whitespace es verdadero, cada carácter del tabulador será reemplazado por un solo espacio, que no es lo mismo que la expansión del tabulador.

Nota

Si replace_whitespace es falso, las nuevas líneas pueden aparecer en medio de una línea y causar una salida extraña. Por esta razón, el texto debe ser dividido en párrafos (usando str.splitlines() o similar) que se envuelven por separado.

drop_whitespace

(default: True) Si es verdadero, se eliminan los espacios en blanco al principio y al final de cada línea (después de la envoltura pero antes del indentado). Sin embargo, el espacio en blanco al principio del párrafo no se elimina si lo sigue un espacio en blanco. Si el espacio blanco que se deja caer ocupa una línea entera, se deja caer toda la línea.

initial_indent

(default: '') Cadena que será preparada para la primera línea de salida envuelta. Cuenta hacia la longitud de la primera línea. La cadena vacía no está indentada.

subsequent_indent

(default: '') Cadena que se preparará para todas las líneas de salida envueltas excepto la primera. Cuenta hacia la longitud de cada línea excepto la primera.

fix_sentence_endings

(default: False) If true, TextWrapper attempts to detect sentence endings and ensure that sentences are always separated by exactly two spaces. This is generally desired for text in a monospaced font. However, the sentence detection algorithm is imperfect: it assumes that a sentence ending consists of a lowercase letter followed by one of '.', '!', or '?', possibly followed by one of '"' or "'", followed by a space. One problem with this algorithm is that it is unable to detect the difference between «Dr.» in

[...] Dr. Frankenstein's monster [...]

y «Spot.» en:

[...] See Spot. See Spot run [...]

fix_sentence_endings es falso por defecto.

Dado que el algoritmo de detección de oraciones se basa en string.lowercase para la definición de «letra en minúscula», y en la convención de utilizar dos espacios después de un punto para separar las oraciones en la misma línea, es específico para los textos en inglés.

break_long_words

(default: True) Si es verdadero, entonces las palabras más largas que width se romperán para asegurar que ninguna línea sea más larga que width. Si es falso, las palabras largas no se romperán, y algunas líneas pueden ser más largas que width. (Las palabras largas se pondrán en una línea por sí mismas, para minimizar la cantidad en que se excede width).

break_on_hyphens

(predeterminado: True) Si es verdadero, el ajuste se producirá preferiblemente en espacios en blanco y justo después de los guiones en palabras compuestas, como es habitual en inglés. Si es falso, solo los espacios en blanco se considerarán lugares potencialmente buenos para los saltos de línea, pero debe establecer break_long_words en falso si desea palabras verdaderamente insecables. El comportamiento predeterminado en versiones anteriores era permitir siempre romper palabras con guiones.

max_lines

(default: None) Si es None, entonces la salida contendrá como máximo max_lines, con un placeholder que aparecerá al final de la salida.

Nuevo en la versión 3.4.

placeholder

(default: ' [...]') Cadena que aparecerá al final del texto de salida si ha sido truncado.

Nuevo en la versión 3.4.

TextWrapper también proporciona algunos métodos públicos, análogos a las funciones de conveniencia a nivel de módulo:

wrap(text)

Envuelve el párrafo individual en text (una cadena) para que cada línea tenga como máximo width caracteres de largo. Todas las opciones de envoltura se toman de los atributos de la instancia TextWrapper. Retorna una lista de líneas de salida, sin las nuevas líneas finales. Si la salida envuelta no tiene contenido, la lista retornada estará vacía.

fill(text)

Envuelve el único párrafo en text, y retorna una única cadena que contiene el párrafo envuelto.