Pythonのエラー・警告対処まとめ｜バージョン不整合・型スタブ・lint抑制

はじめに

Pythonのエラーは、コードではなく環境が原因であることがよくあります。特に「昨日まで動いていたのに」というときは、たいていライブラリのバージョンが噛み合っていません。

実際に遭遇したエラーと対処法をまとめました。

requests を使ったコードを実行すると出る警告です。

RequestsDependencyWarning: urllib3 (2.0.7) or chardet (None)/charset_normalizer (2.0.11) doesn't match a supported version!

requests が想定しているバージョンと、実際に入っている urllib3 のバージョンが噛み合っていません。まとめて更新すれば解消します。

$ pip install -U urllib3 requests

imbalanced-learn で fit_resample() したときに出ました。

'RandomOverSampler' object has no attribute '_validate_data'

imbalanced-learn が依存している scikit-learn のバージョンが古いことが原因でした。0.23.0以上に上げると解消します。

$ pip install -U scikit-learn

import lightgbm as lgb

lgb_train = lgb.Dataset(X_train, y_train)
# AttributeError: module 'lightgbm' has no attribute 'Dataset'

明示的にインポートすると動くことがあります。

from lightgbm import Dataset

ただし、これは根本原因の解決ではありません。この形のエラーでまず疑うべきは、同名ファイルによる上書きです。

作業ディレクトリに lightgbm.py というファイルがあると、Pythonはライブラリではなくそちらを読み込みます。中身が空なら、当然 Dataset は見つかりません。

import lightgbm
print(lightgbm.__file__)   # どこを読んでいるか確認する

出力が site-packages 配下でなければ、そのファイル名を変えてください。random.py や json.py など、標準ライブラリと同じ名前を付けてしまったときも同じことが起きます。

同名ファイルがないのにエラーが出る場合は、インストールが壊れている可能性があるので入れ直します。

$ pip install --force-reinstall lightgbm

バージョン起因を疑ったら、まず次の2つを確認します。

# 依存関係に矛盾がないか検査する
$ pip check

# 実際に入っているバージョンを見る
$ pip list | grep パッケージ名

pip check は、依存関係が壊れている組み合わせを一覧で教えてくれます。原因を探す前にこれを打つと早いです。

requests を使った簡単なコードでも、mypyがこう言ってきます。

import requests

res = requests.get("https://example.com/")
print(res.text)

Library stubs not installed for "requests"

型情報（スタブ）のパッケージが別配布になっているためです。入れれば解消します。

$ pip install types-requests

types- で始まるパッケージは、型情報だけを提供するものです。実行には不要なので、requirements.txt ではなく開発用の依存として管理するのが適切です。

他にもよく使うものがあります。

何を入れればよいか分からない場合は、mypyに任せることもできます。

$ mypy --install-types

lintの指摘を、意図的に無視したい場面はあります。

# 行単位で無視する
import os  # NOQA

# ファイル全体で無視する
# flake8: NOQA

特定のルールだけを無視することもできます。

import os  # noqa: F401

**ファイル全体の無視（# flake8: NOQA）は避けてください。**そのファイルで以降に混入するすべての問題が見えなくなります。

抑制するときは、行単位かつルール指定で、なぜ無視するのかをコメントに残すのが望ましいです。

from .models import User  # noqa: F401  # マイグレーション検出のため読み込みが必要

ツールとしては、現在は flake8 より Ruff が主流になりつつあります。Ruffでも # noqa の書き方は同じです。

環境起因のエラーは、コードをいくら読んでも原因が見つかりません。「昨日は動いた」「他の人の環境では動く」という症状が出たら、まず pip check と pip list でバージョンを確認するのが近道です。

そもそもの予防としては、プロジェクトごとに仮想環境を分けて、requirements.txt でバージョンを固定しておくのが確実です。