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