textwrap — 文字換行和填充

原始碼: Lib/textwrap.py

textwrap 模組提供了一些便捷函式，以及完成所有工作的類 TextWrapper。如果你只是換行或填充一兩個文字字串，便捷函式就足夠了；否則，為了效率，你應該使用 TextWrapper 的例項。

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

將 text（字串）中的單個段落換行，使得每行最多 width 個字元。返回一個輸出行列表，不帶最終的換行符。

可選的關鍵字引數對應於 TextWrapper 的例項屬性，如下所述。

有關 wrap() 行為的更多詳細資訊，請參見 TextWrapper.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=' [...]')

將 text 中的單個段落換行，並返回包含已換行段落的單個字串。fill() 是以下內容的簡寫：

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

特別是，fill() 接受與 wrap() 完全相同的關鍵字引數。

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

摺疊並截斷給定的 text 以適應給定的 width。

首先，text 中的空白被摺疊（所有空白都被替換為單個空格）。如果結果符合 width，則返回。否則，從末尾刪除足夠的單詞，使剩餘的單詞加上 placeholder 適合 width。

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

可選的關鍵字引數對應於 TextWrapper 的例項屬性，如下所述。請注意，在文字傳遞給 TextWrapper 的 fill() 函式之前，空白會被摺疊，因此更改 tabsize、expand_tabs、drop_whitespace 和 replace_whitespace 的值將無效。

在 3.4 版本加入。

textwrap.dedent(text)

從 text 中的每一行移除任何常見的行首空白。

這可用於使三引號字串與顯示屏的左邊緣對齊，同時在原始碼中以縮排形式呈現它們。

請注意，製表符和空格都被視為空白，但它們不相等：行 "  hello" 和 "\thello" 被認為沒有共同的行首空白。

輸入中僅包含空白的行將被忽略，並在輸出中標準化為單個換行符。

例如:

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)

將 prefix 新增到 text 中選定行的開頭。

透過呼叫 text.splitlines(True) 來分隔行。

預設情況下，prefix 會新增到所有不完全由空白（包括任何行尾字元）組成的行。

例如:

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

可選的 predicate 引數可用於控制哪些行被縮排。例如，很容易將 prefix 新增到空行和僅包含空白的行中。

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

在 3.3 版本加入。

wrap()、fill() 和 shorten() 透過建立一個 TextWrapper 例項並呼叫其上的單個方法來工作。該例項不會被重用，因此對於使用 wrap() 和/或 fill() 處理許多文字字串的應用程式，建立自己的 TextWrapper 物件可能更高效。

文字優先在空格處和帶連字元的單詞中的連字元後進行換行；只有在必要時才會拆分長單詞，除非 TextWrapper.break_long_words 設定為 False。

class textwrap.TextWrapper(**kwargs)

TextWrapper 建構函式接受許多可選的關鍵字引數。每個關鍵字引數都對應一個例項屬性，例如

wrapper = TextWrapper(initial_indent="* ")

與以下相同

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

您可以多次重用同一個 TextWrapper 物件，並且您可以在每次使用之間透過直接賦值給例項屬性來更改其任何選項。

TextWrapper 例項屬性（和建構函式的可選關鍵字引數）如下：

width

（預設值：70）換行行的最大長度。只要輸入文字中沒有單個單詞的長度超過 width，TextWrapper 就保證沒有輸出行會比 width 字元長。

expand_tabs

（預設值：True）如果為 True，則 text 中的所有制表符都將使用 text 的 expandtabs() 方法展開為空格。

tabsize

（預設值：8）如果 expand_tabs 為 True，則 text 中的所有制表符都將根據當前列和給定的製表符大小擴充套件為零個或多個空格。

在 3.3 版本加入。

replace_whitespace

（預設值：True）如果為 True，則在製表符展開後但在換行之前，wrap() 方法會將每個空白字元替換為單個空格。替換的空白字元如下：製表符、換行符、垂直製表符、換頁符和回車符（'\t\n\v\f\r'）。

備註

如果 expand_tabs 為 False 且 replace_whitespace 為 True，則每個製表符都將替換為單個空格，這與製表符展開 不同。

備註

如果 replace_whitespace 為 False，則換行符可能會出現在行的中間並導致奇怪的輸出。因此，文字應拆分為段落（使用 str.splitlines() 或類似方法），並分別進行換行。

drop_whitespace

（預設值：True）如果為 True，則（換行後但在縮排前）每行開頭和結尾的空白將被刪除。但是，如果後面有非空白字元，則段落開頭的空白不會被刪除。如果被刪除的空白佔據整行，則整行將被刪除。

initial_indent

（預設值：''）將新增到換行輸出的第一行開頭的字串。計入第一行的長度。空字串不縮排。

subsequent_indent

（預設值：''）將新增到除第一行之外的所有換行輸出行開頭的字串。計入除第一行之外的每行的長度。

fix_sentence_endings

（預設值：False）如果為 True，TextWrapper 將嘗試檢測句子結尾，並確保句子始終用兩個空格分隔。這對於等寬字型的文字通常是期望的。但是，句子檢測演算法並不完善：它假定句子結尾由一個小寫字母后跟 '.'、'!' 或 '?' 之一組成，可能後跟 '"' 或 "'" 之一，再後跟一個空格。此演算法的一個問題是它無法區分以下情況中的“Dr.”

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

和以下情況中的“Spot.”

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

fix_sentence_endings 預設為 False。

由於句子檢測演算法依賴於 string.lowercase 來定義“小寫字母”，以及在句號後使用兩個空格來分隔同一行上的句子的約定，因此它僅適用於英語文字。

break_long_words

（預設值：True）如果為 True，則長度超過 width 的單詞將被拆分，以確保沒有一行長於 width。如果為 False，則長單詞不會被拆分，有些行可能長於 width。（長單詞將單獨佔一行，以儘量減少超出 width 的量。）

break_on_hyphens

（預設值：True）如果為 True，換行將優先在空格和複合詞的連字元後發生，這在英語中是慣例。如果為 False，則只有空格會被視為潛在的良好斷行位置，但如果您想要真正不可分割的單詞，則需要將 break_long_words 設定為 False。先前版本中的預設行為是始終允許拆分帶連字元的單詞。

max_lines

（預設值：None）如果不是 None，則輸出最多包含 max_lines 行，其中 placeholder 出現在輸出的末尾。

在 3.4 版本加入。

placeholder

（預設值：' [...]'）如果輸出文字被截斷，將出現在輸出文字末尾的字串。

在 3.4 版本加入。

TextWrapper 還提供了一些公共方法，類似於模組級的便捷函式

wrap(text)

將 text（字串）中的單個段落換行，使得每行最多 width 個字元長。所有換行選項都取自 TextWrapper 例項的例項屬性。返回一個輸出行列表，不帶最終的換行符。如果換行輸出沒有內容，則返回的列表為空。

fill(text)

將 text 中的單個段落換行，並返回一個包含已換行段落的單個字串。