バージョン 2.3 で追加.
textwrap モジュールでは、二つの簡易関数 wrap() と fill() 、そして作業のすべてを行うクラス TextWrapper とユーティリティ関数 dedent() を提供しています。単に一つや二つのテキスト文字列の折り返しまたは詰め込みを行っているならば、簡易関数で十分間に合います。そうでなければ、 効率のために TextWrapper のインスタンスを使った方が良いでしょう。
text (文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行が高々 width 文字の長さになります。最後に改行が付かない出力行のリストを返します。
オプションのキーワード引数は、以下で説明する TextWrapper のインスタンス属性に対応しています。 width はデフォルトで 70 です。
text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。 fill() は
"\n".join(wrap(text, ...))
の省略表現です。
wrap() と fill() の両方ともが TextWrapper インスタンスを作成し、その一つのメソッドを呼び出すことで機能します。 そのインスタンスは再利用されません。 したがって、たくさんのテキスト文字列を折り返し/詰め込みを行うアプリケーションのためには、あなた自身の TextWrapper オブジェクトを作成することでさらに効率が良くなるでしょう。
テキストはなるべく空白か、ハイフンを含む語のハイフンの直後で折り返されます。 TextWrapper.break_long_words が偽に設定されていなければ、必要な場合に長い語が分解されます。
追加のユーティリティ関数である dedent() は、不要な空白をテキストの左側に持つ文字列からインデントを取り去ります。
text の各行に対し、共通して現れる先頭の空白を削除します。
この関数は通常、三重引用符で囲われた文字列をスクリーン/その他の左端にそろえ、なおかつソースコード中ではインデントされた形式を 損なわないようにするために使われます。
タブとスペースはともにホワイトスペースとして扱われますが、同じではないことに注意してください: " hello" という行と "\thello" は、同じ先頭の空白文字をもっていないとみなされます。(このふるまいは Python 2.5で導入されました。古いバージョ ンではこのモジュールは不正にタブを展開して共通の先頭空白文字列を探していました)
以下に例を示します:
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'
TextWrapper コンストラクタはたくさんのオプションのキーワード引数を受け取ります。それぞれの引数は一つのインスタンス属性に対応します。したがって、例えば、
wrapper = TextWrapper(initial_indent="* ")
は
wrapper = TextWrapper()
wrapper.initial_indent = "* "
と同じです。
あなたは同じ TextWrapper オブジェクトを何回も再利用できます。また、使用中にインスタンス属性へ代入することでそのオプションのどれでも変更できます。
TextWrapper インスタンス属性(とコンストラクタのキーワード引数)は以下の通りです:
(デフォルト: 70) 折り返しが行われる行の最大の長さ。 入力行に width より長い単一の語が無い限り、 TextWrapper は width 文字より長い出力行が無いことを保証します。
(デフォルト: True) もし真ならば、そのときは text 内のすべてのタブ文字は text の expand_tabs() メソッドを用いて空白に展開されます。
(デフォルト: True) もし真ならば、タブ展開の後に残る(string.whitespace に定義された)空白文字のそれぞれが一つの空白と置き換えられます。
ノート
expand_tabs が偽で replace_whitespace が真ならば、各タブ文字は1つの空白に置き換えられます。それはタブ展開と同じでは ありません 。
(デフォルト: True) 真の場合、ラップ後に行末や行頭にあるスペースが削除されます。 (最初の行の先頭の空白は残ります)
バージョン 2.6 で追加: .. Whitespace was always dropped in earlier versions.
過去のバージョンでは、空白は常に削除されていました。
(デフォルト: '') 折り返しが行われる出力の一行目の先頭に付けられる文字列。 一行目の折り返しまでの長さにカウントされます。
(デフォルト: '') 一行目以外の折り返しが行われる出力のすべての行の先頭に付けられる文字列。 一行目以外の各行の折り返しまでの長さにカウントされます。
(デフォルト: False) もし真ならば、 TextWrapper は文の終わりを見つけようとし、確実に文がちょうど二つの空白で常に区切られているようにします。 これは一般的に固定スペースフォントのテキストに対して望ましいです。 しかし、文の検出アルゴリズムは完全ではありません: 文の終わりには、後ろに空白がある '.', '!' または '?' の中の一つ、ことによると '"' あるいは ''' が付随する小文字があると仮定しています。これに伴う一つの問題は
[...] Dr. Frankenstein's monster [...]
の”Dr.”と
[...] See Spot. See Spot run [...]
の”Spot.”の間の差異を検出できないアルゴリズムです。
fix_sentence_endings はデフォルトで偽です。
文検出アルゴリズムは”小文字”の定義のために string.lowercase に依存し、同一行の文を区切るためにピリオドの後に二つの空白を使う慣習に依存しているため、英文テキストに限定されたものです。
(デフォルト: True) もし真ならば、そのとき width より長い行が確実にないようにするために、 width より長い語は切られます。 偽ならば、長い語は切られないでしょう。そして、 width より長い行があるかもしれません。 (width を超える分を最小にするために、長い語は単独で一行に置かれるでしょう。)
(デフォルト: True) 真の場合、英語で一般的なように、ラップ処理は空白か合成語に含まれるハイフンの直後で行われます。 偽の場合、空白だけが改行に適した位置として判断されます。ただし、本当に語の途中で改行が行われないようにするためには、 break_long_words 属性を真に設定する必要があります。 過去のバージョンでのデフォルトの振る舞いは、常にハイフンの直後での改行を許していました。
バージョン 2.6 で追加.
TextWrapper はモジュールレベルの簡易関数に類似した二つの公開メソッドも提供します:
text (文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行は高々 width 文字です。すべてのラッピングオプションは TextWrapper インスタンスのインスタンス属性から取られています。最後に改行の無い出力された行のリストを返します。
text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。