textwrap --- テキストの折り返しと詰め込み¶
ソースコード: Lib/textwrap.py
The textwrap module provides some convenience functions,
as well as TextWrapper, the class that does all the work.
If you're just wrapping or filling one or two text strings, the convenience
functions should be good enough; otherwise, you should use an instance of
TextWrapper for efficiency.
- 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のインスタンス属性に対応しています。wrap()の動作についての詳細はTextWrapper.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, ...))
- textwrap.shorten(text, width, *, fix_sentence_endings=False, break_long_words=True, break_on_hyphens=True, placeholder=' [...]')¶
与えられた 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の値を変更しても、意味がありません。Added in version 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'
バージョン 3.14 で変更: The
dedent()function now correctly normalizes blank lines containing only whitespace characters. Previously, the implementation only normalized blank lines containing tabs and spaces.
- 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
Added in version 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 と現在のカラムに応じて、ゼロ以上のスペースに展開されます。Added in version 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 に置き換えます。Added in version 3.4.
- placeholder¶
(デフォルト:
' [...]') 切り詰める場合に出力の最後の行に置く文字列です。Added in version 3.4.
TextWrapperはモジュールレベルの簡易関数に類似したいくつかの公開メソッドも提供します:- wrap(text)¶
1段落の文字列 text を、各行が
width文字以下になるように wrap します。 wrap のすべてのオプションはTextWrapperインスタンスの属性から取得します。結果の、行末に改行のない行のリストを返します。出力の内容が空になる場合は、返すリストも空になります。
- fill(text)¶
text 内の段落を一つだけ折り返しを行い、折り返しが行われた段落を含む一つの文字列を返します。