format（str、文字列）

このページでは豊富な例を用いてPythonのstrクラスのformatメソッドの使い方を学ぶことができます。

formatメソッドはstrクラス（文字列）のメソッドの1つです。

「呼び出し元の文字列の置換フィールド（波括弧{}部分）」を「formatメソッドの引数」で置換した文字列を戻り値として返します。置換フィールドは「引数の位置」、「引数のインデックス」、「キーワード引数の名前」など、様々な方法で指定できます。
また、置換フィールドには書式指定（桁数の指定など）を追加することもできます。

TL;DR

基本

# 波括弧{}が引数で与えた値に置換した文字列が返される
str1 = '{}---{}'
# 引数は可変長引数
formatted_str1 = str1.format('foo', 'bar')
print(formatted_str1)
==> foo---bar
# 元の値には変更なし
print(str1)
==> {}---{}




# 文字列ではない値も文字列値に変換されて処理される
str2 = '{}, {}'
formatted_str2 = str2.format(100, True)
print(formatted_str2)
==> 100, True




# 波括弧の数 < 引数の数
str3 = '{}::{}'
formatted_str3 = str3.format('string', 'integer', 'float')
print(formatted_str3)
==> string::integer




# 波括弧の数 > 引数の数
str4 = '{}::{}'
formatted_str4 = str4.format('string')
==> IndexError: Replacement index 1 out of range for positional args tuple




# 反復可能オブジェクトを展開して引数に指定する
formatted_str5 = 'I like {}, {} and {}.'.format(*['python', 'javascript', 'php'])
print(formatted_str5)
==> I like python, javascript and php.

インデックスの指定

# 波括弧{}の中に引数のインデックスを指定できる
str1 = '{0},{2},{1}'
formatted_str1 = str1.format(0, 100, 200)
print(formatted_str1)
==> 0,200,100




# 同じインデックスを複数指定することができる
str2 = '{0},{0},{2}'
formatted_str2 = str2.format('python', 'js', 'go')
print(formatted_str2)
==> python,python,go




# 複合オブジェクトを指定する場合
str3 = '{0[name]},{0[age]}---{1[name]},{1[age]}'
formatted_str3 = str3.format({'name': 'Olivia', 'age': 20}, {'name': 'Adah', 'age': 15})
print(formatted_str3)
==> Olivia,20---Adah,15




# インデックスを使用しない場合との混合パターン
str4 = '{},{0}'
formatted_str4 = str4.format('python', 'js')
==> ValueError: cannot switch from automatic field numbering to manual field specification




# 存在しないインデックスの指定
str5 = '{2}'
formatted_str5 = str5.format('python')
==> IndexError: Replacement index 2 out of range for positional args tuple

キーワードの指定

# キーワード引数（可変長引数）の名前を波括弧{}に指定する
str1 = '{py} and {js} are great.'
formatted_str1 = str1.format(py='Python', js='JavaScript')
print(formatted_str1)
==> Python and JavaScript are great.




# 辞書（複合オブジェクト）の指定
formatted_str2 = 'Score is {info[score]}.'.format(info={'score': 80})
print(formatted_str2)
==> Score is 80.




# 存在しないキーワードを指定した場合
formatted_str2_1 = '{foobar}'.format(name='Olivia')
==> KeyError: 'foobar'





class Person:
    def __init__(self):
        self.name = 'Joel'

# クラス（複合オブジェクト）の指定
person1 = Person()
formatted_str3 = 'A great engineer, {person.name}.'.format(person=person1)
print(formatted_str3)
==> A great engineer, Joel.




# 引数として辞書オブジェクトを展開する
dict1 = {'name': 'Alice', 'age': 55}
formatted_str4 = '{name}, {age}'.format(**dict1)
print(formatted_str4)
==> Alice, 55




# 位置引数とキーワード引数を組み合わせる.1
formatted_str5 = '{},{bool},{}'.format(0, 88, bool=False)
print(formatted_str5)
==> 0,False,88




# 位置引数とキーワード引数を組み合わせる.2
formatted_str6 = '{1},{country},{0}'.format('python', 100, country='Japan')
print(formatted_str6)
==> 100,Japan,python

関連情報：関数のキーワード引数使用方法

書式の指定

# 波括弧{}内のコロン:の後ろに書式を指定する

# 3桁区切り（カンマ,）
str1 = '{:,}'
formatted_str1 = str1.format(1234567)
print(formatted_str1)
==> 1,234,567




# 右寄せ（>が右寄せ、10は最小幅を設定）
str2 = '{:>10}'
formatted_str2 = str2.format('python')
print(formatted_str2)
==>     python




# 有効桁数（ピリオドと数値、fは浮動小数点数）
str3 = '{0:.3f}'
formatted_str3 = str3.format(3.14159265359)
print(formatted_str3)
==> 3.142




# %表記
str4 = '{rate:.2%}'
formatted_str4 = str4.format(rate=0.0425)
print(formatted_str4)
==> 4.25%




# 0埋め、0パディング
str5 = '{:0=5}'
formatted_str5 = str5.format(123)
print(formatted_str5)
==> 00123




# 指数表記（eが指数表記の指定）
str6 = '{:e}'
formatted_str6 = str6.format(12345)
print(formatted_str6)
==> 1.234500e+04

解説

基本

formatメソッドは「呼び出し元の文字列の置換フィールド」を「引数の値」で置換し、置換された文字列を戻り値として返します。
引数は「可変長の位置引数」と「可変長のキーワード引数」を取ることができ、この項では「可変長の位置引数」のパターンを紹介します。

置換フィールドは{}（波括弧）で指定し、与えた引数の順番でそれぞれの値に置換されていきます。引数が文字列（strオブジェクト）でない場合、その値の文字列値に変換して置換されます。

「置換フィールド」が「引数の数」より多い場合はIndexErrorが発生します。

str1 = '{}, the most fantastic language.'
formatted_str1 = str1.format('Python')
print(formatted_str1)
==> Python, the most fantastic language.




# 波括弧の数 < 引数の数
formatted_str2 = '{}___{}'.format('apple', 'orange', 'kiwi')
print(formatted_str2)
==> apple___orange




# 波括弧の数 > 引数の数
formatted_str3 = '{},{},{}'.format('apple')
==> IndexError: Replacement index 1 out of range for positional args tuple




# 反復可能オブジェクトを展開して引数に指定
formatted_str4 = '{}--{}--{}'.format(*[False, 0, 0.1])
print(formatted_str4)
==> False--0--0.1

インデックスの指定

呼び出し元の文字列の置換フィールドにはformatメソッドの引数のインデックスを指定することができます。
この指定方法を用いることにより、呼び出し元の文字列の中で複数回同じ引数の値を使用することも可能になります。

しかし、存在しないインデックスを指定した場合はIndexErrorが発生するので注意してください。

str1 = '{1} vs {0}'
formatted_str1 = str1.format('Python', 'JavaScript')
print(formatted_str1)
==> JavaScript vs Python




# 同インデックスを複数指定
str2 = '{0} {1} {0}'
formatted_str2 = str2.format('py', 'js')
print(formatted_str2)
==> py js py




# 複合オブジェクトを指定する場合
str3 = 'I am {0[name]}, she is {1[name]}'
formatted_str3 = str3.format({'name': 'Wang'}, {'name': 'Alex'})
print(formatted_str3)
==> I am Wang, she is Alex




# インデックスを使用しないパターンとの混合
formatted_str4 = '{0},{}'.format(100, 200)
==> ValueError: cannot switch from manual field specification to automatic field numbering




# 存在しないインデックスの指定
formatted_str5 = '{1}'.format(True)
==> IndexError: Replacement index 1 out of range for positional args tuple

キーワードの指定

formatメソッドの引数は可変長のキーワード引数として指定することもできます。

キーワード引数を指定した場合、置換フィールドにはキーワード引数で指定したキーワードを記述することができ、対応する値で置換された文字列が戻り値となります。

位置引数と一緒にキーワード引数を用いる場合は、位置引数をキーワード引数より前に指定することに注意してください。また、引数として存在しないキーワード引数のキーワードを置換フィールド内に用いるとKeyErrorが発生することにも注意してください。

str1 = 'I have a {tool}.'
formatted_str1 = str1.format(tool='pen')
print(formatted_str1)
==> I have a pen.




# 存在しないキーワードの指定
formatted_str1_1 = '{python}'.format(age=20)
==> KeyError: 'python'





class Student:
    def __init__(self, name):
        self.name = name

# クラス（複合オブジェクト）の指定
student1 = Student('John')
formatted_str2 = 'I am {student.name}.'.format(student=student1)
print(formatted_str2)
==> I am John.




# 辞書オブジェクトを引数で展開する
formatted_str3 = '{country}___{capital}'.format(**{'country': 'China', 'capital': 'Beijing'})
print(formatted_str3)
==> China___Beijing




# 位置引数とキーワード引数の組み合わせ
formatted_str4 = '{key}, {1}, {0}'.format(True, 99, key='valueeeee')
print(formatted_str4)
==> valueeeee, 99, True

関連情報：関数のキーワード引数使用方法

書式の指定

置換フィールドには、:（コロン）区切りで様々な書式を指定することができます。書式を設定することで有効桁数や指数表記の指定ができるようになり、フォーマットの幅が広がります。

インデックスやキーワードとともに使用する場合は、インデックス:書式指定、キーワード:書式指定のように指定して使用してください。

以下に書式指定オプションの一部を記載します。より詳しく知りたい場合、公式ドキュメントの書式指定ミニ言語仕様を参照してください。

オプション	説明
>	右寄せ
,（カンマ）	3桁区切り
e	指数表記
.[数値]	有効桁数
f	浮動小数点数
数値	最小幅
%	パーセント表記

# 3桁区切り（カンマ,）
str1 = '{:,}'
formatted_str1 = str1.format(1234567)
print(formatted_str1)
==> 1,234,567




# 右寄せ（>が右寄せ、5は最小幅を設定）
str2 = '{:>5}'
formatted_str2 = str2.format('A')
print(formatted_str2)
==>     A




# 有効桁数（ピリオドと数値、fは浮動小数点数）
str3 = '{0:.2f}'
formatted_str3 = str3.format(1.41421356237)
print(formatted_str3)
==> 1.41




# %表記
str4 = '{rate:.2%}'
formatted_str4 = str4.format(rate=0.54321)
print(formatted_str4)
==> 54.32%




# 0埋め、0パディング
str5 = '{:0=10}'
formatted_str5 = str5.format(123)
print(formatted_str5)
==> 0000000123




# 指数表記（Eが指数表記の指定）
str6 = '{:E}'
formatted_str6 = str6.format(10000)
print(formatted_str6)
==> 1.000000E+04

1次情報

formatメソッド strクラス - Pythonドキュメント

文字列のformat()メソッド - Pythonドキュメント

書式指定文字列の文法 - Pythonドキュメント

書式指定ミニ言語仕様 - Pythonドキュメント