fsspecと環境変数

Python

はじめに

fsspecはローカル、リモート (FTP, Samba, etc.)、アーカイブファイル (zip, tar, etc.)、そしてBlobストレージ (S3, etc.) を操作する統一的なインタフェースを提供してくれる、非常に便利なPythonパッケージだ。その核となるコンセプトはファイルシステムで、雑に言うと「ファイルがフォルダ分けされている点は、どれも同じでしょ」という感じで様々なデータ置き場へのアクセスを抽象化している。fsspecが特に便利だと思うのは、スキームにファイルシステム種別を書いたURLを使えばアプリケーション側で使うサービスを切り替えるロジックを書かずにファイルアクセスを実現できるところ。例えば次のような感じ。

urls = [
    "s3://some_bucket/foobar.txt",  # AWS S3 (MinIO)
    "sftp://hostname/path/to/foobar.txt",  # SFTP
    "file:///path/to/foobar.txt"  # ローカルファイル
    r"C:\Path\To\foobar.txt"  # ローカルファイルの場合は絶対パスでも OK
]
for url in urls:
    fs, path = fsspec.url_to_fs(url)
    with fs.open(path, "rt", encoding="utf-8") as f:
        content = f.read()
        print(content)

ただ、アクセスの内容によってはファイルシステムから認証情報などを要求されることも当然あり、そのような場合には追加パラメーターが必要になる。追加パラメーターをfsspecに与える方法は複数あり、少し複雑だ。fsspecのドキュメントから説明個所を抜粋しておく。

Configuration is determined in the following order, with later items winning:

  1. ini and json files in the config directory (FSSPEC_CONFIG_DIRECTORY or $HOME/.config/fsspec/), sorted lexically by filename
  2. FSSPEC_{protocol} environment variables
  3. FSSPEC_{protocol}_{kwargname} environment variables
  4. the contents of fsspec.config.conf, which can be edited at runtime
  5. kwargs explicitly passed, whether with fsspec.open, fsspec.filesystem or directly instantiating the implementation class.

—https://filesystem-spec.readthedocs.io/en/stable/features.html#configuration

使うサービスごとに違うコードを書くのは嫌なので、環境変数を使って設定する方法を少し掘り下げてみる。

ファイルシステムのパラメーターと環境変数

fsspecでは各種ファイルシステムの具象クラス（fsspec.spec.AbstractFileSystemの互換クラス）をインスタンス化するとき、環境変数などから得たパラメータを引数として渡す仕組みになっている。例えばS3の場合は次のように環境変数からs3fs.core.S3FileSystemの作成時に渡すキーワード引数（の辞書kwargs）を作成する。

  1. 環境変数FSSPEC_S3の値をJSONオブジェクト（辞書）として解釈し、その内容でkwargsを更新
  2. FSSPEC_S3_という接頭辞の付いた環境変数を検索し、その接頭辞に続く文字列をキーに、その環境変数値を値としてkwargsを更新

したがって、使いたいサービスごとに以下2点を把握しておくと適切にパラメーターを指定できる：

  1. どのファイルシステムクラスが使われるのか
  2. どのようなパラメーターが存在するのか

ここで、例えば今の時点で上記内容を調べ上げて一覧表にすることはできるものの、関連パッケージの数も非常に多いため確実にメンテナンスが追い付かなくなる。そのため、本記事では使ったことのある一部のファイルシステムについてだけ情報を書くにとどめたい。

なお以下の事情があるため、意図しない動作をしたときには必ずFSSPEC_系の環境変数以外の確認も忘れないように…。

  • kwargs は設定ファイルやプログラムコードでも更新できる
  • ファイルアクセス機能の実装を提供するパッケージ自体が独自に環境変数や設定ファイル等からパラメーターを読み出して使うこともある

各ファイルシステムの設定例など

動作確認環境

  • fsspec 2024.12.0
  • gcsfs 2024.12.0
  • s3fs 2024.12.0
  • paramiko 3.5.0

AWS S3 (MinIO)

  FSSPEC_S3={"anon": false, "endpoint_url": "localhost:9000", "key": "alice", "secret": "wonderland"}
  ### または ###
  FSSPEC_S3_ANON=false
  FSSPEC_S3_ENDPOINT_URL=localhost:9000  # MinIOの場合など
  FSSPEC_S3_KEY=alice  # FSSPEC_S3_USERNAMEでもOK
  FSSPEC_S3_SECRET=wonderland  # FSSPEC_S3_PASSWORDでもOK

GCS (Google Cloud Storage)

  FSSPEC_GCS={"token": "cloud"}
  ### または ###
  FSSPEC_GCS_TOKEN=cloud

SFTP

  FSSPEC_SFTP={"username": "alice", "password": "wonderland", "key_filename": "~/.ssh/id_ed25519"}
  ### または ###
  FSSPEC_SFTP_USERNAME=alice
  FSSPEC_SFTP_PASSWORD=wonderland
  FSSPEC_SFTP_KEY_FILENAME=~/.ssh/id_ed25519