Python
PR

Pythonのconfigparserの使い方|INIファイルの読み書きと型変換の落とし穴

Pythonのconfigparserの使い方|INIファイルの読み書きと型変換の落とし穴
hr
記事内に商品プロモーションを含む場合があります

「ポート番号やフォルダーの場所をコードに直接書かず、設定ファイルに分けたい」というとき、Python の標準ライブラリだけで手軽に使えるのが configparser です。[app] のような見出しと port = 8080 のような行で書く INI ファイルを読み書きできます。

書き方は簡単ですが、日本語が化ける・数字なのに足し算できない・% でエラーになる、といったつまずきがよくあります。この記事では、それぞれを実際に起こして原因と直し方を説明します(形式の選び方は「JSON・YAML・TOMLの違いと選び方」で比べています)。出力は Windows 11 の PowerShell 5.1 と Python 3.12.6 で実行したもので、仕様は公式ドキュメント(docs.python.org の configparser、英語原文)で確認しました。

INI ファイルの形:セクション・キー・値・コメント

この記事では、次の内容を config.ini という名前で、UTF-8(BOM なし)で保存して使います。

# アプリの設定ファイル
[DEFAULT]
timeout = 30
log_dir = logs

[app]
name = 在庫管理ツール
debug = yes
port = 8080
ratio = 0.75

; データベースの接続先
[database]
host = localhost
port = 5432
user = shop
timeout = 10

INI ファイルは、セクション([app] のような角かっこの見出し)と、その下に並ぶ キー = 値 の行でできています。Python からは、config["セクション名"]["キー名"] のように辞書と同じ形で取り出します。

config.ini の 4 行の役割。; で始まる行はコメント、[database] はセクション、host = localhost と port = 5432 はキーと値。Python で config にセクション名 database とキー名 port を続けて指定すると、その値が文字列の 5432 として取り出される
図 1:INI ファイルの各部分と、Python での取り出し方の対応

configparser の初期設定では、区切りは = か :(前後の空白は取り除かれる)、コメントは行頭の # か ;、セクション名は大文字・小文字を区別し、キー名は区別しません。INI には統一された仕様がなく、ソフトによって細かい決まりが違うので、ここでの説明は configparser の場合です。

基本の読み込み:ConfigParser と read

config.ini と同じフォルダーに、次の内容を read1.py として保存します。

import configparser

config = configparser.ConfigParser()
files = config.read("config.ini", encoding="utf-8")
print(files)
print(config.sections())
print(config["app"]["name"])
print(config["database"]["port"])
print(type(config["database"]["port"]))

PowerShell で、保存したフォルダーに移動してから実行します。

py read1.py
['config.ini']
['app', 'database']
在庫管理ツール
5432
<class 'str'>

read は読み込めたファイル名のリストを返します。sections() に DEFAULT は入りません(後で説明します)。そして port の 5432 は文字列です。

ファイルがなくてもエラーにならない

公式ドキュメントのとおり、read は開けなかったファイルを黙って飛ばします。config.read("nothing.ini", encoding="utf-8") は例外を出さず [] を返すだけで、その後の config["app"] で初めて KeyError になりました。戻り値を確かめましょう(後の「実例」参照)。

逆にこの性質を使うと、共通の設定に「その PC だけの設定(あれば)」を重ねられます。config.read(["base.ini", "local.ini", "missing.ini"], encoding="utf-8") は ['base.ini', 'local.ini'] を返し、両方にある debug は後から読んだ local.ini の値になりました。

encoding=”utf-8″ を付けないと、Windows では日本語が化ける

read の encoding を省略すると、open() と同じくその PC の既定の文字コードで読みます。日本語版 Windows の Python 3.12 では cp932(Shift_JIS を Windows 向けに広げたもの)です。UTF-8 の config.ini を encoding なしで読んでみます。

import configparser

config = configparser.ConfigParser()
config.read("config.ini")
print(config["app"]["name"])

トレースバックの最後に次のエラーが出ました。

UnicodeDecodeError: 'cp932' codec can't decode byte 0x86 in position 96: illegal multibyte sequence

UTF-8 のバイトを cp932 の表で読み、cp932 にない組み合わせに当たったためです。やっかいなのは、エラーにならずに化けるだけの場合もあることです。office = 東京 と書いた UTF-8 のファイルを encoding なしで読むと、例外は出ずに次の文字列が返りました。

譚ア莠ャ

「東京」の 6 バイトが、たまたま cp932 の文字として読めてしまった結果です。書かれた文字によって「エラー」と「静かな文字化け」が分かれるので、read には必ず encoding を書くと決めておきましょう。化けた文字列を見かけたら、文字化け復元ツールに貼ると、どの文字コードの組み合わせで化けたかを調べられます。

ファイルの保存形式指定する encoding合わないときの症状(実際に試した結果)
UTF-8(BOM なし)"utf-8"省略すると UnicodeDecodeError か文字化け
UTF-8(BOM 付き)"utf-8-sig"“utf-8” で読むと MissingSectionHeaderError(1 行目の先頭に見えない BOM が残る)
Shift_JIS(古い Windows ソフトの INI など)"cp932"“utf-8” で読むと UnicodeDecodeError: ‘utf-8’ codec can’t decode byte 0x83

BOM のときは、エラーメッセージに \ufeff が見えたら BOM が原因です。文字コードそのものの説明は「文字コードとは?」、open() の encoding については「Pythonのファイル読み書き」で詳しく書いています。

値はすべて文字列:getint・getfloat・getboolean と fallback

公式ドキュメントには「config parser は値の型を推測せず、常に文字列として保存する」とあります。数値や真偽値として使うときは、取り出すときに型を指定します(types_demo.py)。

import configparser

config = configparser.ConfigParser()
config.read("config.ini", encoding="utf-8")
app = config["app"]

print(app["port"] + "1")
print(app.getint("port") + 1)
print(app.getfloat("ratio"))
print(app.getboolean("debug"))
print(config.getint("database", "port"))
print(app.getint("workers", fallback=4))
print(app.get("theme", "light"))
80801
8081
0.75
True
5432
4
light

1 行目は文字列の連結なので 80801 です。getint・getfloat・getboolean を使うと int・float・bool で取り出せ、config.getint("セクション", "キー") の形でも同じです。config.ini にない workers・theme は、fallback= の値(セクションの get では 2 番目の引数)が返りました。

注意したいのは、config 全体の get では 3 番目の引数に既定値を書けない点です。config.get("app", "theme", "light") は TypeError: RawConfigParser.get() takes 3 positional arguments but 4 were given になりました。公式ドキュメントにも「parser.get(section, option, **kwargs) の 2 番目の引数は fallback ではない」と注意があります(セクションの get と形が違うため)。config 全体の get では fallback="light" とキーワードで書きます。

getboolean が True・False と判定する文字

12 種類の値を getboolean に通して確かめました。

INI に書いた値getboolean の結果
yes・on・1・true・True・YESTrue
no・off・0・falseFalse
y・enableValueError: Not a boolean: y(enable も同様)

公式ドキュメントのとおり、True になるのは 1・yes・true・on、False になるのは 0・no・false・off の 8 つだけで、大文字・小文字は区別しません。逆に、bool(app["debug"]) と書くと、"no" も "false" も空でない文字列なので True になってしまいます。真偽値は必ず getboolean で取り出しましょう。

複数の値(リスト)は自分で分ける

INI にはリストの書き方がありません。cc = sato@example.com, ito@example.com のように「,」でつないで書き、[s.strip() for s in mail["cc"].split(",")] で分けると ['sato@example.com', 'ito@example.com'] になりました。公式ドキュメントのとおり、2 行目以降を字下げすれば値を複数行に分けることもでき、その場合は改行(\n)を含む 1 つの文字列になるので、split() で分けます。

キーは大文字・小文字を区別しない(optionxform)

キー名は、読み込むときに小文字に変換されます。次の case.ini で確かめます。

[server]
Host = example.com
PORT = 443
import configparser

config = configparser.ConfigParser()
config.read("case.ini", encoding="utf-8")
server = config["server"]
print(server["host"], server["HOST"], server["Port"])
print(list(server))
example.com example.com 443
['host', 'port']

host・HOST・Port のどれで取り出しても同じ値が返り、一覧は小文字の ['host', 'port'] です。この config を write で書き出すと(後で説明します)、host = example.com・port = 443 とキー名が小文字に変わってしまいました。

この変換をするのが optionxform で、公式ドキュメントでも「既定では名前を小文字にする。そのため書き出すとキーはすべて小文字になる」とあります。read より前に config.optionxform = str とすると一覧は ['Host', 'PORT'] のまま残りましたが、今度は区別されるので get("host") は None になりました。

なお、セクション名は区別します。"app" in config は True ですが、"App" in config は False でした。

DEFAULT セクションは全セクションに引き継がれる

config.ini の先頭にある [DEFAULT] は特別なセクションで、公式ドキュメントでは「ほかのすべてのセクションに既定値を与える」と説明されています。確かめます(default_demo.py)。

import configparser

config = configparser.ConfigParser()
config.read("config.ini", encoding="utf-8")
print(config.sections())
print(config["app"]["timeout"])
print(config["database"]["timeout"])
print(config["database"]["log_dir"])
print(dict(config["app"]))
['app', 'database']
30
10
logs
{'name': '在庫管理ツール', 'debug': 'yes', 'port': '8080', 'ratio': '0.75', 'timeout': '30', 'log_dir': 'logs'}
DEFAULT セクションの timeout = 30 と log_dir = logs が、app と database の両方のセクションに引き継がれる。app では timeout が 30、log_dir が logs。database は自分で timeout = 10 を持つのでそちらが優先され、log_dir は DEFAULT の logs になる
図 2:DEFAULT セクションの値は、ほかの全セクションから見える

[app] には timeout がないのに DEFAULT の 30 が取れ、自分で timeout = 10 を持つ [database] はそちらが優先されます。sections() には DEFAULT が出ず、中身は defaults() で見ます。dict(config["app"]) に DEFAULT の値も混ざる点は、「キーを全部並べる」処理で思わぬキーが出てくる原因になります。また、DEFAULT の値は fallback より優先されます。config["app"].getint("timeout", fallback=99) は 99 ではなく 30 を返しました(公式ドキュメントにも「default values have precedence over fallback values」とあります)。

補間(%(name)s)と、% を含む値のエラー

ConfigParser には、値の中にほかのキーの値を埋め込む補間(interpolation)の機能が初めから入っています。書き方は %(キー名)s で、同じセクションか DEFAULT のキーを参照できます。次の interp.ini で試します。

[paths]
base = C:/work/shop
log = %(base)s/logs

[api]
url = https://example.com/search?q=%E6%9D%B1
password = abc%123

config["paths"]["log"] は C:/work/shop/logs になりました。base を書き換えるだけで、log も一緒に変わります。

問題は [api] のほうです。URL の %E6(日本語を URL に入れるときのパーセントエンコード)やパスワードの % も、補間の記号として解釈されます。url と password を取り出すと、それぞれ次の例外になりました(read は成功しています)。

configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%E6%9D%B1'
configparser.InterpolationSyntaxError: '%' must be followed by '%' or '(', found: '%123'

「% の後には % か ( が必要」という意味です。read の時点ではなく値を取り出したときに初めて例外になるので、その値を使う処理まで進んでから止まります。直し方は 3 つです。

直し方書き方向いている場面
% を 2 つ重ねるINI に password = abc%%123 と書く(取り出すと abc%123)補間も使いたい。% を含む値が少ない
補間を切るconfigparser.ConfigParser(interpolation=None)補間を使わない(多くの場合はこれで十分)
RawConfigParser を使うconfigparser.RawConfigParser()古いコードとの互換。補間が初めから無効

interpolation=None で読み直すと、url も password も書いたとおりに取れました(そのかわり %(base)s/logs も置き換えられません)。RawConfigParser は公式ドキュメントで「古い(legacy)版」とされているので、新しく書くなら interpolation=None が分かりやすいでしょう。値を入れるときも同じで、補間が有効なまま config["api"]["password"] = "abc%123" とすると ValueError: invalid interpolation syntax in 'abc%123' at position 3 になりました。

ExtendedInterpolation:${section:key} でほかのセクションを参照する

%(name)s では同じセクションと DEFAULT しか参照できません。ExtendedInterpolation に切り替えると、${セクション:キー} でほかのセクションの値を使えます。次の ext.ini を読みました。

[common]
base_dir = C:/work/shop

[app]
log_dir = ${common:base_dir}/logs
log_file = ${log_dir}/app.log
import configparser

config = configparser.ConfigParser(interpolation=configparser.ExtendedInterpolation())
config.read("ext.ini", encoding="utf-8")
print(config["app"]["log_dir"])
print(config["app"]["log_file"])

結果は C:/work/shop/logs と C:/work/shop/logs/app.log でした。${log_dir} のようにセクション名を省くと、同じセクションのキーを指します。こちらでは abc%123 はそのまま取れ、代わりに $ を書くときは $$ と重ねます(100$$ は 100$ になりました)。

書き込み:write でコメントが消える

値を変えて別のファイルに書き出します(write_demo.py)。write には、open() で開いたファイルを渡します。

import configparser

config = configparser.ConfigParser()
config.read("config.ini", encoding="utf-8")
config["app"]["port"] = "8081"
config["app"]["theme"] = "dark"
config["mail"] = {"host": "smtp.example.com", "port": "587"}

with open("config_new.ini", "w", encoding="utf-8") as f:
    config.write(f)

できた config_new.ini の中身です。

[DEFAULT]
timeout = 30
log_dir = logs

[app]
name = 在庫管理ツール
debug = yes
port = 8081
ratio = 0.75
theme = dark

[database]
host = localhost
port = 5432
user = shop
timeout = 10

[mail]
host = smtp.example.com
port = 587
  • コメントが消えた:2 つのコメント行がない。公式ドキュメントにも「元のファイルのコメントは、書き戻すときに保たれない」とある
  • 順番は保たれた:セクションもキーも読み込んだ順のまま。新しく足した theme はセクションの最後、[mail] はファイルの最後に入る
  • キー名は小文字になる(前の節)。Windows では改行が CRLF になった

人がコメントを書き込んだファイルを write で上書きすると、コメントはすべて失われます。人が編集するファイルとプログラムが書き換えるファイルは分け、上書きするなら先にバックアップを取りましょう。

値は文字列で入れる必要があります。config["api"]["port"] = 8080 のように数値を入れると、TypeError: option values must be strings になりました。str(8080) などで文字列にしてから入れます。

存在しないセクション・キーの例外:KeyError と NoSectionError の違い

ないものを取り出したとき、書き方によって例外の種類が変わります。config.ini にない [mail] セクションと、[app] にない color キーで確かめました。

書き方セクションがないキーがない
config["mail"]・config["app"]["color"](辞書の形)KeyError: ‘mail’KeyError: ‘color’
config.get("mail", "host")・config.get("app", "color")(getint なども同じ)NoSectionError: No section: ‘mail’NoOptionError: No option ‘color’ in section: ‘app’
get・getint などに fallback= を付けるfallback の値(例外にならない)fallback の値(例外にならない)

ここでつまずきやすいのが、NoSectionError と NoOptionError は KeyError の仲間(サブクラス)ではないことです。Python 3.12 で issubclass(configparser.NoSectionError, KeyError) を調べると False でした。つまり except KeyError: では config.get(...) の例外は捕まえられません。共通の親の configparser.Error を使うか、fallback を付けるのが簡単です。例外の書き方は「Pythonの例外処理入門」を参照してください。

実例:設定を読み込む関数をまとめる

ここまでの注意点(encoding・ファイルの有無・型の変換・既定値)を入れて、設定を読み込む関数を作ります。config.ini と同じフォルダーに settings.py として保存します。

import configparser
from pathlib import Path

CONFIG_PATH = Path(__file__).with_name("config.ini")


def load_settings():
    config = configparser.ConfigParser()
    if not config.read(CONFIG_PATH, encoding="utf-8"):
        raise FileNotFoundError(f"設定ファイルがありません: {CONFIG_PATH}")
    app = config["app"]
    return {
        "name": app.get("name", "名前なし"),
        "port": app.getint("port", fallback=8000),
        "debug": app.getboolean("debug", fallback=False),
        "timeout": app.getint("timeout"),
    }


print(load_settings())
{'name': '在庫管理ツール', 'port': 8080, 'debug': True, 'timeout': 30}
  • Path(__file__).with_name("config.ini") でスクリプトと同じフォルダーの config.ini を指す。"config.ini" とだけ書くと実行したときのフォルダーから探すので、別のフォルダーから実行すると read が [] を返した(詳しくは「Pythonのpathlibの使い方」)
  • read の戻り値が空ならすぐに分かるエラーにし、型の変換もこの関数の中で済ませる

パスワードや API キーを INI に平文で書かない

この記事では % の例として password を INI に書きましたが、実際のパスワードや API キーを設定ファイルに平文で書くのは避けましょう。config.ini はソースコードと一緒に Git に入れることが多く、一度コミットすると履歴に残り続けます。秘密の情報は環境変数や .env ファイルに分けて、Git に入れないのが基本です。やり方は「.envと環境変数で秘密情報を守る」で、漏れてしまったときの対処まで説明しています。

TOML(tomllib)との違い

Python 3.11 から、TOML を読む tomllib が標準ライブラリに入りました。configparser の公式ドキュメントでも「TOML は INI の改良版として設計された」形式として紹介されています。config.toml に port = 8080・debug = true と書いて読むと、port は最初から int(+ 1 で 8081)、debug は bool でした。

TOML は型を書き分けられ、入れ子も書けますが、tomllib は読み込み専用で書き出しはできません(ファイルは “rb” で開いて渡します)。新しく設定ファイルを作るなら TOML も候補になり、既存のソフトが INI を使っている、Python から書き戻したい、といった場合は configparser が手軽です。詳しい比較は「JSON・YAML・TOMLの違いと選び方」を参照してください。

よくある間違い・トラブル

行の途中に書いたコメントが値に入る

port = 8080 ; 本番は 80 と書くと、値は '8080 ; 本番は 80' になり、getint で ValueError: invalid literal for int() with base 10: '8080 ; 本番は 80' になりました。初期設定では行の途中のコメントは無効なので、コメントは別の行に書きます。どうしても使うなら ConfigParser(inline_comment_prefixes=(";",)) とすると '8080' になりましたが、8080;memo のように前に空白がない ; は値の一部のままでした。

MissingSectionHeaderError: File contains no section headers.

最初のセクションの見出しより前にキーを書くと出ます。すべてのキーを何かのセクションの下に書きます(Python 3.13 では、見出しなしを許す allow_unnamed_section という設定が追加されました)。BOM 付きの UTF-8 を “utf-8” で読んだときも同じエラーです。

DuplicateOptionError:同じキーを 2 回書いた

[app] に port = 8080 と PORT = 9090 を書くと、DuplicateOptionError: While reading from 'dup.ini' [line 3]: option 'port' in section 'app' already exists になりました。キーは小文字にそろえて比べるので、大文字・小文字だけが違うキーも重複です。

まとめ

  • read には必ず encoding=”utf-8″ を付ける(BOM 付きなら “utf-8-sig”)。ファイルがなくても例外にならないので戻り値を確かめる
  • 値はすべて文字列。getint・getfloat・getboolean と fallback で取り出す。真偽値に bool() は使わない
  • キーは小文字に変換される。DEFAULT の値は全セクションに引き継がれ、fallback より優先される
  • % を含む値は InterpolationSyntaxError になる。%% と書くか interpolation=None にする
  • write はコメントを消す。秘密の情報は INI ではなく環境変数・.env へ

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました