textwrap --- 文本自動(dòng)換行與填充?

源代碼: Lib/textwrap.py

textwrap 模塊提供了一些快捷函數，以及可以完成所有工作的類(lèi) TextWrapper。 如果你只是要對一兩個(gè)文本字符串進(jìn)行自動(dòng)換行或填充，快捷函數應該就夠用了；否則的話(huà)，你應該使用 TextWrapper 的實(shí)例來(lái)提高效率。

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 (字符串) 中的單獨段落自動(dòng)換行以使每行長(cháng)度最多為 width 個(gè)字符。 返回由輸出行組成的列表，行尾不帶換行符。

與 TextWrapper 的實(shí)例屬性對應的可選的關(guān)鍵字參數，具體文檔見(jiàn)下。

請參閱 TextWrapper.wrap() 方法了解有關(guān) 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 中的單獨段落自動(dòng)換行，并返回一個(gè)包含被自動(dòng)換行段落的單獨字符串。 fill() 是以下語(yǔ)句的快捷方式

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

特別要說(shuō)明的是，fill() 接受與 wrap() 完全相同的關(guān)鍵字參數。

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

折疊并截短給定的 text 以符合給定的 width。

首先，將折疊 text 中的空格（所有連續空格替換為單個(gè)空格）。 如果結果能適合 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...'

可選的關(guān)鍵字參數對應于 TextWrapper 的實(shí)際屬性，具體見(jiàn)下文。 請注意文本在被傳入 TextWrapper 的 fill() 函數之前會(huì )被折疊，因此改變 tabsize, expand_tabs, drop_whitespace 和 replace_whitespace 的值將沒(méi)有任何效果。

3.4 新版功能.

textwrap.dedent(text)?

移除 text 中每一行的任何相同前綴空白符。

這可以用來(lái)清除三重引號字符串行左側空格，而仍然在源碼中顯示為縮進(jìn)格式。

請注意制表符和空格符都被視為是空白符，但它們并不相等：以下兩行 "  hello" 和 "\thello" 不會(huì )被視為具有相同的前綴空白符。

只包含空白符的行會(huì )在輸入時(shí)被忽略并在輸出時(shí)被標準化為單個(gè)換行符。

例如：

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 中選定行的開(kāi)頭。

通過(guò)調用 text.splitlines(True) 來(lái)對行進(jìn)行拆分。

默認情況下，prefix 會(huì )被添加到所有不是只由空白符（包括任何行結束符）組成的行。

例如：

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

可選的 predicate 參數可用來(lái)控制哪些行要縮進(jìn)。 例如，可以很容易地為空行或只有空白符的行添加 prefix:

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

3.3 新版功能.

wrap(), fill() 和 shorten() 的作用方式為創(chuàng )建一個(gè) TextWrapper 實(shí)例并在其上調用單個(gè)方法。 該實(shí)例不會(huì )被重用，因此對于要使用 wrap() 和/或 fill() 來(lái)處理許多文本字符串的應用來(lái)說(shuō)，創(chuàng )建你自己的 TextWrapper 對象可能會(huì )更有效率。

文本最好在空白符位置自動(dòng)換行，包括帶連字符單詞的連字符之后；長(cháng)單詞僅在必要時(shí)會(huì )被拆分，除非 TextWrapper.break_long_words 被設為假值。

class textwrap.TextWrapper(**kwargs)?

TextWrapper 構造器接受多個(gè)可選的關(guān)鍵字參數。 每個(gè)關(guān)鍵字參數對應一個(gè)實(shí)例屬性，比如說(shuō)

wrapper = TextWrapper(initial_indent="* ")

相當于：

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

你可以多次重用相同的 TextWrapper 對象，并且你也可以在使用期間通過(guò)直接向實(shí)例屬性賦值來(lái)修改它的任何選項。

TextWrapper 的實(shí)例屬性（以及構造器的關(guān)鍵字參數）如下所示：

width?

(默認: 70) 自動(dòng)換行的最大行長(cháng)度。 只要輸入文本中沒(méi)有長(cháng)于 width 的單個(gè)單詞，TextWrapper 就能保證沒(méi)有長(cháng)于 width 個(gè)字符的輸出行。

expand_tabs?

(默認: True) 如果為真值，則 text 中所有的制表符將使用 text 的 expandtabs() 方法擴展為空格符。

tabsize?

(默認: 8) 如果 expand_tabs 為真值，則 text 中所有的制表符將擴展為零個(gè)或多個(gè)空格，具體取決于當前列位置和給定的制表寬度。

3.3 新版功能.

replace_whitespace?

(default: True) 如果為真值，在制表符擴展之后、自動(dòng)換行之前，wrap() 方法將把每個(gè)空白字符都替換為單個(gè)空格。 會(huì )被替換的空白字符如下：制表，換行，垂直制表，進(jìn)紙和回車(chē) ('\t\n\v\f\r')。

備注

如果 expand_tabs 為假值且 replace_whitespace 為真值，每個(gè)制表符將被替換為單個(gè)空格，這與制表符擴展是 不 一樣的。

備注

如果 replace_whitespace 為假值，在一行的中間有可能出現換行符并導致怪異的輸出。 因此，文本應當（使用 str.splitlines() 或類(lèi)似方法）拆分為段落并分別進(jìn)行自動(dòng)換行。

drop_whitespace?

(默認: True) 如果為真值，每一行開(kāi)頭和末尾的空白字符（在包裝之后、縮進(jìn)之前）會(huì )被丟棄。 但是段落開(kāi)頭的空白字符如果后面不帶任何非空白字符則不會(huì )被丟棄。 如果被丟棄的空白字符占據了一個(gè)整行，則該整行將被丟棄。

initial_indent?

(默認: '') 將被添加到被自動(dòng)換行輸出內容的第一行的字符串。 其長(cháng)度會(huì )被計入第一行的長(cháng)度。 空字符串不會(huì )被縮進(jìn)。

subsequent_indent?

(default: '') 將被添加到被自動(dòng)換行輸出內容除第一行外的所有行的字符串。 其長(cháng)度會(huì )被計入除行一行外的所有行的長(cháng)度。

fix_sentence_endings?

(默認: False) 如果為真值，TextWrapper 將嘗試檢測句子結尾并確保句子間總是以恰好兩個(gè)空格符分隔。 對于使用等寬字體的文本來(lái)說(shuō)通常都需要這樣。 但是，句子檢測算法并不完美：它假定句子結尾是一個(gè)小寫(xiě)字母加字符 '.', '!' 或 '?' 中的一個(gè)，并可能帶有字符 '"' 或 "'"，最后以一個(gè)空格結束。 此算法的問(wèn)題之一是它無(wú)法區分以下文本中的 "Dr."

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

和以下文本中的 "Spot."

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

fix_sentence_endings 默認為假值。

由于句子檢測算法依賴(lài)于 string.lowercase 來(lái)確定“小寫(xiě)字母”，以及約定在句點(diǎn)后使用兩個(gè)空格來(lái)分隔處于同一行的句子，因此只適用于英語(yǔ)文本。

break_long_words?

(默認: True) 如果為真值，則長(cháng)度超過(guò) width 的單詞將被分開(kāi)以保證行的長(cháng)度不會(huì )超過(guò) width。 如果為假值，超長(cháng)單詞不會(huì )被分開(kāi)，因而某些行的長(cháng)度可能會(huì )超過(guò) width。 （超長(cháng)單詞將被單獨作為一行，以盡量減少超出 width 的情況。）

break_on_hyphens?

(默認: True) 如果為真值，將根據英語(yǔ)的慣例首選在空白符和復合詞的連字符之后自動(dòng)換行。 如果為假值，則只有空白符會(huì )被視為合適的潛在斷行位置，但如果你確實(shí)不希望出現分開(kāi)的單詞則你必須將 break_long_words 設為假值。 之前版本的默認行為總是允許分開(kāi)帶有連字符的單詞。

max_lines?

(默認: None) 如果不為 None，則輸出內容將最多包含 max_lines 行，并使 placeholder 出現在輸出內容的末尾。

3.4 新版功能.

placeholder?

(默認: ' [...]') 該文本將在輸出文本被截短時(shí)出現在文本末尾。

3.4 新版功能.

TextWrapper 還提供了一些公有方法，類(lèi)似于模塊層級的便捷函數：

wrap(text)?

對 text (字符串) 中的單獨段落自動(dòng)換行以使每行長(cháng)度最多為 width 個(gè)字符。 所有自動(dòng)換行選項均獲取自 TextWrapper 實(shí)例的實(shí)例屬性。 返回由輸出行組成的列表，行尾不帶換行符。 如果自動(dòng)換行輸出結果沒(méi)有任何內容，則返回空列表。

fill(text)?

對 text 中的單獨段落自動(dòng)換行并返回包含被自動(dòng)換行段落的單獨字符串。