# `textwrap` --- Text wrapping and filling

Source code: Lib/textwrap.py

Le module `textwrap` fournit quelques fonctions pratiques, comme `TextWrapper`, la classe qui fait tout le travail. Si vous ne faites que formater ou ajuster une ou deux chaînes de texte, les fonctions de commodité devraient être assez bonnes ; sinon, nous vous conseillons d'utiliser une instance de `TextWrapper` pour une meilleure efficacité.

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=' [...]')

  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.

  Optional keyword arguments correspond to the instance attributes of `TextWrapper`, documented below.

  Consultez la méthode `TextWrapper.wrap()` pour plus de détails sur le comportement 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=' [...]')

  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 nommés que `wrap()`.

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

  Réduit et tronque le text donné pour l'adapter à la largeur donnée.

  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...'

  Les arguments nommés optionnels correspondent aux attributs d'instance de `TextWrapper`, documentés ci-dessous. Notez que l'espace blanc est réduit avant que le texte ne soit passé à la fonction `fill()` de `TextWrapper`, donc changer la valeur de `tabsize`, `expand_tabs`, `drop_whitespace`, et `replace_whitespace` est sans effet.

  Ajouté dans la version 3.4.

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.

  Notez que les tabulations et les espaces sont traitées comme des espaces, mais qu'elles ne sont pas égales : les lignes `" hello"` et `"\thello"` sont considérées comme n'ayant pas d'espaces de tête communes.

  Les lignes contenant uniquement des espaces sont ignorées en entrée et réduites à un seul caractère de saut de ligne en sortie.

  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'

  Modifié dans la version 3.14: The `dedent()` function now correctly normalizes blank lines containing only whitespace characters. Previously, the implementation only normalized blank lines containing tabs and spaces.

textwrap.indent(text, prefix, predicate=None)

  Ajoute prefix au début des lignes sélectionnées dans text.

  Les lignes sont séparées en appelant `text.splitlines(True)`.

  Par défaut, prefix est ajouté à toutes les lignes qui ne sont pas constituées uniquement d'espaces (y compris les fins de ligne).

  Par exemple :

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

  L'argument optionnel predicate peut être utilisé pour contrôler quelles lignes sont en retrait. Par exemple, il est facile d'ajouter prefix aux lignes vides et aux lignes blanches seulement :

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

  Ajouté dans la version 3.3.

`wrap()`, `fill()` et `shorten()` travaillent en créant une instance `TextWrapper` et en appelant une méthode unique sur celle-ci. Cette instance n'est pas réutilisée, donc pour les applications qui traitent plusieurs chaînes de texte en utilisant `wrap()` et/ou `fill()`, il peut être plus efficace de créer votre propre objet `TextWrapper`.

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.

class textwrap.TextWrapper(**kwargs)

  Le constructeur `TextWrapper` accepte un certain nombre d'arguments nommés optionnels. Chaque argument nommé correspond à un attribut d'instance, donc par exemple

      wrapper = TextWrapper(initial_indent="* ")

  est identique à

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

  You can reuse the same `TextWrapper` object many times, and you can change any of its options through direct assignment to instance attributes between uses.

  Les attributs d'instance de la classe `TextWrapper` (et les arguments nommés 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

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

  tabsize

    (par défaut : `8`) Si `expand_tabs` est vrai, alors tous les caractères de tabulation dans text sont transformés en zéro ou plus d'espaces, selon la colonne courante et la taille de tabulation donnée.

    Ajouté dans la version 3.3.

  replace_whitespace

    (par défaut : `True`) Si vrai, 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.

  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

    (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 [...]

    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.

  max_lines

    (par défaut : `None`) Si ce n'est pas `None`, alors la sortie contient au maximum max_lines lignes, avec placeholder à la fin de la sortie.

    Ajouté dans la version 3.4.

  placeholder

    (par défaut : `'' [...]'`) Chaîne qui apparaît à la fin du texte de sortie s'il a été tronqué.

    Ajouté dans la version 3.4.

  `TextWrapper` fournit également quelques méthodes publiques, analogues aux fonctions de commodité au niveau du module :

  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é.