textwrap — Ombrytning och fyllning av text

Källkod: Lib/textwrap.py

Modulen textwrap tillhandahåller några bekvämlighetsfunktioner samt TextWrapper, den klass som gör allt arbete. Om du bara omsluter eller fyller en eller två textsträngar bör bekvämlighetsfunktionerna vara tillräckligt bra; annars bör du använda en instans av TextWrapper för effektivitetens skull.

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

Slår in det enskilda stycket i text (en sträng) så att varje rad är högst bredd tecken lång. Returnerar en lista med utdatarader, utan avslutande nya linjer.

Valfria nyckelordsargument motsvarar instansattributen för TextWrapper, som dokumenteras nedan.

Se metoden TextWrapper.wrap() för mer information om hur wrap() fungerar.

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

Omsluter det enskilda stycket i text och returnerar en enskild sträng som innehåller det omslutna stycket. fill() är en förkortning för

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

I synnerhet accepterar fill() exakt samma nyckelordsargument som wrap().

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

Kollapsa och trunkera den givna texten så att den passar in i den givna bredden.

Först kollapsas blankstegen i text (alla blanksteg ersätts med enkla mellanslag). Om resultatet ryms inom bredden returneras det. Annars tas tillräckligt många ord bort från slutet så att de återstående orden plus platshållaren ryms inom bredd:

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

Valfria nyckelordsargument motsvarar instansattributen för TextWrapper, som dokumenteras nedan. Observera att blanksteg kollapsar innan texten skickas till TextWrapper fill()-funktionen, så att ändra värdet på tabsize, expand_tabs, drop_whitespace och replace_whitespace kommer inte att ha någon effekt.

Tillagd i version 3.4.

textwrap.dedent(text)

Ta bort alla vanliga inledande blanksteg från varje rad i text.

Detta kan användas för att få trippelciterade strängar att ligga i linje med vänsterkanten på skärmen, samtidigt som de fortfarande presenteras i källkoden i indragen form.

Observera att tabbar och mellanslag båda behandlas som blanksteg, men de är inte lika: raderna " hello" och "\thello" anses inte ha något gemensamt ledande blanksteg.

Rader som bara innehåller blanksteg ignoreras i inmatningen och normaliseras till ett enda nytt radtecken i utmatningen.

Till exempel:

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)

Lägg till prefix i början av markerade rader i text.

Rader separeras genom att anropa text.splitlines(True).

Som standard läggs prefix till på alla rader som inte enbart består av blanksteg (inklusive eventuella radavslut).

Till exempel:

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

Det valfria argumentet predicate kan användas för att styra vilka rader som ska vara indragna. Det är t.ex. enkelt att lägga till prefix även till tomma rader och rader med enbart blanksteg:

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

Tillagd i version 3.3.

wrap(), fill() och shorten() fungerar genom att skapa en TextWrapper-instans och anropa en enda metod på den. Den instansen återanvänds inte, så för program som bearbetar många textsträngar med hjälp av wrap() och/eller fill() kan det vara effektivare att skapa ett eget TextWrapper-objekt.

Texten bryts helst på blanksteg och direkt efter bindestrecken i ord med bindestreck; först därefter bryts långa ord vid behov, såvida inte TextWrapper.break_long_words är satt till false.

class textwrap.TextWrapper(**kwargs)

Konstruktorn för TextWrapper accepterar ett antal valfria nyckelordsargument. Varje nyckelordsargument motsvarar ett instansattribut, så till exempel

wrapper = TextWrapper(initial_indent="* ")

är detsamma som

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

Du kan återanvända samma TextWrapper-objekt många gånger, och du kan ändra alla dess alternativ genom direkt tilldelning till instansattribut mellan användningarna.

Instansattributen för TextWrapper (och nyckelordsargument till konstruktören) är följande:

width

(standard: 70) Den maximala längden på omslutna rader. Så länge det inte finns några enskilda ord i inmatningstexten som är längre än width, garanterar TextWrapper att ingen utmatningsrad kommer att vara längre än width tecken.

expand_tabs

(default: True) Om true, kommer alla tabbtecken i text att expanderas till mellanslag med hjälp av expandtabs()-metoden i text.

tabsize

(default: 8) Om expand_tabs är true kommer alla tabbtecken i text att expanderas till noll eller fler mellanslag, beroende på aktuell kolumn och angiven tabbstorlek.

Tillagd i version 3.3.

replace_whitespace

(default: True) Om true används kommer metoden wrap() att ersätta varje blankstegstecken med ett enda mellanslag efter tabbexpansion men före ombrytning. De blankstegstecken som ersätts är följande: tabb, ny rad, vertikal tabb, formfeed och vagnsretur ('\t\n\v\f\r\).

Anteckning

Om expand_tabs är false och replace_whitespace är true kommer varje tabbtecken att ersättas med ett mellanslag, vilket inte är samma sak som tabbexpansion.

Anteckning

Om replace_whitespace är false kan nya linjer visas mitt på en rad och orsaka konstiga utdata. Av denna anledning bör text delas upp i stycken (med str.splitlines() eller liknande) som paketeras separat.

drop_whitespace

(standard: True) Om true används, tas blanksteg i början och slutet av varje rad (efter ombrytning men före indragning) bort. Whitespace i början av stycket tas dock inte bort om det följs av icke-whitespace. Om det blanksteg som ska tas bort upptar en hel rad, tas hela raden bort.

initial_indent

(standard: '') Sträng som läggs till på den första raden i den inplastade utdata. Räknas mot längden på den första raden. Den tomma strängen är inte indragen.

subsequent_indent

(standard: '') Sträng som kommer att läggas till alla rader i den inplastade utdata utom den första. Räknar mot längden på varje rad utom den första.

fix_sentence_endings

(default: False) Om true, försöker TextWrapper upptäcka meningsavslutningar och se till att meningarna alltid är åtskilda av exakt två mellanslag. Detta är i allmänhet önskvärt för text i ett monospaced-teckensnitt. Meningsdetekteringsalgoritmen är dock ofullständig: den antar att en meningsslut består av en gemen bokstav följd av en av '.', '!' eller '?', eventuellt följd av en av '"' eller "'", följt av ett mellanslag. Ett problem med den här algoritmen är att den inte kan upptäcka skillnaden mellan ”Dr.” i

[...] Dr Frankensteins monster [...]

och ”Spot.” i

[...] Se Spot. Se Spot springa [...]

fix_sentence_endings är false som standard.

Eftersom algoritmen för meningsdetektering bygger på string.lowercase för definitionen av ”gemen bokstav” och en konvention om att använda två mellanslag efter en punkt för att separera meningar på samma rad, är den specifik för engelskspråkiga texter.

break_long_words

(default: True) Om true, kommer ord som är längre än width att brytas för att säkerställa att inga rader är längre än width. Om den är false kommer långa ord inte att brytas, och vissa rader kan vara längre än width. (Långa ord kommer att placeras på en rad för sig för att minimera den mängd som width överskrids med)

break_on_hyphens

(default: True) Om true, kommer ombrytning att ske företrädesvis på blanksteg och direkt efter bindestreck i sammansatta ord, som det är brukligt på engelska. Om false, kommer endast blanksteg att betraktas som potentiellt bra platser för radbrytningar, men du måste ställa in break_long_words till false om du vill ha riktigt osäkra ord. Standardbeteendet i tidigare versioner var att alltid tillåta brytning av ord med bindestreck.

max_lines

(standard: None) Om inte None, kommer utdata att innehålla högst max_lines rader, med placeholder i slutet av utdata.

Tillagd i version 3.4.

placeholder

(standard: ' [...]') Sträng som visas i slutet av utdatatexten om den har avkortats.

Tillagd i version 3.4.

TextWrapper innehåller också några publika metoder, som motsvarar de praktiska funktionerna på modulnivå:

wrap(text)

Omsluter det enskilda stycket i text (en sträng) så att varje rad är högst width tecken lång. Alla ombrytningsalternativ hämtas från instansattributen i instansen TextWrapper. Returnerar en lista med utdatarader, utan avslutande nya linjer. Om det omslutna utdatat inte har något innehåll är den returnerade listan tom.

fill(text)

Omsluter ett stycke med text och returnerar en sträng som innehåller det omslutna stycket.