textwrap --- 文本自動換行與填充?

源代碼: Lib/textwrap.py

textwrap 模塊提供了一些快捷函數(shù)，以及可以完成所有工作的類 TextWrapper。 如果你只是要對一兩個文本字符串進行自動換行或填充，快捷函數(shù)應(yīng)該就夠用了；否則的話，你應(yīng)該使用 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 的實例屬性對應(yīng)的可選的關(guān)鍵字參數(shù)，具體文檔見下。

請參閱 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 中的單獨段落自動換行，并返回一個包含被自動換行段落的單獨字符串。 fill() 是以下語句的快捷方式

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

特別要說明的是，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ù)空格替換為單個空格）。 如果結(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ù)對應(yīng)于 TextWrapper 的實際屬性，具體見下文。 請注意文本在被傳入 TextWrapper 的 fill() 函數(shù)之前會被折疊，因此改變 tabsize, expand_tabs, drop_whitespace 和 replace_whitespace 的值將沒有任何效果。

3.4 新版功能.

textwrap.dedent(text)?

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

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

請注意制表符和空格符都被視為是空白符，但它們并不相等：以下兩行 "  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 中選定行的開頭。

通過調(diào)用 text.splitlines(True) 來對行進行拆分。

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

例如：

>>>

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

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

>>>

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

3.3 新版功能.

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

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

class textwrap.TextWrapper(**kwargs)?

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

wrapper = TextWrapper(initial_indent="* ")

相當于：

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

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

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

width?

(默認: 70) 自動換行的最大行長度。 只要輸入文本中沒有長于 width 的單個單詞，TextWrapper 就能保證沒有長于 width 個字符的輸出行。

expand_tabs?

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

tabsize?

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

3.3 新版功能.

replace_whitespace?

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

備注

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

備注

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

drop_whitespace?

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

initial_indent?

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

subsequent_indent?

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

fix_sentence_endings?

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

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

和以下文本中的 "Spot."

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

fix_sentence_endings 默認為假值。

由于句子檢測算法依賴于 string.lowercase 來確定“小寫字母”，以及約定在句點后使用兩個空格來分隔處于同一行的句子，因此只適用于英語文本。

break_long_words?

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

break_on_hyphens?

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

max_lines?

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

3.4 新版功能.

placeholder?

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

3.4 新版功能.

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

wrap(text)?

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

fill(text)?

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