"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, **kwargs)

   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 opcionales de las palabras clave corresponden a los
   atributos de la instancia de "TextWrapper", documentados a
   continuación.  *width* por defecto es "70".

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

textwrap.fill(text, width=70, **kwargs)

   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, **kwargs)

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

   Primero el espacio blanco en *text* se colapsa (todos los espacios
   blancos son reemplazados por espacios sencillos).  Si el resultado
   cabe en el *width*, se retorna. En caso contrario, se eliminan
   suficientes palabras del final para que las palabras restantes más
   el "placeholder" encajen dentro de "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") Si es verdadero, entonces todos los caracteres
      de tabulación en *text* serán expandidos a espacios usando el
      método "expandtabs()" de *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") If true, after tab expansion but before
      wrapping, the "wrap()" method will replace each whitespace
      character with a single space.  The whitespace characters
      replaced are as follows: tab, newline, vertical tab, formfeed,
      and 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") Si es verdadero, "TextWrapper" intenta
      detectar los finales de las frases y asegurarse de que las
      frases estén siempre separadas por dos espacios exactos.  Esto
      es generalmente deseado para el texto en una fuente
      monoespaciada. Sin embargo, el algoritmo de detección de
      oraciones es imperfecto: asume que el final de una oración
      consiste en una letra minúscula seguida de una de "'.'", "'!'",
      o "'?'", posiblemente seguida de una de "'"'" o ""'"", seguida
      de un espacio.  Un problema de este algoritmo es que no puede
      detectar la diferencia entre "Dr." en

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

      y "Spot." en:

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

      "fix_sentence_endings" es falso por defecto.

      Since the sentence detection algorithm relies on
      "string.lowercase" for the definition of "lowercase letter", and
      a convention of using two spaces after a period to separate
      sentences on the same line, it is specific to English-language
      texts.

   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

      (default: "True") If true, wrapping will occur preferably on
      whitespaces and right after hyphens in compound words, as it is
      customary in English. If false, only whitespaces will be
      considered as potentially good places for line breaks, but you
      need to set "break_long_words" to false if you want truly
      insecable words.  Default behaviour in previous versions was to
      always allow breaking hyphenated words.

   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.
