6.4. textwrap — テキストの折り返しと詰め込み¶
ソースコード: Lib/textwrap.py
textwrap モジュールは、実際の処理を行う TextWrapper とともに、いくつかの便利な関数を提供しています。1つか2つの文字列を wrap あるいは fill するだけの場合は便利関数で十分ですが、多くの処理を行う場合は効率のために TextWrapper のインスタンスを使うべきでしょう。
-
textwrap.wrap(text, width=70, **kwargs)¶ text (文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行が高々 width 文字の長さになります。最後に改行が付かない出力行のリストを返します。
オプションのキーワード引数は、以下で説明する
TextWrapperのインスタンス属性に対応しています。 width はデフォルトで70です。wrap()の動作についての詳細はTextWrapper.wrap()メソッドを参照してください。
-
textwrap.fill(text, width=70, **kwargs)¶ text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。
fill()はこれの省略表現です"\n".join(wrap(text, ...))
-
textwrap.shorten(text, width, **kwargs)¶ 与えられた text を折りたたみ、切り詰めて、与えられた width に収まるようにします。
最初に、text 内の空白が折りたたまれます (すべての空白を、1 文字の空白文字で置き換えます)。結果が width 内に収まった場合、その結果が返されます。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)¶ text の中の選択された行の先頭に prefix を追加します。
行の分割は
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 が偽に設定されていなければ、必要な場合に長い語が分解されます。
-
class
textwrap.TextWrapper(**kwargs)¶ TextWrapperコンストラクタはたくさんのオプションのキーワード引数を受け取ります。それぞれのキーワード引数は一つのインスタンス属性に対応します。したがって、例えばwrapper = TextWrapper(initial_indent="* ")
はこれと同じです
wrapper = TextWrapper() wrapper.initial_indent = "* "
あなたは同じ
TextWrapperオブジェクトを何回も再利用できます。また、使用中にインスタンス属性へ代入することでそのオプションのどれでも変更できます。TextWrapperインスタンス属性(とコンストラクタのキーワード引数)は以下の通りです:-
width¶ (デフォルト:
70) 折り返しが行われる行の最大の長さ。入力行にwidthより長い単一の語が無い限り、TextWrapperはwidth文字より長い出力行が無いことを保証します。
-
expand_tabs¶ (デフォルト:
True) もし真ならば、そのときは text 内のすべてのタブ文字は text のexpandtabs()メソッドを用いて空白に展開されます。
-
tabsize¶ (デフォルト:
8)expand_tabsが真の場合、 text の中のすべてのTAB文字は tabsize と現在のカラムに応じて、ゼロ以上のスペースに展開されます。バージョン 3.3 で追加.
-
replace_whitespace¶ (デフォルト:
True) 真の場合、wrap()メソッドはタブの展開の後、 wrap 処理の前に各種空白文字をスペース1文字に置換します。置換される空白文字は: TAB, 改行, 垂直TAB, FF, CR ('\t\n\v\f\r') です。注釈
expand_tabsが偽でreplace_whitespaceが真ならば、各タブ文字は1つの空白に置き換えられます。それはタブ展開と同じでは ありません 。注釈
replace_whitespaceが偽の場合、改行が行の途中で現れることで出力がおかしくなることがあります。このため、テキストを(str.splitlines()などを使って)段落ごとに分けて別々に wrap する必要があります。
-
drop_whitespace¶ (デフォルト:
True) 真の場合、(wrap 処理のあとインデント処理の前に) 各行の最初と最後の空白文字を削除します。ただし、段落の最初の空白については、次の文字が空白文字でない場合は削除されません。削除される空白文字が行全体に及ぶ場合は、行自体を削除します。
-
initial_indent¶ (default:
'') wrap の出力の最初の行の先頭に付与する文字列。最初の行の長さに加算されます。空文字列の場合インデントされません。
-
subsequent_indent¶ (デフォルト:
'') 一行目以外の折り返しが行われる出力のすべての行の先頭に付けられる文字列。一行目以外の各行の折り返しまでの長さにカウントされます。
-
fix_sentence_endings¶ (デフォルト:
False) もし真ならば、TextWrapperは文の終わりを見つけようとし、確実に文がちょうど二つの空白で常に区切られているようにします。これは一般的に固定スペースフォントのテキストに対して望ましいです。しかし、文の検出アルゴリズムは完全ではありません: 文の終わりには、後ろに空白がある'.','!'または'?'の中の一つ、ことによると'"'あるいは"'"が付随する小文字があると仮定しています。これに伴う一つの問題はアルゴリズムで下記の”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) 真の場合、英語で一般的なように、ラップ処理は空白か合成語に含まれるハイフンの直後で行われます。偽の場合、空白だけが改行に適した位置として判断されます。ただし、本当に語の途中で改行が行われないようにするためには、break_long_words属性を真に設定する必要があります。過去のバージョンでのデフォルトの振る舞いは、常にハイフンの直後での改行を許していました。
-
max_lines¶ (デフォルト
None)None以外の場合、出力は行数 max_lines を超えないようにされ、切り詰める際には出力の最後の行を placeholder に置き換えます。バージョン 3.4 で追加.
-
placeholder¶ (デフォルト:
' [...]') 切り詰める場合に出力の最後の行に置く文字列です。バージョン 3.4 で追加.
TextWrapperはモジュールレベルの簡易関数に類似したいくつかの公開メソッドも提供します:-
wrap(text)¶ 1段落の文字列 text を、各行が
width文字以下になるように wrap します。 wrap のすべてのオプションはTextWrapperインスタンスの属性から取得します。結果の、行末に改行のない行のリストを返します。出力の内容が空になる場合は、返すリストも空になります。
-
fill(text)¶ text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。
-