(2026年10月29日 追記:記事どおりに再現できるよう、必要なコードと手順を追加しました)
前回(第9回)では、フォルダ内の図面PDFをまとめて処理する一括処理と、重い処理を別スレッドで動かす仕組みを作りました。
第10回は、図面を社外に出さない「ローカル完結モード」と、精度を優先する「外部AIモード」を設定画面で切り替えられるようにし、外部AIのAPIキーを安全に保存する仕組みをPythonで作ります。ポイントは次の3つです。
- 設定(モード・モデルID)は設定ファイルに、APIキーは設定ファイルに書かずOSの資格情報ストアに、と保存先を分ける
- 既定はローカル完結。ローカル完結のあいだは画面で「外部AI」を選べず、送信する関数の側でも止める(画面だけに頼らない)
- APIキーは画面・ログ・エラーメッセージに出さない。出ないことをpytestで確かめる
今回作る機能と完成イメージ
メイン画面の読み取り方式の横に「設定…」ボタンを追加し、次の項目を持つ設定画面を開けるようにします。
| 項目 | 内容 | 保存先 |
|---|---|---|
| 読み取りモード | ローカル完結(既定)/外部AIを許可 | 設定ファイル |
| モデルID | 外部AIのモデル。空欄なら既定 | 設定ファイル |
| APIキー | 「保存」「削除」のみ。保存済みのキーは表示しない | OSの資格情報ストア |
| 起動時の転記設定ファイル | 第8回のYAMLを起動時に読み込む | 設定ファイル |
第10回からは、設定で「外部AIを許可」にしない限り外部AIは使えません。一括処理(第9回)はこれまでどおりローカルだけで読み取ります。
仕組みの説明:設定とAPIキーは保存先を分ける
設定ファイルはユーザーごとの設定フォルダへ
設定は settings.json に保存します。保存先はアプリの置き場所ではなく利用者ごとの設定フォルダなので、exe(第11回)をどこに置いても保存でき、利用者ごとに設定が分かれます。
| OS | 保存先 |
|---|---|
| Windows | %APPDATA%\MadoriOCR\settings.json(例:C:\Users\<ユーザー名>\AppData\Roaming\MadoriOCR) |
| macOS | ~/Library/Application Support/MadoriOCR/settings.json |
| Linux | ~/.config/madori-ocr/settings.json(XDG_CONFIG_HOME があればその下) |
APIキーは「資格情報ストア」へ
APIキー(外部AIを呼ぶための合言葉。これがあれば誰でも発行元の料金で利用できる)を設定ファイルに平文で書くと、ファイルのコピーやバックアップと一緒に漏れます。そこで keyring ライブラリを使い、OSの資格情報ストア(パスワードなどを保管するOSの仕組み。Windowsでは「資格情報マネージャー」)に保存します。
keyringの公式ページでは、推奨のバックエンド(実際の保存先)として、macOSのキーチェーン、LinuxのSecret Service・KWallet、Windowsの「Windows Credential Locker」が挙げられています。バックエンドは環境に合わせて自動で選ばれ、set_keyring() で差し替えることもできます。
📰 出典:keyring(PyPI)
採用したのは keyring 25.7.0(2025年11月公開・MITライセンス)です。APIキーは「資格情報ストア → 環境変数 ANTHROPIC_API_KEY(第5回からの方法。開発用)」の順に探し、どちらにも無ければ送信確認より前に止めます。
「外部AIを許可」していなければ、2か所で止める
画面の選択肢を無効にするだけでは、画面の作り間違いや後から追加する別の入口から送信されるおそれがあります。そこで、送信する関数(app/core/ocr_ai.py)が設定を必ず受け取り、ローカル完結なら通信の前に例外にするようにしました。
| 場所 | ローカル完結のときの動き |
|---|---|
| メイン画面 | 「外部AI」の選択肢を無効化し、選択をローカルに戻す |
| 読み取り開始の処理 | 念のため再確認し、エラーを表示して止める |
| 送信する関数(コア処理) | 設定を確認し、通信・画像化の前に ExternalAiDisabledError |
実装
ファイル構成(第10回時点の差分)
app/
├ core/
│ ├ settings.py … 新規:設定ファイルの読み書き・検証、APIキーの保存・読み込み(keyring)
│ └ ocr_ai.py … 変更:送信する関数が設定を必ず受け取り、ローカル完結なら送信しない
└ ui/
├ settings_dialog.py … 新規:設定画面(モード・モデルID・APIキー・起動時の転記設定ファイル)
└ main_window.py … 変更:「設定...」ボタン、ローカル完結中は「外部AI」を無効化
tests/
├ conftest.py … 新規:全テストでkeyringをメモリ上の実装に差し替える
├ test_settings.py … 新規48件
└ test_ocr_ai.py … 変更:設定を渡す形に修正、ローカル完結で止まることなど7件を追加
requirements.txt … keyring==25.7.0 を追加
.env.example … 変更:APIキーの保存先が設定画面になったことを説明に追記
設定の型:APIキーの欄をそもそも持たない(app/core/settings.py)
設定は変更できないデータクラス(frozen=True)で持ちます。APIキーの項目を作らないことで、設定ファイルにキーが書かれる経路をなくしています。
# app/core/settings.py(抜粋)
MODE_LOCAL = "local"
MODE_EXTERNAL_AI = "external_ai"
@dataclass(frozen=True)
class AppSettings:
"""アプリの設定。APIキーは意図的に持たない(keyring に別に保存する)。"""
#: 読み取りモード(`MODE_LOCAL` / `MODE_EXTERNAL_AI`)
read_mode: str = MODE_LOCAL
#: 外部AIのモデルID。空なら `app/core/ocr_ai.py` の既定(DEFAULT_AI_MODEL)
ai_model: str = ""
#: 起動時に読み込む転記の設定ファイル(第8回のYAML)。空なら読み込まない
default_mapping_path: str = ""
@property
def external_ai_allowed(self) -> bool:
"""外部AIへの送信を許可しているか。"""
return self.read_mode == MODE_EXTERNAL_AI
設定ファイルが無ければ既定(ローカル完結)、壊れていればエラーを表示してローカル完結で起動するので、外部AIが勝手に有効になることはありません。モデルIDの欄にAPIキーらしい値(sk- で始まる)を貼り付けた場合も保存を拒否します。
保存先のフォルダをOSごとに決める
# app/core/settings.py(抜粋)
def default_settings_dir(
platform: str | None = None,
environ: Mapping[str, str] | None = None,
home: Path | None = None,
) -> Path:
plat = sys.platform if platform is None else platform
env = os.environ if environ is None else environ
base_home = Path.home() if home is None else home
if plat.startswith("win"):
appdata = env.get("APPDATA", "").strip()
base = Path(appdata) if appdata else base_home / "AppData" / "Roaming"
return base / "MadoriOCR"
if plat == "darwin":
return base_home / "Library" / "Application Support" / "MadoriOCR"
xdg = env.get("XDG_CONFIG_HOME", "").strip()
base = Path(xdg) if xdg else base_home / ".config"
return base / "madori-ocr"
引数で差し替えられるので、Linux上のpytestでもWindowsの保存先を確かめられます。
APIキーを保存する:エラーにキーを混ぜない
# app/core/settings.py(抜粋)
KEYRING_SERVICE = "madori-ocr"
KEYRING_USERNAME = "anthropic-api-key"
def save_api_key(text: str) -> None:
value = validate_api_key(text)
if not is_keyring_available():
raise ApiKeyStoreError(
"この環境ではOSの資格情報ストアが使えないため、APIキーを保存できません。"
f"開発時は環境変数 {ENV_API_KEY} を使ってください。"
)
try:
keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, value)
except Exception as exc:
raise ApiKeyStoreError(f"APIキーを資格情報ストアに保存できませんでした({type(exc).__name__})。") from None
logger.info("APIキーを資格情報ストアに保存しました(サービス名=%s)", KEYRING_SERVICE)
失敗時は元の例外を連結せず(from None)、種類名だけを伝えます。バックエンドによってはエラーメッセージに保存しようとした値を含める可能性があるためです。使えるバックエンドが無い環境(Linuxのサーバーなど)では、is_keyring_available() で見分けて保存ボタンを無効にし、環境変数だけを使います。
APIキーを読み込む:資格情報ストア → 環境変数
# app/core/settings.py(抜粋)
@dataclass(frozen=True)
class ResolvedApiKey:
"""読み込んだAPIキーと、その読み込み元。`repr()`・`str()` にキーの値を出さない。"""
value: str = field(repr=False)
source: str
def __str__(self) -> str:
return f"{MASKED_KEY}({self.source})"
def load_api_key(environ: Mapping[str, str] | None = None) -> ResolvedApiKey | None:
stored = _read_stored_api_key()
if stored is not None:
logger.debug("APIキーを資格情報ストアから読み込みました")
return ResolvedApiKey(stored, SOURCE_KEYRING)
env = os.environ if environ is None else environ
from_env = env.get(ENV_API_KEY, "").strip()
if from_env:
logger.debug("APIキーを環境変数 %s から読み込みました(開発用)", ENV_API_KEY)
return ResolvedApiKey(from_env, SOURCE_ENV)
return None
field(repr=False) にしておくと、デバッグ用に print(resolved) やログに %r で出しても、キーの値は表示されません。
送信する関数の側でも止める(app/core/ocr_ai.py)
ai_ocr_image() などに引数 settings を必須で追加しました。ローカル完結なら何も送らずに例外になります。
# app/core/ocr_ai.py(抜粋)
def ensure_external_ai_allowed(settings: AppSettings) -> None:
if not isinstance(settings, AppSettings):
raise TypeError("settings には AppSettings を渡してください。")
if not settings.external_ai_allowed:
raise ExternalAiDisabledError(
"ローカル完結モードのため、外部AIへは送信できません。外部AIを使う場合は、"
"「設定...」画面で読み取りモードを「外部AIを許可」に切り替えてください。"
)
def ai_ocr_image(
image: Image.Image,
*,
settings: AppSettings,
base_scale: float,
# (以下の引数は第5回と同じため省略)
) -> AiOcrResult:
ensure_external_ai_allowed(settings)
if client is None:
client = create_client(get_api_key())
used_model = model or resolve_model(settings=settings)
# (以下は第5回と同じ:画像の縮小 → 送信 → 応答JSONのパース)
モデルIDは「設定画面 → 環境変数 MADORI_OCR_AI_MODEL → 既定」の順です。APIのエラーメッセージは、APIキーらしい文字列を伏せ字にしてから表示します。
画面:ローカル完結のあいだは「外部AI」を選べない(app/ui/main_window.py)
# app/ui/main_window.py(抜粋)
def _apply_settings(self) -> None:
"""設定を画面に反映する。ローカル完結モードなら「外部AI」の選択肢を無効にし、ローカルに戻す。"""
if self.settings.external_ai_allowed:
self.ai_radio.configure(state="normal", text=AI_RADIO_TEXT_ALLOWED)
else:
self.ai_radio.configure(state="disabled", text=AI_RADIO_TEXT_DISABLED)
self.read_mode_var.set(READ_MODE_LOCAL)
送信時は、送信確認ダイアログ(第5回。許可モードでも毎回出ます)を出した時点の設定を、別スレッドの送信関数へ渡します。
設定画面:入力欄は伏せ字、保存済みのキーは見せない(app/ui/settings_dialog.py)
# app/ui/settings_dialog.py(抜粋)
# show= で入力した文字を伏せ字にする。保存後は入力欄を空に戻し、値を画面に残さない
self.api_key_entry = ttk.Entry(key_row, textvariable=self.api_key_var, show=_MASK_CHAR, width=30)
保存済みのキーは状態だけを表示し、末尾の数文字も出しません。キーを入力したまま「OK」を押すと、保存し忘れとして警告します。
この回で追加・変更するファイル
APIキーの保存にkeyringを追加します(Windowsでは、keyringが使う pywin32-ctypes も自動で入ります)。
requirements.txt に次の変更を加えます(+ が追加、- が削除)。
--- a/requirements.txt
+++ b/requirements.txt
@@ -30,3 +30,9 @@ anthropic==0.77.0
# 第7回〜:Excelテンプレート(既存の様式)を開き、決まったセルへ部屋名を書き込む(import openpyxl。
# 3.1.5は2024-06-28公開・MIT License)。書式・数式はそのまま残し、値だけを書き込んで別名で保存する。
openpyxl==3.1.5
+
+# 第10回〜:外部AIのAPIキーをOSの資格情報ストア(Windowsでは資格情報マネージャー)へ保存する
+# (import keyring。25.7.0は2025-11-16公開・MIT License)。APIキーは設定ファイル(settings.json)に
+# 書かない。Windowsでは依存の pywin32-ctypes が自動で入る。Linuxのサーバー等で使えるバックエンドが
+# 無い場合は保存できず、開発用の環境変数 ANTHROPIC_API_KEY だけを使う。
+keyring==25.7.0
pip install keyring==25.7.0
上で抜粋した設定のコア処理(app/core/settings.py)と、設定画面(app/ui/settings_dialog.py)の全体です。
app/core/settings.py を新しく作ります(全文)。
app/core/settings.py の全文(385行)
# app/core/settings.py
"""アプリの設定(読み取りモード・モデルID・既定の転記設定ファイル)とAPIキーの保存・読み込み(第10回)。
第5回では、外部AI(Claude API)のAPIキーを環境変数 `ANTHROPIC_API_KEY` から
読んでいた。開発者には手軽だが、配布先の担当者に「環境変数を設定してください」
とは頼みにくい。第10回では、次の2つを分けて保存する。
- **設定ファイル(settings.json)**:読み取りモード(ローカル完結/外部AIを許可)、
外部AIのモデルID、起動時に読み込む転記の設定ファイル(第8回のYAML)。
保存先はOSごとのユーザー用の設定フォルダ(Windowsなら `%APPDATA%\\MadoriOCR`)。
**APIキーはこのファイルに書かない**(フィールド自体を持たない)。
- **APIキー**:keyring ライブラリで、OSの資格情報ストア(Windowsでは資格情報
マネージャー)に保存する。読み込みは「keyring → 環境変数 `ANTHROPIC_API_KEY`
(開発用)」の順。
既定(設定ファイルが無いとき)は **ローカル完結モード**。外部AIは、利用者が
設定画面で「外部AIを許可」に切り替えた場合だけ使える。画面の選択肢を無効に
するだけでなく、`app/core/ocr_ai.py` 側でもこの設定を確認してから送信する
(UIの作り間違いがあっても図面が送られないようにするため)。
APIキーの値は、ログ・例外メッセージ・`repr()` のどこにも出さない。
tkinterなどGUIライブラリはimportしない(pytestで検証するコア処理)。
"""
from __future__ import annotations
import json
import logging
import os
import re
import sys
import tempfile
from collections.abc import Mapping
from dataclasses import dataclass, field, replace
from pathlib import Path
import keyring
import keyring.errors
from keyring.backends import fail as keyring_fail
logger = logging.getLogger(__name__)
#: 読み取りモード。既定はローカル完結(図面を社外に送らない)
MODE_LOCAL = "local"
MODE_EXTERNAL_AI = "external_ai"
READ_MODES = (MODE_LOCAL, MODE_EXTERNAL_AI)
#: 設定ファイルの形式のバージョン(将来項目を増やしたときの読み替え用)
SETTINGS_VERSION = 1
SETTINGS_FILE_NAME = "settings.json"
#: 設定ファイルの大きさの上限(壊れた・想定外のファイルを読み込まないため)
MAX_SETTINGS_BYTES = 64 * 1024
#: keyring に保存するときの「サービス名」と「ユーザー名」。
#: Windowsの資格情報マネージャーでは、サービス名が「汎用資格情報」の名前として使われる
#: (keyring 25.7.0 の `keyring/backends/Windows.py` の実装による)。
KEYRING_SERVICE = "madori-ocr"
KEYRING_USERNAME = "anthropic-api-key"
#: 開発用に、keyring に保存が無いとき読む環境変数(第5回から)
ENV_API_KEY = "ANTHROPIC_API_KEY"
#: APIキーをどこから読んだか
SOURCE_KEYRING = "keyring"
SOURCE_ENV = "env"
#: 画面にAPIキーの代わりに出す伏せ字(長さも分からないよう固定の長さにする)
MASKED_KEY = "●" * 12
#: APIキーとして受け付ける長さの上限(貼り付け間違いで長文が入るのを防ぐ)
MAX_API_KEY_LENGTH = 512
#: モデルIDとして受け付ける文字(英数字と . _ : @ / -)。空欄は「既定のモデル」
_MODEL_ID_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:@/-]{0,99}")
#: AnthropicのAPIキーらしき文字列(ログや画面に出す前に伏せるため)
_API_KEY_LIKE_PATTERN = re.compile(r"sk-ant-[A-Za-z0-9_-]+")
class SettingsError(RuntimeError):
"""設定ファイルの読み込み・保存、設定値の検証に失敗した場合の例外。"""
class ApiKeyStoreError(RuntimeError):
"""APIキーの保存・削除に失敗した場合の例外(メッセージにキーの値は含めない)。"""
@dataclass(frozen=True)
class AppSettings:
"""アプリの設定。APIキーは意図的に持たない(keyring に別に保存する)。"""
#: 読み取りモード(`MODE_LOCAL` / `MODE_EXTERNAL_AI`)
read_mode: str = MODE_LOCAL
#: 外部AIのモデルID。空なら `app/core/ocr_ai.py` の既定(DEFAULT_AI_MODEL)
ai_model: str = ""
#: 起動時に読み込む転記の設定ファイル(第8回のYAML)。空なら読み込まない
default_mapping_path: str = ""
@property
def external_ai_allowed(self) -> bool:
"""外部AIへの送信を許可しているか。"""
return self.read_mode == MODE_EXTERNAL_AI
# --- 保存先 --------------------------------------------------------------------
def default_settings_dir(
platform: str | None = None,
environ: Mapping[str, str] | None = None,
home: Path | None = None,
) -> Path:
"""OSごとのユーザー用の設定フォルダを返す(作成はしない)。
- Windows:`%APPDATA%\\MadoriOCR`(例:C:\\Users\\<ユーザー名>\\AppData\\Roaming\\MadoriOCR)
- macOS:`~/Library/Application Support/MadoriOCR`
- Linuxなど:`$XDG_CONFIG_HOME/madori-ocr`(未設定なら `~/.config/madori-ocr`)
`platform`・`environ`・`home` はテストで差し替えるための引数。
"""
plat = sys.platform if platform is None else platform
env = os.environ if environ is None else environ
base_home = Path.home() if home is None else home
if plat.startswith("win"):
appdata = env.get("APPDATA", "").strip()
base = Path(appdata) if appdata else base_home / "AppData" / "Roaming"
return base / "MadoriOCR"
if plat == "darwin":
return base_home / "Library" / "Application Support" / "MadoriOCR"
xdg = env.get("XDG_CONFIG_HOME", "").strip()
base = Path(xdg) if xdg else base_home / ".config"
return base / "madori-ocr"
def default_settings_path() -> Path:
"""既定の設定ファイルのパス(`default_settings_dir()` の下の settings.json)。"""
return default_settings_dir() / SETTINGS_FILE_NAME
# --- 設定値の検証 ----------------------------------------------------------------
def validate_model_id(text: str) -> str:
"""モデルIDの入力を検証して前後の空白を除いた値を返す。空欄は「既定のモデル」。
APIキーをモデルIDの欄に貼り付けてしまうと設定ファイルに平文で残るため、
APIキーらしい値(sk- で始まる)は受け付けない。エラーメッセージには入力値を含めない。
"""
value = text.strip()
if not value:
return ""
if value.lower().startswith("sk-"):
raise SettingsError(
"モデルIDの欄にAPIキーのような値が入力されています。APIキーは「APIキー」欄で保存してください"
"(モデルIDの欄の値は設定ファイルに平文で保存されます)。"
)
if not _MODEL_ID_PATTERN.fullmatch(value):
raise SettingsError(
"モデルIDに使えない文字が含まれているか、長すぎます(英数字と . _ : @ / - の100文字以内)。"
)
return value
def validate_settings(settings: AppSettings) -> AppSettings:
"""設定値を検証し、正規化した `AppSettings` を返す。"""
if settings.read_mode not in READ_MODES:
raise SettingsError(f"読み取りモードの値が不正です({', '.join(READ_MODES)} のいずれか)。")
return replace(
settings,
ai_model=validate_model_id(settings.ai_model),
default_mapping_path=settings.default_mapping_path.strip(),
)
# --- 設定ファイルの読み書き --------------------------------------------------------
def load_settings(path: str | Path | None = None) -> AppSettings:
"""設定ファイルを読み込む。ファイルが無ければ既定(ローカル完結モード)を返す。
壊れている(JSONでない・値が不正)場合は `SettingsError`。呼び出し側(画面)は
エラーを表示したうえで既定の設定で起動する(外部AIが勝手に有効になることはない)。
知らない項目は無視する(新しい版で保存した設定を古い版で開いた場合のため)。
"""
settings_path = default_settings_path() if path is None else Path(path)
if not settings_path.exists():
return AppSettings()
try:
raw = settings_path.read_bytes()
except OSError as exc:
raise SettingsError(f"設定ファイルを読み込めませんでした: {settings_path}({exc.strerror})") from None
if len(raw) > MAX_SETTINGS_BYTES:
raise SettingsError(f"設定ファイルが大きすぎます({MAX_SETTINGS_BYTES // 1024}KBまで): {settings_path}")
try:
data = json.loads(raw.decode("utf-8-sig"))
except UnicodeDecodeError:
raise SettingsError(f"設定ファイルがUTF-8ではありません: {settings_path}") from None
except json.JSONDecodeError as exc:
raise SettingsError(f"設定ファイルの形式が壊れています({exc.lineno}行目): {settings_path}") from None
if not isinstance(data, dict):
raise SettingsError(f"設定ファイルの形式が不正です(JSONのオブジェクトではありません): {settings_path}")
if data.get("version", SETTINGS_VERSION) != SETTINGS_VERSION:
raise SettingsError(f"対応していない設定ファイルの版です(version: {SETTINGS_VERSION} のみ対応)。")
values: dict[str, str] = {}
for name in ("read_mode", "ai_model", "default_mapping_path"):
if name not in data:
continue
if not isinstance(data[name], str):
raise SettingsError(f"設定ファイルの「{name}」は文字列で指定してください: {settings_path}")
values[name] = data[name]
return validate_settings(AppSettings(**values))
def save_settings(settings: AppSettings, path: str | Path | None = None) -> Path:
"""設定をJSONで保存し、保存したパスを返す。保存先のフォルダが無ければ作る。
一時ファイルに書いてから置き換えるため、保存中に落ちても設定ファイルが
中途半端な内容で残らない。APIキーは `AppSettings` に無いので書かれない。
"""
checked = validate_settings(settings)
settings_path = default_settings_path() if path is None else Path(path)
data = {
"version": SETTINGS_VERSION,
"read_mode": checked.read_mode,
"ai_model": checked.ai_model,
"default_mapping_path": checked.default_mapping_path,
}
text = json.dumps(data, ensure_ascii=False, indent=2) + "\n"
try:
settings_path.parent.mkdir(parents=True, exist_ok=True)
fd, tmp_name = tempfile.mkstemp(prefix="~settings", suffix=".tmp", dir=settings_path.parent)
try:
with os.fdopen(fd, "w", encoding="utf-8") as tmp:
tmp.write(text)
os.replace(tmp_name, settings_path)
except BaseException:
Path(tmp_name).unlink(missing_ok=True)
raise
except OSError as exc:
raise SettingsError(f"設定ファイルを保存できませんでした: {settings_path}({exc.strerror})") from None
logger.info("設定を保存しました(読み取りモード=%s): %s", checked.read_mode, settings_path)
return settings_path
# --- APIキー(keyring) -------------------------------------------------------------
@dataclass(frozen=True)
class ResolvedApiKey:
"""読み込んだAPIキーと、その読み込み元。`repr()`・`str()` にキーの値を出さない。"""
value: str = field(repr=False)
#: `SOURCE_KEYRING`(資格情報ストア)または `SOURCE_ENV`(環境変数・開発用)
source: str
def __str__(self) -> str:
return f"{MASKED_KEY}({self.source})"
@dataclass(frozen=True)
class ApiKeyStatus:
"""設定画面に出すAPIキーの状態(キーの値そのものは持たない)。"""
#: 資格情報ストアにAPIキーが保存されているか
stored: bool
#: 開発用の環境変数 ANTHROPIC_API_KEY が設定されているか
env_set: bool
#: この環境で資格情報ストアが使えるか(Linuxのサーバー等では使えないことが多い)
store_available: bool
def is_keyring_available() -> bool:
"""資格情報ストア(keyringのバックエンド)が使えるか。
使えるバックエンドが無い環境では、keyring は `keyring.backends.fail.Keyring`
(呼ぶと必ず `NoKeyringError` になる)を返す。
"""
try:
return not isinstance(keyring.get_keyring(), keyring_fail.Keyring)
except Exception: # バックエンドの初期化そのものに失敗した場合も「使えない」とする
return False
def validate_api_key(text: str) -> str:
"""保存する前にAPIキーの入力を検証する。エラーメッセージには入力値を一切含めない。"""
value = text.strip()
if not value:
raise ApiKeyStoreError("APIキーが入力されていません。")
if len(value) > MAX_API_KEY_LENGTH:
raise ApiKeyStoreError(f"APIキーが長すぎます({MAX_API_KEY_LENGTH}文字まで)。貼り付けた内容を確認してください。")
if any(ch.isspace() or not ch.isprintable() for ch in value):
raise ApiKeyStoreError("APIキーに空白・改行などの使えない文字が含まれています。貼り付けた内容を確認してください。")
return value
def save_api_key(text: str) -> None:
"""APIキーをOSの資格情報ストアに保存する(設定ファイルには書かない)。
失敗したときの例外は `ApiKeyStoreError` にまとめ、元の例外は連結しない
(`from None`)。バックエンドによってはエラーメッセージに保存しようとした
値を含める可能性があり、それがログやエラー画面に出ないようにするため。
"""
value = validate_api_key(text)
if not is_keyring_available():
raise ApiKeyStoreError(
"この環境ではOSの資格情報ストアが使えないため、APIキーを保存できません。"
f"開発時は環境変数 {ENV_API_KEY} を使ってください。"
)
try:
keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, value)
except Exception as exc:
raise ApiKeyStoreError(f"APIキーを資格情報ストアに保存できませんでした({type(exc).__name__})。") from None
logger.info("APIキーを資格情報ストアに保存しました(サービス名=%s)", KEYRING_SERVICE)
def delete_api_key() -> bool:
"""資格情報ストアからAPIキーを削除する。保存されていなければ `False`。"""
if not is_keyring_available():
return False
try:
keyring.delete_password(KEYRING_SERVICE, KEYRING_USERNAME)
except keyring.errors.PasswordDeleteError:
return False # 保存されていない
except Exception as exc:
raise ApiKeyStoreError(f"APIキーを資格情報ストアから削除できませんでした({type(exc).__name__})。") from None
logger.info("APIキーを資格情報ストアから削除しました(サービス名=%s)", KEYRING_SERVICE)
return True
def _read_stored_api_key() -> str | None:
if not is_keyring_available():
return None
try:
stored = keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME)
except Exception as exc: # 資格情報ストアが一時的に使えない等。環境変数へ進む
logger.warning("資格情報ストアからAPIキーを読み込めませんでした(%s)", type(exc).__name__)
return None
if stored is None or not stored.strip():
return None
return stored.strip()
def load_api_key(environ: Mapping[str, str] | None = None) -> ResolvedApiKey | None:
"""APIキーを「資格情報ストア → 環境変数 ANTHROPIC_API_KEY(開発用)」の順に探す。
どちらにも無ければ `None`。見つかったキーの値はログに出さず、読み込み元だけを記録する。
"""
stored = _read_stored_api_key()
if stored is not None:
logger.debug("APIキーを資格情報ストアから読み込みました")
return ResolvedApiKey(stored, SOURCE_KEYRING)
env = os.environ if environ is None else environ
from_env = env.get(ENV_API_KEY, "").strip()
if from_env:
logger.debug("APIキーを環境変数 %s から読み込みました(開発用)", ENV_API_KEY)
return ResolvedApiKey(from_env, SOURCE_ENV)
return None
def api_key_status(environ: Mapping[str, str] | None = None) -> ApiKeyStatus:
"""設定画面に表示するAPIキーの状態を調べる。"""
env = os.environ if environ is None else environ
return ApiKeyStatus(
stored=_read_stored_api_key() is not None,
env_set=bool(env.get(ENV_API_KEY, "").strip()),
store_available=is_keyring_available(),
)
def describe_api_key_status(status: ApiKeyStatus) -> str:
"""APIキーの状態を画面用の文章にする(キーの値・一部の文字も出さない)。"""
if status.stored:
return f"保存済み({MASKED_KEY})。キーは表示しません"
if status.env_set:
return f"資格情報ストアには未保存。開発用の環境変数 {ENV_API_KEY} のキーを使います"
if not status.store_available:
return f"未設定(この環境では資格情報ストアを使えません。開発時は環境変数 {ENV_API_KEY})"
return "未設定"
def redact_secrets(text: str, secret: str | None = None) -> str:
"""文字列からAPIキー(とそれらしい文字列)を伏せ字にする。エラー表示・ログの直前に使う。"""
if secret:
text = text.replace(secret, MASKED_KEY)
return _API_KEY_LIKE_PATTERN.sub("sk-ant-" + MASKED_KEY, text)
app/ui/settings_dialog.py を新しく作ります(全文)。
app/ui/settings_dialog.py の全文(225行)
# app/ui/settings_dialog.py
"""設定画面(第10回)。
- 読み取りモード:「ローカル完結(既定)」か「外部AIを許可」か
- 外部AIのモデルID(空欄なら既定のモデル)
- APIキー:OSの資格情報ストア(Windowsでは資格情報マネージャー)への保存・削除。
入力欄は伏せ字で、保存済みのキーは画面に一切表示しない(状態だけを出す)
- 起動時に読み込む転記の設定ファイル(第8回のYAML)
「OK」で `AppSettings` を返し、保存は呼び出し側(メイン画面)が `save_settings()` で行う。
APIキーの「保存」「削除」は資格情報ストアへすぐに反映する(OK/キャンセルとは別)。
設定値の検証・保存・keyringの操作は `app/core/settings.py`(GUI非依存)にあり、この画面は
それを呼ぶだけの薄い層にしている。
"""
from __future__ import annotations
import tkinter as tk
from pathlib import Path
from tkinter import filedialog, messagebox, ttk
from app.core.ocr_ai import DEFAULT_AI_MODEL
from app.core.settings import (
MODE_EXTERNAL_AI,
MODE_LOCAL,
ApiKeyStoreError,
AppSettings,
SettingsError,
api_key_status,
delete_api_key,
describe_api_key_status,
save_api_key,
validate_model_id,
validate_settings,
)
DIALOG_TITLE = "設定"
MAPPING_FILETYPES = [("転記の設定ファイル(YAML)", "*.yaml *.yml")]
#: 入力欄に表示する伏せ字の文字
_MASK_CHAR = "●"
class SettingsDialog(tk.Toplevel):
"""設定画面。`result` に「OK」で確定した `AppSettings`(キャンセルなら `None`)が入る。"""
def __init__(self, master: tk.Misc, *, settings: AppSettings, settings_path: Path) -> None:
super().__init__(master)
self.title(DIALOG_TITLE)
self.resizable(False, False)
self.result: AppSettings | None = None
self._settings_path = settings_path
self.mode_var = tk.StringVar(value=settings.read_mode)
self.model_var = tk.StringVar(value=settings.ai_model)
self.api_key_var = tk.StringVar(value="")
self.key_status_var = tk.StringVar(value="")
self.mapping_var = tk.StringVar(value=settings.default_mapping_path)
self._build_widgets()
self._refresh_key_status()
self.protocol("WM_DELETE_WINDOW", self._on_cancel)
self.bind("<Escape>", lambda _e: self._on_cancel())
def _build_widgets(self) -> None:
body = ttk.Frame(self, padding=16)
body.pack(fill="both", expand=True)
body.columnconfigure(0, weight=1)
mode = ttk.LabelFrame(body, text="読み取りモード", padding=10)
mode.grid(row=0, column=0, sticky="ew")
ttk.Radiobutton(
mode,
text="ローカル完結(既定):図面を社外へ送信しません。メイン画面の「外部AI」は選べません",
variable=self.mode_var,
value=MODE_LOCAL,
).pack(anchor="w")
ttk.Radiobutton(
mode,
text="外部AIを許可:メイン画面で「外部AI」を選び、送信を確認したときだけ図面画像を送信します",
variable=self.mode_var,
value=MODE_EXTERNAL_AI,
).pack(anchor="w", pady=(4, 0))
ai = ttk.LabelFrame(body, text="外部AI(Anthropic Claude API)", padding=10)
ai.grid(row=1, column=0, sticky="ew", pady=(12, 0))
ai.columnconfigure(1, weight=1)
ttk.Label(ai, text="モデルID:").grid(row=0, column=0, sticky="w")
ttk.Entry(ai, textvariable=self.model_var, width=40).grid(row=0, column=1, sticky="ew")
ttk.Label(ai, text=f"空欄なら既定({DEFAULT_AI_MODEL})", foreground="#555555").grid(
row=1, column=1, sticky="w", pady=(0, 8)
)
ttk.Label(ai, text="APIキーの状態:").grid(row=2, column=0, sticky="w")
self.key_status_label = ttk.Label(ai, textvariable=self.key_status_var, foreground="#1f5fbf")
self.key_status_label.grid(row=2, column=1, sticky="w")
ttk.Label(ai, text="新しいAPIキー:").grid(row=3, column=0, sticky="w", pady=(6, 0))
key_row = ttk.Frame(ai)
key_row.grid(row=3, column=1, sticky="ew", pady=(6, 0))
# show= で入力した文字を伏せ字にする。保存後は入力欄を空に戻し、値を画面に残さない
self.api_key_entry = ttk.Entry(key_row, textvariable=self.api_key_var, show=_MASK_CHAR, width=30)
self.api_key_entry.pack(side="left", fill="x", expand=True)
self.save_key_button = ttk.Button(key_row, text="保存", command=self._on_save_key)
self.save_key_button.pack(side="left", padx=(6, 0))
self.delete_key_button = ttk.Button(key_row, text="削除", command=self._on_delete_key)
self.delete_key_button.pack(side="left", padx=(4, 0))
ttk.Label(
ai,
text=(
"APIキーは設定ファイルに書かず、OSの資格情報ストア(Windowsでは資格情報マネージャー)に\n"
"保存します。「保存」「削除」はすぐに反映されます(OK・キャンセルとは別)。"
),
foreground="#555555",
justify="left",
).grid(row=4, column=0, columnspan=2, sticky="w", pady=(6, 0))
mapping = ttk.LabelFrame(body, text="起動時に読み込む転記の設定ファイル(任意・YAML)", padding=10)
mapping.grid(row=2, column=0, sticky="ew", pady=(12, 0))
mapping.columnconfigure(0, weight=1)
ttk.Label(mapping, textvariable=self.mapping_var, foreground="#555555", width=60).grid(
row=0, column=0, sticky="w"
)
mapping_buttons = ttk.Frame(mapping)
mapping_buttons.grid(row=0, column=1, sticky="e")
ttk.Button(mapping_buttons, text="選ぶ...", command=self._on_choose_mapping).pack(side="left")
ttk.Button(mapping_buttons, text="外す", command=lambda: self.mapping_var.set("")).pack(
side="left", padx=(4, 0)
)
ttk.Label(body, text=f"設定の保存先:{self._settings_path}", foreground="#555555").grid(
row=3, column=0, sticky="w", pady=(12, 0)
)
buttons = ttk.Frame(body)
buttons.grid(row=4, column=0, sticky="e", pady=(12, 0))
ttk.Button(buttons, text="キャンセル", command=self._on_cancel).pack(side="right")
ttk.Button(buttons, text="OK", command=self._on_ok).pack(side="right", padx=(0, 6))
# --- APIキー -----------------------------------------------------------------
def _refresh_key_status(self) -> None:
status = api_key_status()
self.key_status_var.set(describe_api_key_status(status))
self.key_status_label.configure(foreground="#1f5fbf" if status.stored or status.env_set else "#b00020")
store_state = "normal" if status.store_available else "disabled"
self.save_key_button.configure(state=store_state)
self.delete_key_button.configure(state="normal" if status.stored else "disabled")
def _on_save_key(self) -> None:
try:
save_api_key(self.api_key_var.get())
except ApiKeyStoreError as exc:
messagebox.showerror("APIキーを保存できません", str(exc), parent=self)
return
finally:
self.api_key_var.set("") # 成功・失敗どちらでも、入力した値を画面に残さない
self._refresh_key_status()
messagebox.showinfo("APIキーを保存しました", "APIキーを資格情報ストアに保存しました。", parent=self)
def _on_delete_key(self) -> None:
if not messagebox.askyesno(
"APIキーを削除します",
"資格情報ストアに保存したAPIキーを削除しますか?",
detail="削除すると、外部AIを使うにはAPIキーの保存が再び必要になります。",
icon="warning",
default="no",
parent=self,
):
return
try:
delete_api_key()
except ApiKeyStoreError as exc:
messagebox.showerror("APIキーを削除できません", str(exc), parent=self)
self._refresh_key_status()
# --- その他 -------------------------------------------------------------------
def _on_choose_mapping(self) -> None:
path = filedialog.askopenfilename(title="転記の設定ファイルを選択", filetypes=MAPPING_FILETYPES, parent=self)
if path:
self.mapping_var.set(path)
def _collect(self) -> AppSettings:
"""画面の入力から `AppSettings` を作って検証する(不正なら `SettingsError`)。"""
model = validate_model_id(self.model_var.get())
return validate_settings(
AppSettings(
read_mode=self.mode_var.get(),
ai_model=model,
default_mapping_path=self.mapping_var.get(),
)
)
def _on_ok(self) -> None:
if self.api_key_var.get().strip():
# 入力したまま「保存」を押し忘れた場合。黙って捨ても保存もせず、確認する
messagebox.showwarning(
"APIキーが保存されていません",
"入力したAPIキーはまだ保存されていません。「保存」を押すか、入力欄を空にしてください。",
parent=self,
)
return
try:
self.result = self._collect()
except SettingsError as exc:
messagebox.showerror("設定のエラー", str(exc), parent=self)
return
self.destroy()
def _on_cancel(self) -> None:
self.api_key_var.set("")
self.result = None
self.destroy()
def open_settings_dialog(master: tk.Misc, *, settings: AppSettings, settings_path: Path) -> AppSettings | None:
"""設定画面をモーダルで開き、「OK」なら新しい `AppSettings`、キャンセルなら `None` を返す。"""
dialog = SettingsDialog(master, settings=settings, settings_path=settings_path)
dialog.transient(master.winfo_toplevel())
dialog.wait_visibility()
dialog.grab_set()
dialog.focus_set()
master.wait_window(dialog)
return dialog.result
外部AIの処理は、送信する関数が設定を必ず受け取り、ローカル完結なら送信の前に止めるようにします。APIキーの環境変数名 ENV_API_KEY は settings.py へ移します。
app/core/ocr_ai.py に次の変更を加えます(+ が追加、- が削除)。
app/core/ocr_ai.py の差分(195行)
--- a/app/core/ocr_ai.py
+++ b/app/core/ocr_ai.py
@@ -19,8 +19,14 @@ AIは図面全体の文脈(部屋の枠の中央にある語か、寸法線の
前後に説明文やコードフェンス(```json ... ```)が付くこともあるため、
`parse_ai_response()` で頑健に取り出し、形式が崩れていれば
`AiResponseFormatError` にする。
-- **APIキーと利用料金が必要**。APIキーはコード・設定ファイルに書かず、
- 環境変数 `ANTHROPIC_API_KEY` から読む(保存方法は第10回で見直す)。
+- **APIキーと利用料金が必要**。APIキーはコード・設定ファイルに書かない。
+ 第10回から、設定画面で保存したOSの資格情報ストア(Windowsでは資格情報
+ マネージャー。keyring経由)→ 環境変数 `ANTHROPIC_API_KEY`(開発用)の順に
+ 読む(`app/core/settings.py`)。
+- **第10回から、設定が「外部AIを許可」でなければ送信しない**。画面で選択肢を
+ 無効にしているだけでなく、送信する関数(`ai_ocr_image()` など)が設定
+ (`AppSettings`)を必ず受け取り、ローカル完結モードなら通信の前に
+ `ExternalAiDisabledError` にする。
戻り値は第2回・第4回と同じ `ExtractedWord`(文字列・座標・文字の高さ・
ページ番号)にそろえ、プレビューのハイライト表示や部屋名辞書との照合を
@@ -48,16 +54,17 @@ from PIL import Image
from app.core.ocr_local import image_from_ppm_bytes
from app.core.pdf_loader import DEFAULT_DPI, PdfDocument, RenderedPage
+from app.core.settings import ENV_API_KEY, AppSettings, load_api_key, redact_secrets
from app.core.text_extractor import ExtractedWord
-#: APIキーを読む環境変数名(値はコード・設定ファイルに書かない)
-ENV_API_KEY = "ANTHROPIC_API_KEY"
+# APIキーの環境変数名 ENV_API_KEY は第10回で settings.py へ移した(第5回と同じ名前で import できる)
+
#: 使用するモデルIDを差し替えるための環境変数名
ENV_MODEL = "MADORI_OCR_AI_MODEL"
#: 既定のモデルID(執筆時点。画像入力に対応したClaude Haiku 4.5のスナップショットID)。
#: モデルは入れ替わりが速いため、公式ドキュメントのモデル一覧で最新を確認し、
-#: 必要なら環境変数 `MADORI_OCR_AI_MODEL` で差し替える。
+#: 必要なら設定画面のモデルID(開発時は環境変数 `MADORI_OCR_AI_MODEL`)で差し替える。
DEFAULT_AI_MODEL = "claude-haiku-4-5-20251001"
#: 応答の最大トークン数。返してほしいのは部屋名と座標の短いJSONだけなので小さめにする。
@@ -98,7 +105,11 @@ class AiOcrError(RuntimeError):
class AiApiKeyMissingError(AiOcrError):
- """環境変数 `ANTHROPIC_API_KEY` にAPIキーが設定されていない場合に送出する例外。"""
+ """APIキーが資格情報ストアにも環境変数 `ANTHROPIC_API_KEY` にも無い場合に送出する例外。"""
+
+
+class ExternalAiDisabledError(AiOcrError):
+ """ローカル完結モード(外部AIを許可していない)のまま送信しようとした場合の例外(第10回)。"""
class AiResponseFormatError(AiOcrError):
@@ -132,27 +143,43 @@ class PreparedImage:
def get_api_key(environ: dict[str, str] | None = None) -> str:
- """環境変数 `ANTHROPIC_API_KEY` からAPIキーを読む。
+ """APIキーを「資格情報ストア → 環境変数(開発用)」の順に探す(第10回から)。
- 未設定・空白だけの場合は、分かりやすいメッセージで `AiApiKeyMissingError`(キーの値は含めない)。
+ どちらにも無ければ、分かりやすいメッセージで `AiApiKeyMissingError`(キーの値は含めない)。
"""
- env = os.environ if environ is None else environ
- key = env.get(ENV_API_KEY, "").strip()
- if not key:
+ resolved = load_api_key(environ)
+ if resolved is None:
raise AiApiKeyMissingError(
- f"外部AIのAPIキーが設定されていません。環境変数 {ENV_API_KEY} にAPIキーを設定してから"
- "アプリを起動し直してください(キーはコードや設定ファイルに書かないでください)。"
+ "外部AIのAPIキーが設定されていません。「設定...」画面でAPIキーを保存してください"
+ f"(開発時は環境変数 {ENV_API_KEY} でも可。キーはコードや設定ファイルに書かないでください)。"
"外部AIを使わない場合は、読み取り方式を「ローカル」に戻してください。"
)
- return key
+ return resolved.value
-def resolve_model(environ: dict[str, str] | None = None) -> str:
- """使用するモデルIDを返す(環境変数 `MADORI_OCR_AI_MODEL` があればそれ、無ければ既定)。"""
+def resolve_model(environ: dict[str, str] | None = None, *, settings: AppSettings | None = None) -> str:
+ """使用するモデルIDを返す。設定画面のモデルID → 環境変数 `MADORI_OCR_AI_MODEL` → 既定の順。"""
+ if settings is not None and settings.ai_model.strip():
+ return settings.ai_model.strip()
env = os.environ if environ is None else environ
return env.get(ENV_MODEL, "").strip() or DEFAULT_AI_MODEL
+def ensure_external_ai_allowed(settings: AppSettings) -> None:
+ """設定が「外部AIを許可」でなければ `ExternalAiDisabledError`(通信の前に必ず呼ぶ)。
+
+ 画面の選択肢を無効にするだけでは、画面の作り間違いや別の呼び出し口(一括処理など)
+ から送信されてしまうおそれがある。送信する関数そのものでも止める。
+ """
+ if not isinstance(settings, AppSettings):
+ raise TypeError("settings には AppSettings を渡してください。")
+ if not settings.external_ai_allowed:
+ raise ExternalAiDisabledError(
+ "ローカル完結モードのため、外部AIへは送信できません。外部AIを使う場合は、"
+ "「設定...」画面で読み取りモードを「外部AIを許可」に切り替えてください。"
+ )
+
+
def create_client(api_key: str) -> anthropic.Anthropic:
"""Anthropic公式SDKのクライアントを作る(タイムアウトと自動リトライ回数を明示)。"""
return anthropic.Anthropic(api_key=api_key, timeout=DEFAULT_TIMEOUT_SECONDS, max_retries=DEFAULT_MAX_RETRIES)
@@ -283,6 +310,7 @@ def _parse_bbox(raw: Any, image_width: int, image_height: int) -> tuple[float, f
def ai_ocr_image(
image: Image.Image,
*,
+ settings: AppSettings,
base_scale: float,
page_number: int = 0,
client: Any | None = None,
@@ -291,14 +319,18 @@ def ai_ocr_image(
) -> AiOcrResult:
"""画像を外部AIに送り、部屋名を読み取って `AiOcrResult` を返す。
- `client` を省略すると、環境変数のAPIキーで `create_client()` を呼ぶ
- (キーが無ければ、通信する前に `AiApiKeyMissingError`)。テストでは
+ 最初に `settings` を確認し、ローカル完結モードなら何もせず `ExternalAiDisabledError`
+ (第10回。`client` を渡した場合も同じ)。
+ `client` を省略すると、資格情報ストア(無ければ環境変数)のAPIキーで `create_client()` を
+ 呼ぶ(キーが無ければ、通信する前に `AiApiKeyMissingError`)。テストでは
`messages.create()` を持つダミーを渡す。
APIのエラーは種類ごとに分かりやすい日本語メッセージの `AiOcrError` に変換する。
+ メッセージにAPIキーらしい文字列が混ざっていれば伏せ字にする。
"""
+ ensure_external_ai_allowed(settings)
if client is None:
client = create_client(get_api_key())
- used_model = model or resolve_model()
+ used_model = model or resolve_model(settings=settings)
prepared = prepare_image(image, base_scale=base_scale, max_long_edge=max_long_edge)
request = build_request(prepared, model=used_model)
@@ -306,18 +338,21 @@ def ai_ocr_image(
try:
response = client.messages.create(**request)
except anthropic.AuthenticationError as exc: # 401
- raise AiOcrError(f"APIキーが無効です。環境変数 {ENV_API_KEY} の値を確認してください。") from exc
+ raise AiOcrError(
+ f"APIキーが無効です。「設定...」画面で保存したAPIキー(開発時は環境変数 {ENV_API_KEY})を確認してください。"
+ ) from exc
except anthropic.PermissionDeniedError as exc: # 403
raise AiOcrError("このAPIキーには、このモデル・機能を使う権限がありません。") from exc
except anthropic.NotFoundError as exc: # 404
raise AiOcrError(
- f"モデル '{used_model}' が見つかりません。環境変数 {ENV_MODEL} のモデルIDを"
+ f"モデル '{used_model}' が見つかりません。「設定...」画面のモデルID(開発時は環境変数 {ENV_MODEL})を"
"公式ドキュメントで確認してください。"
) from exc
except anthropic.RateLimitError as exc: # 429(SDKの自動リトライ後もなお失敗)
raise AiOcrError("APIの利用上限(レート制限)に達しました。しばらく待ってから再実行してください。") from exc
except anthropic.APIStatusError as exc: # その他のHTTPエラー(400・5xxなど)
- raise AiOcrError(f"外部AIの呼び出しに失敗しました(HTTP {exc.status_code}): {exc.message}") from exc
+ detail = redact_secrets(str(exc.message)) # 応答のメッセージにキーらしい文字列があれば伏せる
+ raise AiOcrError(f"外部AIの呼び出しに失敗しました(HTTP {exc.status_code}): {detail}") from exc
except anthropic.APIConnectionError as exc: # 通信エラー・タイムアウト
raise AiOcrError("外部AIに接続できませんでした。ネットワーク接続・プロキシ設定を確認してください。") from exc
elapsed = time.perf_counter() - started
@@ -346,6 +381,7 @@ def ai_ocr_pdf_page(
document: PdfDocument,
page_number: int,
*,
+ settings: AppSettings,
dpi: int = DEFAULT_DPI,
client: Any | None = None,
model: str | None = None,
@@ -356,13 +392,15 @@ def ai_ocr_pdf_page(
画像化は第4回のOCRと同じく `PdfDocument.render_page(zoom=1.0)` を再利用する
(プレビューの拡大率に結果が左右されないようにするため)。
"""
+ ensure_external_ai_allowed(settings) # 画像化の前に止める
rendered = document.render_page(page_number, zoom=1.0, dpi=dpi)
- return ai_ocr_rendered_page(rendered, client=client, model=model, max_long_edge=max_long_edge)
+ return ai_ocr_rendered_page(rendered, settings=settings, client=client, model=model, max_long_edge=max_long_edge)
def ai_ocr_rendered_page(
rendered: RenderedPage,
*,
+ settings: AppSettings,
client: Any | None = None,
model: str | None = None,
max_long_edge: int = DEFAULT_MAX_LONG_EDGE,
@@ -376,6 +414,7 @@ def ai_ocr_rendered_page(
base_scale = (rendered.dpi / 72.0) * rendered.zoom
return ai_ocr_image(
image,
+ settings=settings,
base_scale=base_scale,
page_number=rendered.page_number,
client=client,
メイン画面には「設定…」ボタンと、設定を画面に反映する処理を追加します。
app/ui/main_window.py に次の変更を加えます(+ が追加、- が削除)。
app/ui/main_window.py の差分(227行)
--- a/app/ui/main_window.py
+++ b/app/ui/main_window.py
@@ -39,6 +39,13 @@ AI(Anthropic Claude)へ送り、部屋名だけをJSONで受け取る。送
いまはPyMuPDFでの画像化(短時間)だけをこの画面のスレッドで行い、OCR・外部AIの
呼び出しを別スレッドへ渡す。処理中は進捗バーを動かし、「中止」を押せる。
画面(ウィジェット)の更新は、結果が戻ってきたあとにこの画面のスレッドでだけ行う。
+第10回では、「設定...」ボタンから設定画面(`app/ui/settings_dialog.py`)を開けるようにした。
+設定(`app/core/settings.py`。ユーザーの設定フォルダの settings.json)の読み取りモードが
+「ローカル完結」(既定)のあいだは、読み取り方式の「外部AI」を選べない(無効化)。
+外部AIのAPIキーは、設定画面で保存したOSの資格情報ストア(Windowsでは資格情報
+マネージャー)→ 環境変数 `ANTHROPIC_API_KEY`(開発用)の順に探す。送信する関数
+(`ai_ocr_rendered_page()`)にも設定を渡し、コア側でもローカル完結なら送信を止める。
+起動時に読み込む転記の設定ファイルも設定画面で指定できる。
"""
from __future__ import annotations
@@ -77,6 +84,14 @@ from app.core.ocr_ai import (
get_api_key,
resolve_model,
)
+from app.core.settings import (
+ AppSettings,
+ SettingsError,
+ default_settings_path,
+ load_settings,
+ redact_secrets,
+ save_settings,
+)
from app.core.ocr_local import OcrError, is_tesseract_available, ocr_rendered_page
from app.core.pdf_loader import PdfDocument, PdfLoadError
from app.core.review_model import ReviewedRoom, ReviewError, ReviewList
@@ -85,6 +100,7 @@ from app.core.text_extractor import ExtractedWord, extract_words
from app.ui.batch_dialog import open_batch_dialog
from app.ui.preview_canvas import PreviewCanvas
from app.ui.review_dialog import open_review_dialog
+from app.ui.settings_dialog import open_settings_dialog
WINDOW_TITLE = "間取りOCR転記ツール"
WINDOW_SIZE = "760x980"
@@ -100,6 +116,10 @@ MAPPING_NOT_SELECTED = "未選択(既定:シート「部屋一覧」のC5か
READ_MODE_LOCAL = "local"
READ_MODE_AI = "ai"
+#: 読み取り方式「外部AI」の表示(第10回:設定で許可していないときは選べない)
+AI_RADIO_TEXT_ALLOWED = "外部AI(Claude。図面画像を送信)"
+AI_RADIO_TEXT_DISABLED = "外部AI(設定で無効:ローカル完結)"
+
#: 検出に使った方式ごとの、ステータス行に添える説明
_SOURCE_NOTES = {"embedded": "", "ocr": "(OCRで検出)", "ai": "(外部AIで検出)"}
@@ -117,6 +137,15 @@ class MainWindow(ttk.Frame):
# 読み取り方式。既定は必ずローカル(外部AIは利用者が明示的に選んだときだけ使う)
self.read_mode_var = tk.StringVar(value=READ_MODE_LOCAL)
+ # アプリの設定(第10回)。読めなければ既定(ローカル完結)で起動する
+ self.settings_path = default_settings_path()
+ settings_error: str | None = None
+ try:
+ self.settings = load_settings(self.settings_path)
+ except SettingsError as exc:
+ self.settings = AppSettings()
+ settings_error = str(exc)
+
# 直近に「4.」で絞り込んだ結果(第6回の確認画面へ渡す)と、確認画面で確定した一覧
self._last_detection: tuple[list[ExtractedWord], list[RoomCandidate], str, int] | None = None
self.reviewed_rooms: list[ReviewedRoom] | None = None
@@ -142,10 +171,18 @@ class MainWindow(ttk.Frame):
self._room_dictionary_error = None
self._build_widgets()
+ self._apply_settings()
self._refresh_run_button()
if self._room_dictionary is None:
self.filter_room_button.configure(state="disabled")
messagebox.showerror("部屋名辞書エラー", self._room_dictionary_error)
+ if settings_error is not None:
+ messagebox.showwarning(
+ "設定ファイルを読み込めません",
+ settings_error,
+ detail="既定の設定(ローカル完結モード)で起動します。「設定...」から保存し直してください。",
+ )
+ self._load_default_mapping()
def _build_widgets(self) -> None:
self.columnconfigure(0, weight=1)
@@ -181,16 +218,20 @@ class MainWindow(ttk.Frame):
ttk.Label(mode_frame, text="読み取り方式:").pack(side="left")
ttk.Radiobutton(
mode_frame,
- text="ローカル(埋め込み文字→OCR。社外に送信しない)",
+ text="ローカル(社外に送信しない)",
variable=self.read_mode_var,
value=READ_MODE_LOCAL,
).pack(side="left")
- ttk.Radiobutton(
+ self.ai_radio = ttk.Radiobutton(
mode_frame,
- text="外部AI(Claude。図面画像を送信)",
+ text=AI_RADIO_TEXT_ALLOWED,
variable=self.read_mode_var,
value=READ_MODE_AI,
- ).pack(side="left", padx=(8, 0))
+ )
+ self.ai_radio.pack(side="left", padx=(8, 0))
+ # 第10回:設定画面(読み取りモード・APIキー・モデルID・起動時の転記設定ファイル)
+ self.settings_button = ttk.Button(mode_frame, text="設定...", command=self._on_open_settings)
+ self.settings_button.pack(side="right", padx=(0, 8))
self.detect_text_button = ttk.Button(
self,
@@ -350,6 +391,7 @@ class MainWindow(ttk.Frame):
self.batch_button.configure(
state=normal_if[self.selected.excel_path is not None and not busy and self._room_dictionary is not None]
)
+ self.settings_button.configure(state=normal_if[not busy])
if busy:
self.run_button.configure(state="disabled")
else:
@@ -401,7 +443,8 @@ class MainWindow(ttk.Frame):
if isinstance(exc, (AiOcrError, OcrError, PdfLoadError)):
messagebox.showerror(error_title, str(exc))
else:
- messagebox.showerror("予期しないエラー", f"{type(exc).__name__}: {exc}")
+ # 想定外の例外のメッセージにAPIキーらしい文字列が混ざっていても画面に出さない
+ messagebox.showerror("予期しないエラー", redact_secrets(f"{type(exc).__name__}: {exc}"))
self.status_var.set("読み取りに失敗しました。")
self._job = BackgroundJob(work, schedule=self.after, on_done=done, on_error=error)
@@ -435,6 +478,15 @@ class MainWindow(ttk.Frame):
return
page_number = self.preview.page_number
if self.read_mode_var.get() == READ_MODE_AI:
+ if not self.settings.external_ai_allowed:
+ # 選択肢は無効化しているが、念のためここでも止める(コア側でも止まる)
+ self.read_mode_var.set(READ_MODE_LOCAL)
+ messagebox.showerror(
+ "外部AIは使えません",
+ "ローカル完結モードのため、外部AIへは送信できません。",
+ detail="外部AIを使う場合は「設定...」で読み取りモードを「外部AIを許可」にしてください。",
+ )
+ return
self._start_ai_detection(document, page_number, on_detected)
return
@@ -469,7 +521,7 @@ class MainWindow(ttk.Frame):
) -> None:
"""表示中のページを外部AIに送り、部屋名を読み取る(第5回。第9回から別スレッドで通信する)。
- 1. APIキー(環境変数 `ANTHROPIC_API_KEY`)が無ければ、送信確認より前にエラーを表示して終わる
+ 1. APIキー(資格情報ストア→環境変数。第10回)が無ければ、送信確認より前にエラーを表示して終わる
(確認ダイアログで「OK」を押させてから失敗させないため)。
2. 「図面画像を外部サービスへ送信します」という確認ダイアログを毎回出す。
「キャンセル」なら何も送信せずに終わる。
@@ -481,7 +533,8 @@ class MainWindow(ttk.Frame):
messagebox.showerror("外部AIの設定エラー", str(exc))
return
- model = resolve_model()
+ settings = self.settings # 送信までに設定が変わっても、確認した時点の設定で送る
+ model = resolve_model(settings=settings)
if not messagebox.askokcancel(
SEND_CONFIRMATION_TITLE,
SEND_CONFIRMATION_TITLE,
@@ -499,7 +552,7 @@ class MainWindow(ttk.Frame):
return
client = self._create_ai_client(api_key)
self._run_in_background(
- lambda _job: ai_ocr_rendered_page(rendered, client=client, model=model).words,
+ lambda _job: ai_ocr_rendered_page(rendered, settings=settings, client=client, model=model).words,
message="外部AIで読み取っています(通信中)...「中止」で結果を捨てられます",
on_done=lambda words: self._deliver_detection(document, page_number, words, "ai", on_detected),
error_title="外部AIエラー",
@@ -523,6 +576,54 @@ class MainWindow(ttk.Frame):
"""外部AIのクライアントを作る(スクリーンショット撮影時などに差し替えられるよう分けている)。"""
return create_client(api_key)
+ # --- 設定(第10回) ------------------------------------------------------------
+
+ def _apply_settings(self) -> None:
+ """設定を画面に反映する。ローカル完結モードなら「外部AI」の選択肢を無効にし、ローカルに戻す。"""
+ if self.settings.external_ai_allowed:
+ self.ai_radio.configure(state="normal", text=AI_RADIO_TEXT_ALLOWED)
+ else:
+ self.ai_radio.configure(state="disabled", text=AI_RADIO_TEXT_DISABLED)
+ self.read_mode_var.set(READ_MODE_LOCAL)
+
+ def _load_default_mapping(self) -> None:
+ """設定画面で指定した「起動時に読み込む転記の設定ファイル」を読み込む(無ければ何もしない)。"""
+ path = self.settings.default_mapping_path
+ if not path:
+ return
+ try:
+ config = load_mapping_config(path, self._room_dictionary)
+ except MappingError as exc:
+ messagebox.showwarning(
+ "既定の転記設定ファイルを読み込めません",
+ str(exc),
+ detail="第7回と同じ既定の対応付けで起動します。「設定...」または「2-2.」で選び直してください。",
+ )
+ return
+ self.mapping_config = config
+ self.mapping_path_var.set(f"{path}({len(config.templates)}種類のテンプレートの設定・起動時に読み込み)")
+ self._refresh_mapping_status()
+
+ def _on_open_settings(self) -> None:
+ """「設定...」ボタン。設定画面で「OK」なら保存して画面に反映する。"""
+ if self._job is not None:
+ return
+ new_settings = open_settings_dialog(self, settings=self.settings, settings_path=self.settings_path)
+ if new_settings is None:
+ return
+ try:
+ save_settings(new_settings, self.settings_path)
+ except SettingsError as exc:
+ messagebox.showerror("設定を保存できません", str(exc))
+ return
+ mapping_changed = new_settings.default_mapping_path != self.settings.default_mapping_path
+ self.settings = new_settings
+ self._apply_settings()
+ if mapping_changed:
+ self._load_default_mapping()
+ mode = "外部AIを許可" if new_settings.external_ai_allowed else "ローカル完結"
+ self.status_var.set(f"設定を保存しました(読み取りモード:{mode})。")
+
def _on_detect_text(self) -> None:
"""表示中のページの文字を検出し、検出枠をプレビューに重ねて表示する。
.env.example に次の変更を加えます(+ が追加、- が削除)。
--- a/.env.example
+++ b/.env.example
@@ -1,6 +1,9 @@
# .env.example
# 外部AIモード(第5回〜)で使う環境変数の例。実際の値はこのファイルに書かず、
# OSの環境変数として設定してください(このファイルはキー名の一覧です)。
+# 第10回から、APIキーはアプリの「設定...」画面でOSの資格情報ストア(Windowsでは
+# 資格情報マネージャー。keyring経由)に保存します。環境変数は、資格情報ストアに
+# 保存が無いときだけ使う開発用の手段です。モデルIDも設定画面の値が優先されます。
# Anthropic のAPIキー(Claude Console で発行)。値はコミットしないこと
ANTHROPIC_API_KEY=
すべてのテストで、keyringをメモリ上の実装に差し替える共通設定です(開発者のPCの本物の資格情報に触れないため)。tests フォルダに置くと、pytestが自動で読み込みます。
tests/conftest.py を新しく作ります(全文)。
# tests/conftest.py
"""pytest全体の共通設定(第10回)。
APIキーの保存先(keyring)は、実行するPCのOSの資格情報ストアにつながる。
テストが開発者の本物の資格情報を読んだり書き換えたりしないよう、すべてのテストで
keyring のバックエンドをメモリ上の実装に差し替える(`keyring.set_keyring()`)。
Linuxのサーバー・CIのように資格情報ストアが使えない環境でも同じように動く。
"""
from __future__ import annotations
from collections.abc import Iterator
import keyring
import keyring.backend
import keyring.errors
import pytest
class MemoryKeyring(keyring.backend.KeyringBackend):
"""テスト用:パスワードを辞書に持つだけのkeyringバックエンド(プロセス終了で消える)。"""
priority = 1 # type: ignore[assignment]
def __init__(self) -> None:
super().__init__()
self.passwords: dict[tuple[str, str], str] = {}
def get_password(self, service: str, username: str) -> str | None:
return self.passwords.get((service, username))
def set_password(self, service: str, username: str, password: str) -> None:
self.passwords[(service, username)] = password
def delete_password(self, service: str, username: str) -> None:
if (service, username) not in self.passwords:
raise keyring.errors.PasswordDeleteError("not found")
del self.passwords[(service, username)]
@pytest.fixture(autouse=True)
def memory_keyring(monkeypatch: pytest.MonkeyPatch) -> Iterator[MemoryKeyring]:
"""すべてのテストで、keyringをメモリ上の実装に差し替え、開発用の環境変数も外す。"""
monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
previous = keyring.get_keyring()
backend = MemoryKeyring()
keyring.set_keyring(backend)
try:
yield backend
finally:
keyring.set_keyring(previous)
設定の保存・読み込みとAPIキーの扱いのテストです。
tests/test_settings.py を新しく作ります(全文)。
tests/test_settings.py の全文(325行)
# tests/test_settings.py
"""`app/core/settings.py` のテスト(第10回)。
keyring のバックエンドは `tests/conftest.py` でメモリ上の実装に差し替えている
(OSの資格情報ストアには触れない)。APIキーはすべて架空の値。
"""
from __future__ import annotations
import ast
import json
import logging
from pathlib import Path
import keyring
import keyring.backend
import keyring.errors
import pytest
from keyring.backends import fail as keyring_fail
from app.core import settings as settings_module
from app.core.settings import (
ENV_API_KEY,
KEYRING_SERVICE,
KEYRING_USERNAME,
MASKED_KEY,
MODE_EXTERNAL_AI,
MODE_LOCAL,
SOURCE_ENV,
SOURCE_KEYRING,
ApiKeyStoreError,
AppSettings,
ResolvedApiKey,
SettingsError,
api_key_status,
default_settings_dir,
delete_api_key,
describe_api_key_status,
is_keyring_available,
load_api_key,
load_settings,
redact_secrets,
save_api_key,
save_settings,
validate_model_id,
)
#: 架空のAPIキー(実在しない。伏せ字処理を確かめるため先頭だけAnthropicのキーと同じ「sk-ant-」にしている)
FAKE_KEY = "sk-ant-" + "FAKE-NOT-A-REAL-KEY"
CODE_DIR = Path(__file__).resolve().parents[1]
# --- 既定値と保存先 ------------------------------------------------------------------
def test_default_is_local_mode() -> None:
settings = AppSettings()
assert settings.read_mode == MODE_LOCAL
assert settings.external_ai_allowed is False
def test_missing_file_gives_local_mode(tmp_path: Path) -> None:
assert load_settings(tmp_path / "none" / "settings.json") == AppSettings()
@pytest.mark.parametrize(
("platform", "environ", "expected"),
[
("win32", {"APPDATA": r"C:\Users\taro\AppData\Roaming"}, Path(r"C:\Users\taro\AppData\Roaming") / "MadoriOCR"),
("win32", {}, Path("/home/taro") / "AppData" / "Roaming" / "MadoriOCR"),
("darwin", {}, Path("/home/taro") / "Library" / "Application Support" / "MadoriOCR"),
("linux", {"XDG_CONFIG_HOME": "/xdg"}, Path("/xdg") / "madori-ocr"),
("linux", {}, Path("/home/taro") / ".config" / "madori-ocr"),
],
)
def test_default_settings_dir_per_os(platform: str, environ: dict[str, str], expected: Path) -> None:
assert default_settings_dir(platform, environ, Path("/home/taro")) == expected
# --- 設定ファイルの読み書き ------------------------------------------------------------
def test_save_and_load_round_trip(tmp_path: Path) -> None:
path = tmp_path / "MadoriOCR" / "settings.json"
original = AppSettings(
read_mode=MODE_EXTERNAL_AI,
ai_model="claude-haiku-4-5-20251001",
default_mapping_path="C:/設定/mapping.yaml",
)
saved = save_settings(original, path)
assert saved == path and path.exists()
assert load_settings(path) == original
data = json.loads(path.read_text(encoding="utf-8"))
assert data == {
"version": 1,
"read_mode": "external_ai",
"ai_model": "claude-haiku-4-5-20251001",
"default_mapping_path": "C:/設定/mapping.yaml",
}
assert [p.name for p in path.parent.iterdir()] == ["settings.json"] # 一時ファイルが残らない
def test_settings_file_never_contains_api_key(tmp_path: Path) -> None:
save_api_key(FAKE_KEY)
path = save_settings(AppSettings(read_mode=MODE_EXTERNAL_AI), tmp_path / "settings.json")
text = path.read_text(encoding="utf-8")
assert FAKE_KEY not in text
assert "key" not in json.loads(text) # APIキー用の項目そのものが無い
assert "api_key" not in AppSettings.__dataclass_fields__
def test_unknown_keys_are_ignored_and_not_used(tmp_path: Path) -> None:
path = tmp_path / "settings.json"
path.write_text(json.dumps({"version": 1, "read_mode": "local", "api_key": FAKE_KEY, "future": 1}), "utf-8")
assert load_settings(path) == AppSettings()
def test_load_accepts_utf8_bom(tmp_path: Path) -> None:
path = tmp_path / "settings.json"
path.write_bytes(b"\xef\xbb\xbf" + json.dumps({"read_mode": "external_ai"}).encode("utf-8"))
assert load_settings(path).external_ai_allowed
@pytest.mark.parametrize(
("content", "message"),
[
(b"{ broken", "壊れています"),
(b"[1, 2]", "オブジェクト"),
('{"read_mode": "cloud"}'.encode(), "読み取りモード"),
(b'{"read_mode": true}', "文字列"),
(b'{"version": 2}', "版"),
('{"ai_model": "モデル"}'.encode(), "モデルID"),
('{"x": "寝室"}'.encode("shift_jis"), "UTF-8"),
],
)
def test_broken_settings_raise_clear_error(tmp_path: Path, content: bytes, message: str) -> None:
path = tmp_path / "settings.json"
path.write_bytes(content)
with pytest.raises(SettingsError, match=message):
load_settings(path)
def test_too_large_settings_file_is_rejected(tmp_path: Path) -> None:
path = tmp_path / "settings.json"
path.write_text('{"ai_model": "' + "a" * 70_000 + '"}', "utf-8")
with pytest.raises(SettingsError, match="大きすぎます"):
load_settings(path)
def test_save_rejects_invalid_mode(tmp_path: Path) -> None:
with pytest.raises(SettingsError):
save_settings(AppSettings(read_mode="cloud"), tmp_path / "settings.json")
assert not (tmp_path / "settings.json").exists()
@pytest.mark.parametrize("value", ["", " ", "claude-haiku-4-5-20251001", "claude-haiku-4-5", " claude-x "])
def test_validate_model_id_accepts(value: str) -> None:
assert validate_model_id(value) == value.strip()
@pytest.mark.parametrize("value", ["claude haiku", "claude;rm", "a" * 101, "モデル"])
def test_validate_model_id_rejects(value: str) -> None:
with pytest.raises(SettingsError):
validate_model_id(value)
def test_api_key_in_model_field_is_rejected_without_echo(tmp_path: Path) -> None:
"""モデルIDの欄にAPIキーを貼っても、設定ファイルに平文で残らず、メッセージにも出ない。"""
with pytest.raises(SettingsError) as excinfo:
save_settings(AppSettings(ai_model=FAKE_KEY), tmp_path / "settings.json")
assert "APIキー" in str(excinfo.value)
assert FAKE_KEY not in str(excinfo.value)
assert not (tmp_path / "settings.json").exists()
# --- APIキー(keyring) -------------------------------------------------------------
def test_save_and_load_api_key_uses_keyring(memory_keyring: object) -> None:
save_api_key(f" {FAKE_KEY} ")
assert keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME) == FAKE_KEY
resolved = load_api_key({})
assert resolved is not None
assert (resolved.value, resolved.source) == (FAKE_KEY, SOURCE_KEYRING)
def test_keyring_is_preferred_over_environment() -> None:
save_api_key(FAKE_KEY)
resolved = load_api_key({ENV_API_KEY: "dummy-env-key"})
assert resolved is not None and resolved.source == SOURCE_KEYRING
def test_environment_is_used_when_keyring_is_empty() -> None:
resolved = load_api_key({ENV_API_KEY: " dummy-env-key "})
assert resolved is not None
assert (resolved.value, resolved.source) == ("dummy-env-key", SOURCE_ENV)
assert load_api_key({}) is None
assert load_api_key({ENV_API_KEY: " "}) is None
def test_delete_api_key() -> None:
save_api_key(FAKE_KEY)
assert delete_api_key() is True
assert load_api_key({}) is None
assert delete_api_key() is False # 2回目は「保存されていない」
def test_blank_stored_value_is_treated_as_missing(memory_keyring: object) -> None:
keyring.set_password(KEYRING_SERVICE, KEYRING_USERNAME, " ")
assert load_api_key({}) is None
@pytest.mark.parametrize("value", ["", " ", "sk-ant key", "sk-ant\nkey", "k" * 513])
def test_invalid_api_key_is_rejected_without_echo(value: str) -> None:
with pytest.raises(ApiKeyStoreError) as excinfo:
save_api_key(value)
if value.strip():
assert value.strip() not in str(excinfo.value)
assert keyring.get_password(KEYRING_SERVICE, KEYRING_USERNAME) is None
def test_resolved_api_key_repr_and_str_are_masked() -> None:
resolved = ResolvedApiKey(FAKE_KEY, SOURCE_KEYRING)
assert FAKE_KEY not in repr(resolved)
assert FAKE_KEY not in str(resolved)
assert MASKED_KEY in str(resolved)
def test_status_and_description_never_show_key() -> None:
assert describe_api_key_status(api_key_status({})) == "未設定"
env_status = api_key_status({ENV_API_KEY: FAKE_KEY})
assert env_status.env_set and not env_status.stored
assert ENV_API_KEY in describe_api_key_status(env_status)
save_api_key(FAKE_KEY)
status = api_key_status({})
text = describe_api_key_status(status)
assert status.stored and "保存済み" in text
assert FAKE_KEY not in text and FAKE_KEY[-4:] not in text # 末尾の数文字も出さない
assert FAKE_KEY not in repr(status)
def test_redact_secrets() -> None:
assert FAKE_KEY not in redact_secrets(f"error: {FAKE_KEY}")
assert redact_secrets("value=abc123", "abc123") == f"value={MASKED_KEY}"
assert redact_secrets("ふつうの文章") == "ふつうの文章"
# --- 資格情報ストアが使えない・失敗する環境 ---------------------------------------------
class LeakyFailingKeyring(keyring.backend.KeyringBackend):
"""保存・削除に失敗し、エラーメッセージに渡された値をそのまま含めてしまうバックエンド。"""
priority = 1 # type: ignore[assignment]
def get_password(self, service: str, username: str) -> str | None:
raise RuntimeError(f"cannot read {service}/{username}")
def set_password(self, service: str, username: str, password: str) -> None:
raise keyring.errors.PasswordSetError(f"failed to store {password}")
def delete_password(self, service: str, username: str) -> None:
raise RuntimeError("backend is locked")
def test_no_keyring_backend_falls_back_to_environment() -> None:
"""Linuxのサーバー等(使えるバックエンドが無い)では、保存はできず環境変数だけを使う。"""
keyring.set_keyring(keyring_fail.Keyring())
assert is_keyring_available() is False
with pytest.raises(ApiKeyStoreError, match="資格情報ストアが使えない"):
save_api_key(FAKE_KEY)
assert delete_api_key() is False
resolved = load_api_key({ENV_API_KEY: "dummy-env-key"})
assert resolved is not None and resolved.source == SOURCE_ENV
status = api_key_status({})
assert status.store_available is False
assert "資格情報ストアを使えません" in describe_api_key_status(status)
def test_backend_errors_do_not_leak_key_to_message_or_logs(caplog: pytest.LogCaptureFixture) -> None:
keyring.set_keyring(LeakyFailingKeyring())
caplog.set_level(logging.DEBUG, logger="app.core.settings")
with pytest.raises(ApiKeyStoreError) as excinfo:
save_api_key(FAKE_KEY)
error = excinfo.value
assert FAKE_KEY not in str(error)
assert "PasswordSetError" in str(error)
# 元の例外(メッセージにキーを含む)を連結していない
assert error.__cause__ is None and error.__suppress_context__ is True
with pytest.raises(ApiKeyStoreError, match="RuntimeError"):
delete_api_key()
assert load_api_key({ENV_API_KEY: "dummy-env-key"}) is not None # 読み込みに失敗しても環境変数へ進む
assert FAKE_KEY not in caplog.text
def test_logs_never_contain_api_key(caplog: pytest.LogCaptureFixture, tmp_path: Path) -> None:
caplog.set_level(logging.DEBUG)
save_api_key(FAKE_KEY)
resolved = load_api_key({})
status = api_key_status({})
save_settings(AppSettings(read_mode=MODE_EXTERNAL_AI), tmp_path / "settings.json")
delete_api_key()
load_api_key({ENV_API_KEY: FAKE_KEY})
logging.getLogger("test").info("読み込み結果: %r %s %r", resolved, resolved, status)
assert caplog.records # ログ自体は出ている
assert FAKE_KEY not in caplog.text
def test_settings_module_does_not_import_gui() -> None:
tree = ast.parse((CODE_DIR / "app" / "core" / "settings.py").read_text(encoding="utf-8"))
imported = {
alias.name.split(".")[0]
for node in ast.walk(tree)
if isinstance(node, (ast.Import, ast.ImportFrom))
for alias in (node.names if isinstance(node, ast.Import) else [ast.alias(node.module or "")])
}
assert "tkinter" not in imported
def test_batch_processing_never_calls_external_ai() -> None:
"""一括処理(第9回)はローカルだけで読み取る。外部AIのモジュールを参照していないことを確かめる。"""
source = (CODE_DIR / "app" / "core" / "batch.py").read_text(encoding="utf-8")
assert "ocr_ai" not in source
assert settings_module.MODE_LOCAL == "local"
外部AIのテストは、送信する関数に設定を渡す形に直し、ローカル完結で止まることなどのテストを足します。
tests/test_ocr_ai.py に次の変更を加えます(+ が追加、- が削除)。
tests/test_ocr_ai.py の差分(137行)
--- a/tests/test_ocr_ai.py
+++ b/tests/test_ocr_ai.py
@@ -34,6 +34,7 @@ from app.core.ocr_ai import (
AiApiKeyMissingError,
AiOcrError,
AiResponseFormatError,
+ ExternalAiDisabledError,
ai_ocr_image,
ai_ocr_pdf_page,
build_request,
@@ -44,6 +45,10 @@ from app.core.ocr_ai import (
resolve_model,
)
from app.core.pdf_loader import PdfDocument
+from app.core.settings import MODE_EXTERNAL_AI, AppSettings, save_api_key
+
+#: 外部AIを許可した設定(第10回から、送信する関数は設定を必ず受け取る)
+AI_ALLOWED = AppSettings(read_mode=MODE_EXTERNAL_AI)
class FakeMessages:
@@ -133,7 +138,7 @@ def test_ai_ocr_image_sends_one_request_with_resolved_model(monkeypatch: pytest.
monkeypatch.setenv(ENV_MODEL, "claude-test-model")
messages = FakeMessages('{"rooms": []}')
- result = ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages))
+ result = ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages))
assert len(messages.calls) == 1
assert messages.calls[0]["model"] == "claude-test-model"
@@ -215,7 +220,7 @@ def test_parse_normalizes_reversed_bbox() -> None:
def test_ai_ocr_image_raises_when_response_truncated() -> None:
messages = FakeMessages('{"rooms": [', stop_reason="max_tokens")
with pytest.raises(AiResponseFormatError, match="max_tokens"):
- ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages), model="m")
+ ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages), model="m")
def test_ai_ocr_pdf_page_returns_words_in_pdf_coordinates(tmp_path: Path) -> None:
@@ -228,7 +233,7 @@ def test_ai_ocr_pdf_page_returns_words_in_pdf_coordinates(tmp_path: Path) -> Non
# A4・150dpi(1240×1754px)は長辺1568pxに縮小されて送られる
messages = FakeMessages('{"rooms": [{"name": "居間", "bbox": [100, 100, 200, 140]}]}')
with PdfDocument(pdf_path) as document:
- result = ai_ocr_pdf_page(document, 0, client=FakeClient(messages), model="m")
+ result = ai_ocr_pdf_page(document, 0, settings=AI_ALLOWED, client=FakeClient(messages), model="m")
prompt = messages.calls[0]["messages"][0]["content"][1]["text"]
assert "高さ1568px" in prompt
@@ -264,7 +269,7 @@ def test_ai_ocr_image_without_client_and_key_fails_before_sending(monkeypatch: p
monkeypatch.setattr(ocr_ai, "create_client", _must_not_be_called)
with pytest.raises(AiApiKeyMissingError):
- ai_ocr_image(_white_image(), base_scale=1.0)
+ ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0)
def test_resolve_model_default_and_override() -> None:
@@ -289,7 +294,7 @@ def test_resolve_model_default_and_override() -> None:
def test_api_errors_are_converted_to_readable_messages(error: Exception, expected: str) -> None:
messages = FakeMessages(error=error)
with pytest.raises(AiOcrError, match=expected):
- ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages), model="m")
+ ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages), model="m")
def test_confirmation_message_mentions_external_send_and_model() -> None:
@@ -298,3 +303,70 @@ def test_confirmation_message_mentions_external_send_and_model() -> None:
assert "Claude API" in message
assert "claude-test" in message
assert "秘密保持" in message
+
+
+
+# --- 4. ローカル完結モードでは送信しない(第10回) ---------------------------------
+
+
+def test_local_mode_blocks_sending_even_with_client() -> None:
+ """設定がローカル完結なら、クライアントを渡されても通信の前に止まる(UIだけに頼らない)。"""
+ messages = FakeMessages('{"rooms": []}')
+ with pytest.raises(ExternalAiDisabledError, match="ローカル完結モード"):
+ ai_ocr_image(_white_image(), settings=AppSettings(), base_scale=1.0, client=FakeClient(messages), model="m")
+ assert messages.calls == []
+
+
+def test_local_mode_blocks_before_rendering_pdf(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ pdf_path = tmp_path / "blank.pdf"
+ doc = fitz.open()
+ doc.new_page(width=200, height=200)
+ doc.save(pdf_path)
+ doc.close()
+ messages = FakeMessages('{"rooms": []}')
+ with PdfDocument(pdf_path) as document:
+ rendered: list[int] = []
+ monkeypatch.setattr(document, "render_page", lambda *a, **k: rendered.append(1))
+ with pytest.raises(ExternalAiDisabledError):
+ ai_ocr_pdf_page(document, 0, settings=AppSettings(), client=FakeClient(messages), model="m")
+ assert rendered == [] and messages.calls == []
+
+
+def test_settings_are_required_to_send() -> None:
+ messages = FakeMessages('{"rooms": []}')
+ with pytest.raises(TypeError):
+ ai_ocr_image(_white_image(), base_scale=1.0, client=FakeClient(messages)) # type: ignore[call-arg]
+ with pytest.raises(TypeError):
+ ai_ocr_image(_white_image(), settings=None, base_scale=1.0, client=FakeClient(messages)) # type: ignore[arg-type]
+ assert messages.calls == []
+
+
+def test_get_api_key_prefers_keyring_over_environment(memory_keyring: object) -> None:
+ save_api_key("dummy-key-in-keyring")
+ assert get_api_key({ENV_API_KEY: "dummy-key-in-env"}) == "dummy-key-in-keyring"
+
+
+def test_resolve_model_prefers_settings() -> None:
+ settings = AppSettings(read_mode=MODE_EXTERNAL_AI, ai_model="claude-from-settings")
+ assert resolve_model({ENV_MODEL: "claude-from-env"}, settings=settings) == "claude-from-settings"
+ assert resolve_model({ENV_MODEL: "claude-from-env"}, settings=AppSettings()) == "claude-from-env"
+
+
+def test_ai_ocr_image_uses_model_from_settings() -> None:
+ messages = FakeMessages('{"rooms": []}')
+ settings = AppSettings(read_mode=MODE_EXTERNAL_AI, ai_model="claude-from-settings")
+ result = ai_ocr_image(_white_image(), settings=settings, base_scale=1.0, client=FakeClient(messages))
+ assert messages.calls[0]["model"] == result.model == "claude-from-settings"
+
+
+def test_api_error_message_does_not_leak_api_key_like_text() -> None:
+ fake_key = "sk-ant-" + "FAKE-NOT-A-REAL-KEY" # 架空の値(実在しない)
+ request = httpx.Request("POST", "https://api.anthropic.com/v1/messages")
+ error = anthropic.BadRequestError(
+ f"invalid header: {fake_key}", response=httpx.Response(400, request=request), body=None
+ )
+ messages = FakeMessages(error=error)
+ with pytest.raises(AiOcrError) as excinfo:
+ ai_ocr_image(_white_image(), settings=AI_ALLOWED, base_scale=1.0, client=FakeClient(messages), model="m")
+ assert "HTTP 400" in str(excinfo.value)
+ assert fake_key not in str(excinfo.value)
動かしてみる
pytest
ruff check .
python -m app.main
pytest で「352 passed」と表示されれば完了です。アプリを起動した直後は「外部AI」を選べません。「設定…」で読み取りモードを「外部AIを許可」にして「OK」を押すと選べるようになります。設定はWindowsでは %APPDATA%\MadoriOCR\settings.json に保存されます。
動作確認の方法
pytest は352件すべて成功しました(第9回までの297件に、設定・APIキー48件と外部AI側の7件を追加)。ruff check . もエラーはありません。
pip install -r requirements.txt # keyring==25.7.0 が追加されています
pytest tests/test_settings.py tests/test_ocr_ai.py
このLinux開発環境には使える資格情報ストアが無いため、tests/conftest.py でkeyringのバックエンドをメモリ上のテスト用実装に差し替えています(keyring.set_keyring())。開発者のPCでも本物の資格情報には触れません。主に次を確かめています。
- ローカル完結なら送信関数が通信も画像化もしない
- APIキーが資格情報ストア→環境変数の順で読まれ、設定ファイルに書かれない
- エラーに値を含めてしまう架空のバックエンドでも、エラー・ログ(DEBUGまで)に架空のキーが出ない
次は、設定画面で「外部AIを許可」を選び、APIキーの入力欄に架空の値を入力した状態です(開発環境(Linux)での確認画面です。Windows実機では見た目が異なります)。

「OK」を押すと、設定ファイルにはAPIキー以外の3項目だけが保存され、メイン画面の「外部AI」が選べるようになることも確認しました。
確認できていないこと
- Windowsの資格情報マネージャーでの実際の保存・読み込み・削除。keyring 25.7.0のソースを読むと、サービス名(今回は
madori-ocr)を名前とする汎用資格情報として保存する実装ですが、Windows実機では試していません - Windows実機での設定画面の見た目、
%APPDATA%への保存 - 実際のClaude APIでの動作(今回もAPIキーは使っていません)
つまずきやすい点・セキュリティ上の注意
- 設定の切り替えは「うっかり送信」を防ぐもので、利用者本人の操作は止められない:設定ファイルは利用者が書き換えられます。組織としてオフライン完結を徹底したい場合は、外部AIの機能を含まない版を配布するなど、別の対策が必要です
- 資格情報ストアに入れれば絶対安全、ではない:keyringの公式ページのセキュリティの注意では、Windows Credential Lockerについて「分析は行われていない」と書かれています(macOSについては、同じPythonから動く別のスクリプトがパスワードの確認なしに読めることが注意として挙がっています)。PC自体の管理(ログインの保護・不審なソフトを入れない)が前提です
- 環境変数は開発用に限る:環境変数にキーを置いたままにすると、資格情報ストアに保存が無いとき自動で使われます。配布先のPCでは設定しない運用にします
- テストで本物の資格情報ストアに触れない:
keyring.set_keyring()で差し替えないと、開発者のPCの資格情報を書き換えてしまうことがあります - ログ・エラー画面にキーを出さない:例外の連結やデバッグ出力から漏れやすいので、キーを持つ値は
reprを伏せ、エラーは種類名だけにします
発注者向けメモ
「オフラインで完結させたい」か「精度を優先したい」かを、契約時に決めておく
同じツールでも、ローカル完結(図面を社外に出さない代わりに、スキャン図面などでは精度が落ちやすい)と外部AI(精度の底上げが期待できる代わりに、図面画像を社外のAIサービスへ送る・利用料金がかかる)では、前提になる運用が大きく違います。どちらを前提にするかで、確認画面の作り込み、テストに使う図面、見積もりの範囲が変わります。
「最初はローカル完結、スキャン図面が多ければ外部AIも検討」のように段階を決めておくと、後から「外部AIも使えるはず」「送らない約束だったはず」という食い違いを防げます。顧客から預かる図面を社外へ送ってよいかは、顧客との秘密保持の取り決め次第です。個別の判断は契約の専門家に確認してください。
APIキーは「発注側の名義」で取得するのがおすすめ
一般に、外部AIのAPIキーは発行したアカウント(組織)に利用料金が請求され、サービスの契約上の利用者もそのアカウントの持ち主になります(契約条件は各サービスの規約で確認してください)。開発会社の名義のキーを組み込んでもらう形だと、次の点で困りやすくなります。
- 利用料金を開発会社経由で精算することになり、使用量が見えにくい
- 図面の送信先サービスとの契約当事者が開発会社になり、データの扱いを自社で確認・管理しにくい
- 保守契約の終了や担当者の交代のとき、キーを止める・入れ替える操作を自社でできない
発注側の名義でアカウントを作り、キーの発行・無効化・入れ替えを自社で行える体制にしておくと安心です。今回の作りなら、キーは各PCの設定画面で保存するため、開発会社にキーの値を渡す必要もありません。
社内ルールで決めておくこと
- どの図面なら外部AIに送ってよいか(顧客の了承の有無、図面の種類)
- 誰が「外部AIを許可」に切り替えてよいか、許可したPCをどう把握するか
- APIキーの管理者、入れ替えの頻度、退職・異動・PC入れ替え時の手順
- 利用料金の上限や通知をどう設定するか(サービスの管理画面でできることを確認)
- ☐ ローカル完結と外部AIのどちらを前提にするか、契約・仕様書に書いたか
- ☐ 図面を社外へ送ってよいか、顧客との取り決めを確認したか
- ☐ APIキーを発注側の名義で取得し、管理者を決めたか
- ☐ 外部AIを許可する人・PC・図面の範囲を社内ルールにしたか
開発会社への質問例
- 「ローカル完結モードのとき、どの処理で送信を止めていますか?画面の設定だけですか?」
- 「APIキーはどこに保存されますか?設定ファイルやログに残ることはありませんか?」
- 「APIキーを当社名義で用意した場合、入れ替えや削除は当社だけでできますか?」
- 「オフライン専用の版(外部AIの機能を含まない版)を作ることはできますか?」
まとめと次回予告
第10回では、app/core/settings.py と設定画面を作り、「ローカル完結(既定)」と「外部AIを許可」を切り替えられるようにしました。APIキーはkeyringでOSの資格情報ストアに保存し、ローカル完結のあいだは画面と送信関数の2か所で外部AIを止めています。Windowsの資格情報マネージャーでの実動作は未確認です。
次回(第11回・最終回)は「Windows向けにexe化して配布し、運用時の注意点を整理する」です。PyInstallerで単一のexeにまとめ、配布・初回起動時の注意点と、精度の限界を踏まえた最終チェック体制を整理します。
この連載の記事一覧
この記事は連載「CAD図面PDFをExcelへ自動転記するツール開発」の1回です。連載のほかの回は次のとおりです(連載の一覧ページ)。
- 【CAD図面PDFをExcelへ自動転記するツール開発 第0回】要件整理とPython開発環境、tkinterの最初の画面を作る
- 【CAD図面PDFをExcelへ自動転記するツール開発 第1回】PyMuPDFで図面PDFを画面にプレビュー表示する
- 【CAD図面PDFをExcelへ自動転記するツール開発 第2回】PyMuPDFで図面の文字を座標付きで抽出し、プレビューにハイライト表示する
- 【CAD図面PDFをExcelへ自動転記するツール開発 第3回】部屋名辞書とヒューリスティックで「部屋名らしき文字列」だけを絞り込む
- 【CAD図面PDFをExcelへ自動転記するツール開発 第4回】スキャン図面・画像PDFの部屋名をローカルOCR(Tesseract)で読み取る
- 【CAD図面PDFをExcelへ自動転記するツール開発 第5回】外部AI(Claude)の画像解析で図面の部屋名を読み取り、精度を底上げする
- 【CAD図面PDFをExcelへ自動転記するツール開発 第6回】AI・OCRの読み取り結果を人が確認・修正する画面を作る
- 【CAD図面PDFをExcelへ自動転記するツール開発 第7回】確認済みの部屋名を指定のExcelフォーマットの決まった欄へ転記する
- 【CAD図面PDFをExcelへ自動転記するツール開発 第8回】部屋名とExcelの欄の対応付けを設定ファイル(YAML)で変えられるようにする
- 【CAD図面PDFをExcelへ自動転記するツール開発 第9回】複数の図面PDFをフォルダごとまとめて処理する(進捗表示・中止・失敗しても止まらない一括処理)
- 【CAD図面PDFをExcelへ自動転記するツール開発 第10回】ローカル完結モードと外部AIモードを切り替え、APIキーをWindowsの資格情報マネージャーに保存する(この記事)
- 【CAD図面PDFをExcelへ自動転記するツール開発 第11回(最終回)】PyInstallerでWindows向けexeにまとめて配布し、精度の限界と確認のルールを整理する


コメント
コメント一覧 (1件)
[…] 前回(第10回)では、図面を社外に出さない「ローカル完結モード」と「外部AIモード」を設定画面で切り替え、APIキーをOSの資格情報ストアに保存できるようにしました。 […]