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

源代碼: Lib/textwrap.py

textwrap 模塊提供了一些快捷函數(shù)，以及可以完成所有工作的類 TextWrapper。 如果你只是要對(duì)一兩個(gè)文本字符串進(jìn)行自動(dòng)換行或填充，快捷函數(shù)應(yīng)該就夠用了；否則的話，你應(yīng)該使用 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=' [...]')?

對(duì) text (字符串) 中的單獨(dú)段落自動(dòng)換行以使每行長(zhǎng)度最多為 width 個(gè)字符。 返回由輸出行組成的列表，行尾不帶換行符。

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

請(qǐng)參閱 TextWrapper.wrap() 方法了解有關(guān) wrap() 行為的詳細(xì)信息。

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

對(duì) text 中的單獨(dú)段落自動(dòng)換行，并返回一個(gè)包含被自動(dòng)換行段落的單獨(dú)字符串。 fill() 是以下語(yǔ)句的快捷方式

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

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

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

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

首先，將折疊 text 中的空格（所有連續(xù)空格替換為單個(gè)空格）。 如果結(jié)果能適合 width 則將其返回。 否則將丟棄足夠數(shù)量的末尾單詞以使得剩余單詞加 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)鍵字參數(shù)對(duì)應(yīng)于 TextWrapper 的實(shí)際屬性，具體見(jiàn)下文。 請(qǐng)注意文本在被傳入 TextWrapper 的 fill() 函數(shù)之前會(huì)被折疊，因此改變 tabsize, expand_tabs, drop_whitespace 和 replace_whitespace 的值將沒(méi)有任何效果。

3.4 新版功能.

textwrap.dedent(text)?

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

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

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

只包含空白符的行會(huì)在輸入時(shí)被忽略并在輸出時(shí)被標(biāo)準(zhǔn)化為單個(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ò)調(diào)用 text.splitlines(True) 來(lái)對(duì)行進(jìn)行拆分。

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

例如：

>>>

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

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

>>>

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

3.3 新版功能.

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

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

class textwrap.TextWrapper(**kwargs)?

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

wrapper = TextWrapper(initial_indent="* ")

相當(dāng)于：

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

你可以多次重用相同的 TextWrapper 對(duì)象，并且你也可以在使用期間通過(guò)直接向?qū)嵗龑傩再x值來(lái)修改它的任何選項(xiàng)。

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

width?

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

expand_tabs?

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

tabsize?

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

3.3 新版功能.

replace_whitespace?

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

備注

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

備注

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

drop_whitespace?

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

initial_indent?

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

subsequent_indent?

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

fix_sentence_endings?

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

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

和以下文本中的 "Spot."

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

fix_sentence_endings 默認(rèn)為假值。

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

break_long_words?

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

break_on_hyphens?

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

max_lines?

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

3.4 新版功能.

placeholder?

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

3.4 新版功能.

TextWrapper 還提供了一些公有方法，類似于模塊層級(jí)的便捷函數(shù)：

wrap(text)?

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

fill(text)?

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