# 4.8 `textwrap` -- テキストの折り返しと詰め込み

バージョン2.3 以降で新規追加された 仕様です。

`textwrap`モジュールでは、二つの簡易関数`wrap()`と `fill()`、そして作業のすべてを行うクラス`TextWrapper` とユーティリティ関数 `dedent()` を提供しています。 単に一つや二つのテキスト文字列の折り返しまたは詰め込みを行っている ならば、簡易関数で十分間に合います。そうでなければ、 効率のために`TextWrapper`のインスタンスを使った方が良いでしょう。

`wrap`( | text[, width[, ...]])

  text(文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行が高々width文字の長さになります。最後に改行が付かない出力行のリストを返します。

  オプションのキーワード引数は、以下で説明する`TextWrapper`のインスタンス属性に対応しています。widthはデフォルトで`70`です。

`fill`( | text[, width[, ...]])

  text内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。`fill()`は

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

  の省略表現です。

  特に、`fill()`は`wrap()`とまったく同じ名前のキーワード引数を受け取ります。

`wrap()`と`fill()`の両方ともが`TextWrapper`インスタンスを作成し、その一つのメソッドを呼び出すことで機能します。そのインスタンスは再利用されません。したがって、たくさんのテキスト文字列を折り返し/詰め込みを行うアプリケーションのためには、あなた自身の`TextWrapper`オブジェクトを作成することでさらに効率が良くなるでしょう。

追加のユーティリティ関数である `dedent()` は、不要な 空白をテキストの左側に持つ文字列からインデントを取り去ります。

`dedent`( | text)

  text の各行に対し、左側から一様に取り去ることができるような空白 を除去します。

  この関数は通常、三重引用符で囲われた文字列をスクリーン/その他の 左端にそろえ、なおかつソースコード中でのインデントされた形式を 損なわないようにするために使われます。

  以下に例を示します:

      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'

class `TextWrapper`( | ...)

  `TextWrapper`コンストラクタはたくさんのオプションのキーワード引数を受け取ります。それぞれの引数は一つのインスタンス属性に対応します。したがって、例えば、

      wrapper = TextWrapper(initial_indent="* ")

  は

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

  と同じです。

  あなたは同じ`TextWrapper`オブジェクトを何回も再利用できます。また、使用中にインスタンス属性へ代入することでそのオプションのどれでも変更できます。

`TextWrapper`インスタンス属性(とコンストラクタのキーワード引数)は以下の通りです:

`width`
  (デフォルト: `70`) 折り返しが行われる行の最大の長さ。入力行に`width`より長い単一の語が無い限り、`TextWrapper`は`width`文字より長い出力行が無いことを保証します。

`expand_tabs`
  (デフォルト: `True`) もし真ならば、そのときはtext内のすべてのタブ文字はtextの`expand_tabs()`メソッドを用いて空白に展開されます。

`replace_whitespace`
  (デフォルト: `True`) もし真ならば、タブ展開の後に残る(`string.whitespace`に定義された)空白文字のそれぞれが一つの空白と置き換えられます。注意: `expand_tabs`が偽で`replace_whitespace`が真ならば、各タブ文字は一つの空白に置き換えられます。それはタブ展開と同じではありません。

`initial_indent`
  (デフォルト: `''`) 折り返しが行われる出力の一行目の先頭に付けられる文字列。一行目の折り返しの長さになるまで含められます。

`subsequent_indent`
  (デフォルト: `''`) 一行目以外の折り返しが行われる出力のすべての行の先頭に付けられる文字列。一行目以外の各行が折り返しの長さまで含められます。

`fix_sentence_endings`
  (デフォルト: `False`) もし真ならば、`TextWrapper`は文の終わりを見つけようとし、確実に文がちょうど二つの空白で常に区切られているようにします。これは一般的に固定スペースフォントのテキストに対して望ましいです。しかし、文の検出アルゴリズムは完全ではありません: 文の終わりには、後ろに空白がある"`.`"、"`!`"または"`?`"の中の一つ、ことによると"`"`"あるいは"`'`"が付随する小文字があると仮定しています。これに伴う一つの問題は

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

  の``Dr.''と

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

  の``Spot.''の間の差異を検出できないアルゴリズムです。

  `fix_sentence_endings`はデフォルトで偽です。

  文検出アルゴリズムは``小文字''の定義のために`string.lowercase`に依存し、同一行の文を区切るためにピリオドの後に二つの空白を使う慣習に依存しているため、英文テキストに限定されたものです。

`break_long_words`
  (デフォルト: `True`) もし真ならば、そのとき`width`より長い行が確実にないようにするために、`width`より長い語は切られます。偽ならば、長い語は切られないでしょう。そして、`width`より長い行があるかもしれません。(`width`を超える分を最小にするために、長い語は単独で一行に置かれるでしょう。)

`TextWrapper`はモジュールレベルの簡易関数に類似した二つの公開メソッドも提供します:

`wrap`( | text)

  text(文字列)内の段落を一つだけ折り返しを行います。したがって、すべての行は高々`width`文字です。すべてのラッピングオプションは`TextWrapper`インスタンスのインスタンス属性から取られています。最後に改行の無い出力された行のリストを返します。

`fill`( | text)

  text内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。