Pythonのtextwrapでコマンドライン出力を美しく整形する方法

Pythonを使ってスクリプトを書いていると、コマンドラインにテキストを表示する場面はとても多いですよね。

ログを出力したり、エラーメッセージを表示したり、あるいはちょっとした説明文を流したり。

私自身、エンジニアとして10年以上Pythonを触ってきましたが、見やすくきれいに整形された出力というのは、想像以上に大切だと感じています。

特に、初心者の方がスクリプトを学び始めたときに、ただ文字をずらずら出力するのと、行が整っていて読みやすいのとでは、理解のしやすさがまるで違います。

この記事では、Python標準ライブラリに含まれているtextwrapモジュールを使って、コマンドライン出力を整える方法を、わかりやすく丁寧に解説していきます。

なぜ「整形」が大事なのか？¶

まず、少し立ち止まって考えてみましょう。

コマンドラインに出力される文章は、ほとんどがモノクロで、フォントの大きさも変わりません。 つまり、「行の見やすさ」や「折り返し方」がそのまま読みやすさに直結します。

例えば、こんな文章をそのまま出力してしまうことはありませんか？

long_text = "Pythonのtextwrapモジュールはとても便利で、長い文章を自動的に折り返したり、インデントを追加したり、ちょうど良い幅に整形することができます。これを知っていると知らないとでは、プログラムの見栄えや使いやすさが大きく変わってきます。"
print(long_text)

このままだと、端末の横幅を超えてしまい、横にスクロールしないと読めない場合があります。 これではユーザーに優しくありませんし、エラーメッセージなどは特にどこからどこまでが1つの文章なのかが分かりづらくなってしまいます。

そこで登場するのが textwrap です。

textwrapとは？¶

textwrapは、Pythonの標準ライブラリに含まれているモジュールで、文字列を指定した幅に整形してくれるツールです。

追加のインストールは不要で、すぐに使えます。

私の個人的な感想ですが、このモジュールはシンプルだけど使い勝手が抜群です。 普段の小さなスクリプトから業務用のツールまで、幅広く役立ってくれます。

基本的な使い方¶

まずは一番シンプルな例から見てみましょう。 以下のように利用します。

import textwrap

long_text = "Pythonのtextwrapモジュールはとても便利で、長い文章を自動的に折り返したり、インデントを追加したり、ちょうど良い幅に整形することができます。"

wrapped = textwrap.fill(long_text, width=30)
print(wrapped)

このコードを実行すると、30文字ごとに自動で折り返され、きれいに整列した文章が表示されます。

実際に出力されるイメージはこんな感じです。

Pythonのtextwrapモジュールはとても
便利で、長い文章を自動的に折り返
したり、インデントを追加したり、
ちょうど良い幅に整形することがで
きます。

ただ出力するだけなのに、ここまで読みやすくなると気持ちいいですよね。

よく使う関数まとめ¶

textwrapにはいくつかの便利な関数があります。

よく使うものを一覧表にまとめてみました。

関数名	説明
fill()	指定した幅で折り返した文字列を返す。
wrap()	リスト形式で折り返し後の行を返す。
shorten()	指定幅を超える場合に省略記号（…）でカットしてくれる。
dedent()	文字列の先頭のインデント（スペース）を取り除いてくれる。
indent()	各行の先頭に任意の文字列（例えば「- 」やスペース）を追加してくれる。

こうして一覧にしてみると、「ただの折り返し」以上のことができるのがわかりますね。 特に shorten() や dedent() は、ログ出力やユーザーへの説明文にとても役立ちます。

indentで見やすいリストを作る¶

textwrapを使うと、リスト形式の出力も自然に整形できます。

例えば、次のように使うことができます。

items = ["Python", "JavaScript", "Go", "Rust", "TypeScript"]

text = "\n".join(items)
indented = textwrap.indent(text, " - ")
print(indented)

出力結果は次のようになります。

 - Python
 - JavaScript
 - Go
 - Rust
 - TypeScript

これならユーザーに見せる際も「ちゃんと整ったリスト」に見えますよね。 単なる print ではここまで美しくできません。

実務での活用例¶

私が実際に仕事で活用しているシーンをいくつかご紹介します。

ログ整形¶

よく使う場面は、ログ整形です。 APIから取得した長いレスポンスをそのまま表示すると、横にだらだらと伸びてしまいます。 そんなとき、textwrapで適切に改行すると、デバッグが格段にしやすくなります。

ヘルプメッセージの表示¶

次は、ヘルプメッセージの表示です。

CLIツールを作るとき、--help オプションで使い方を説明することがあります。 この説明文をtextwrapで整形しておくと、コマンドラインでも読みやすく、ユーザー体験が向上します。

エラーメッセージの見やすさ向上¶

続いては、自身で関数を作った際のエラーメッセージです。

長いエラーメッセージはユーザーにとって負担です。 適切な幅で折り返してあげることで、ストレスを軽減できます。

shortenで省略するテクニック¶

ときには、全文を出力する必要がない場面もあります。 例えばログのタイトルや一部の説明文は、「ある程度で切ってしまっても意味が通じる」場合がありますよね。

そんなときに使えるのが shorten です。

text = "これはとても長い文章で、すべてを表示すると画面がごちゃごちゃしてしまいます。"
print(textwrap.shorten(text, width=20, placeholder="..."))

出力はこうなります。

これはとても長い文章…

これだけで「無駄に長すぎない、ちょうど良い出力」ができます。ちょっとした工夫ですが、ユーザーに優しい配慮です。

コマンドラインでの実用例¶

最後に、少し実践的な例を見てみましょう。 たとえば、ヘルプメッセージを整形して出力するスクリプトです。

import textwrap

help_text = """
このツールはファイルを整理するためのシンプルなユーティリティです。
オプションを指定することで、ディレクトリのスキャン、重複ファイルの削除、レポートの作成などが可能です。
"""

print("=== ヘルプ ===")
print(textwrap.fill(help_text, width=40))

実際の出力はこうなります。

=== ヘルプ ===
このツールはファイルを整理するための
シンプルなユーティリティです。オプ
ションを指定することで、ディレクト
リのスキャン、重複ファイルの削除、
レポートの作成などが可能です。

ただの文章が、まるで公式ツールの説明のように整然として見えませんか？

まとめ¶

Pythonのtextwrapモジュールは、一見すると地味な存在ですが、実際に使ってみると「なくてはならない」便利さを実感できます。

• 文章を自動的に折り返して読みやすくできる
• リストやエラーメッセージを整形してきれいに出せる
• 必要に応じて省略やインデントも簡単

エンジニア歴10年の私が断言できるのは、こうした「小さな工夫」がプロジェクト全体の品質やユーザー体験に直結するということです。

もし今までprint文でそのまま出力していたなら、ぜひtextwrapを試してみてください。きっと「これだよ、これ！」と感じるはずです。

ここまでお読みいただきありがとうございました！