Pythonで名前空間パッケージを作成する方法｜pkgutilの使い方も解説

Pythonの名前空間パッケージとは

Pythonにおける名前空間パッケージ（namespace package）とは、複数のプロジェクトやディレクトリにまたがってPythonコードを分散配置できる仕組みです。関連するライブラリ群を、それぞれ独立した配布物としてリリースしたい場合に特に役立ちます。

例えば、PYTHONPATH上に「Package-1」と「Package-2」という2つのディレクトリがあり、以下のような構成になっているとします。

Package-1/namespace/__init__.py
Package-1/namespace/module1/__init__.py
Package-2/namespace/__init__.py
Package-2/namespace/module2/__init__.py

この構成では、エンドユーザーは import namespace.module1 および import namespace.module2 のように、同一の「namespace」名前空間から各モジュールをインポートできます。

Python 3.3以降：暗黙的な名前空間パッケージ

Python 3.3以降では、特別な設定は一切不要です。名前空間パッケージ用のディレクトリに __init__.py を置かないだけで、自動的に正しく動作します。

これは、Python 3.3で導入された「暗黙的な名前空間パッケージ（implicit namespace packages）」という機能によるものです。従来のように __init__.py を必須とせず、ディレクトリのみでもパッケージとして扱えるようになりました。

古いバージョン：pkgutilを使う方法

Python 3.3より前のバージョンでは、標準モジュールの pkgutil を利用します。extend_path 関数を使うことで、指定した名前空間へモジュールを「追加」できます。

Package-1/namespace/__init__.py と Package-2/namespace/__init__.py の両方に、次の2行を記述してください。

from pkgutil import extend_path
__path__ = extend_path(__path__, __name__)

このコードは、sys.path 上の各ディレクトリから、パッケージ名と同名のサブディレクトリをすべて検索し、それらをパッケージの __path__ に追加します。この処理により、2つのパッケージを別々に配布しても、ユーザー側は1つの名前空間としてシームレスに利用できるようになります。