7.7. "textwrap" — Encapsulation et remplissage de texte
*******************************************************

Nouveau dans la version 2.3.

**Source code:** Lib/textwrap.py

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

The "textwrap" module provides two convenience functions, "wrap()" and
"fill()", as well as "TextWrapper", the class that does all the work,
and a utility function  "dedent()".  If you’re just wrapping or
filling one or two  text strings, the convenience functions should be
good enough; otherwise,  you should use an instance of "TextWrapper"
for efficiency.

textwrap.wrap(text[, width[, ...]])

   Reformate le paragraphe simple dans *text* (une chaîne de
   caractères) de sorte que chaque ligne ait au maximum *largeur*
   caractères.  Renvoie une liste de lignes de sortie, sans ligne vide
   ou caractère de fin de ligne à la fin.

   Les arguments par mot-clé optionnels correspondent aux attributs
   d’instance de "TextWrapper", documentés ci-dessous.  *width* vaut
   "70" par défaut.

   Consultez la méthode "TextWrapper.wrap()" pour plus de détails sur
   le comportement de "wrap()".

textwrap.fill(text[, width[, ...]])

   Formate le paragraphe unique dans *text* et renvoie une seule
   chaîne dont le contenu est le paragraphe formaté. "fill()" est un
   raccourci pour : :

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

   En particulier, "fill()" accepte exactement les mêmes arguments par
   mot-clé que "wrap()".

Both "wrap()" and "fill()" work by creating a "TextWrapper" instance
and calling a single method on it.  That instance is not reused, so
for applications that wrap/fill many text strings, it will be more
efficient for you to create your own "TextWrapper" object.

Le formatage du texte s’effectue en priorité sur les espaces puis
juste après les traits d’union dans des mots séparés par des traits
d’union ; ce n’est qu’alors que les mots longs seront cassés si
nécessaire, à moins que "TextWrapper.break_long_words" soit défini sur
*False*.

An additional utility function, "dedent()", is provided to remove
indentation from strings that have unwanted whitespace to the left of
the text.

textwrap.dedent(text)

   Supprime toutes les espaces en de tête de chaque ligne dans *text*.

   Ceci peut être utilisé pour aligner les chaînes à trois guillemets
   avec le bord gauche de l’affichage, tout en les présentant sous
   forme indentée dans le code source.

   Note that tabs and spaces are both treated as whitespace, but they
   are not equal: the lines ""  hello"" and ""\thello"" are considered
   to have no common leading whitespace.  (This behaviour is new in
   Python 2.5; older versions of this module incorrectly expanded tabs
   before searching for common leading whitespace.)

   Lines containing only whitespace are ignored in the input and
   normalized to a single newline character in the output.

   Par exemple :

      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'

class textwrap.TextWrapper(...)

   The "TextWrapper" constructor accepts a number of optional keyword
   arguments.  Each argument corresponds to one instance attribute, so
   for example

      wrapper = TextWrapper(initial_indent="* ")

   est identique à

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

   Vous pouvez réutiliser le même objet "TextWrapper" plusieurs fois
   et vous pouvez changer n’importe laquelle de ses options par
   assignation directe aux attributs d’instance entre les
   utilisations.

   Les attributs d’instance de la classe "TextWrapper" (et les
   arguments par mot-clé au constructeur) sont les suivants :

   width

      (par défaut : "70`") Longueur maximale des lignes reformatées.
      Tant qu’il n’y a pas de mots individuels dans le texte d’entrée
      plus longs que "width", "TextWrapper" garantit qu’aucune ligne
      de sortie n’est plus longue que "width" caractères.

   expand_tabs

      (par défaut : "True") Si *true*, alors tous les caractères de
      tabulation dans *text* sont transformés en espaces en utilisant
      la méthode "expandtabs()" de *text*.

   replace_whitespace

      (par défaut : "True") Si *true*, après l’expansion des
      tabulations mais avant le formatage, la méthode "wrap()"
      remplace chaque *blanc* par une espace unique.  Les *blancs*
      remplacés sont les suivants : tabulation, nouvelle ligne,
      tabulation verticale, saut de page et retour chariot
      ("'\t\n\v\f\r'").

      Note: Si "expand_tabs" est *False* et "replace_whitespace" est
        vrai, chaque caractère de tabulation est remplacé par une
        espace unique, ce qui *n’est pas* la même chose que
        l’extension des tabulations.

      Note: Si "replace_whitespace" est faux, de nouvelles lignes
        peuvent apparaître au milieu d’une ligne et provoquer une
        sortie étrange. Pour cette raison, le texte doit être divisé
        en paragraphes (en utilisant "str.splitlines()" ou similaire)
        qui sont formatés séparément.

   drop_whitespace

      (par défaut : "True") Si *True*, l’espace au début et à la fin
      de chaque ligne (après le formatage mais avant l’indentation)
      est supprimée. L’espace au début du paragraphe n’est cependant
      pas supprimée si elle n’est pas suivie par une espace.  Si les
      espaces en cours de suppression occupent une ligne entière, la
      ligne entière est supprimée.

      Nouveau dans la version 2.6: Whitespace was always dropped in
      earlier versions.

   initial_indent

      (par défaut : "`''`") Chaîne qui est ajoutée à la première ligne
      de la sortie formatée. Elle compte pour le calcul de la longueur
      de la première ligne.  La chaîne vide n’est pas indentée.

   subsequent_indent

      (par défaut : "`''`") Chaîne qui préfixe toutes les lignes de la
      sortie formatée sauf la première. Elle compte pour le calcul de
      la longueur de chaque ligne à l’exception de la première.

   fix_sentence_endings

      (par défaut : "Faux") Si *true*, "TextWrapper" tente de détecter
      les fins de phrases et de s’assurer que les phrases sont
      toujours séparées par exactement deux espaces.  Ceci est
      généralement souhaité pour un texte en police à chasse fixe.
      Cependant, l’algorithme de détection de phrase est imparfait :
      il suppose qu’une fin de phrase consiste en une lettre minuscule
      suivie de l’une des lettres suivantes : "'.'", "'!'", ou "'?'",
      éventuellement suivie d’une des lettres "'"'" ou ""'"", suivie
      par une espace.  Un problème avec cet algorithme est qu’il est
      incapable de détecter la différence entre « Dr » dans : :

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

      et « Spot. » dans

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

      "fix_sentence_endings" est *False* par défaut.

      Étant donné que l’algorithme de détection de phrases repose sur
      "string.lowercase" pour la définition de « lettres minuscules »
      et sur une convention consistant à utiliser deux espaces après
      un point pour séparer les phrases sur la même ligne, ceci est
      spécifique aux textes de langue anglaise.

   break_long_words

      (par défaut : "True") Si *True*, alors les mots plus longs que
      "width" sont cassés afin de s’assurer qu’aucune ligne ne soit
      plus longue que "width".  Si c’est *False*, les mots longs ne
      sont pas cassés et certaines lignes peuvent être plus longues
      que "width" (les mots longs seront mis sur une ligne qui leur
      est propre, afin de minimiser le dépassement de "width").

   break_on_hyphens

      (par défaut : "True") Si c’est vrai, le formatage se fait de
      préférence sur les espaces et juste après sur les traits d’union
      des mots composés, comme il est d’usage en anglais. Si *False*,
      seuls les espaces sont considérées comme de bons endroits pour
      les sauts de ligne, mais vous devez définir "break_long_words" à
      *False* si vous voulez des mots vraiment insécables.  Le
      comportement par défaut dans les versions précédentes était de
      toujours permettre de couper les mots avec trait d’union.

      Nouveau dans la version 2.6.

   "TextWrapper" also provides two public methods, analogous to the
   module-level convenience functions:

   wrap(text)

      Formate le paragraphe unique dans *text* (une chaîne de
      caractères) de sorte que chaque ligne ait au maximum "width"
      caractères.  Toutes les options de formatage sont tirées des
      attributs d’instance de l’instance de classe "TextWrapper".
      Renvoie une liste de lignes de sortie, sans nouvelles lignes
      finales. Si la sortie formatée n’a pas de contenu, la liste vide
      est renvoyée.

   fill(text)

      Formate le paragraphe unique de *text* et renvoie une seule
      chaîne contenant le paragraphe formaté.
