ソースローダー

新しい URI スキームを解決可能にするローダーを追加します。

どのローダーも解決できない URI スキームは、何が始まるよりも前に 415 になります。SourceLoader は解決するスキームを宣言し、その背後にあるバイト列をチャンク単位で yield します。ローダーを宣言したディストリビューションをインストールすることが、インストール環境にスキームを教える唯一の方法です。file:、data:、http:、https:、s3: も indx-loader-file、indx-loader-http、indx-loader-s3 から、あなたの配布物とまったく同じエントリーポイントグループを通じて届きます。素の pip install indx は URI を一つも解決しません。パッケージ化とインストールは概要の手順に従います。

from collections.abc import Iterator
from typing import Any

from indx_interfaces import (
    CapabilityDescriptor,
    CapabilityId,
    InvalidSourceError,
    SourceLoader,
)

_CHUNK_BYTES = 64 * 1024


class GcsLoader:
    schemes = ("gs",)

    def fetch(self, uri: str) -> Iterator[bytes]:
        # クライアントライブラリはモジュールスコープではなくここでインポート
        # します。探索はスナップショット構築時に全プロバイダーモジュールを
        # インポートするためです。
        import google.cloud.storage as storage

        bucket, _, key = uri.removeprefix("gs://").partition("/")
        if not bucket or not key:
            raise InvalidSourceError(
                f"{uri} does not name a bucket and a key",
                code="source_unreadable",
                param="source.uri",
            )
        blob = storage.Client().bucket(bucket).blob(key)
        with blob.open("rb") as body:
            yield from iter(lambda: body.read(_CHUNK_BYTES), b"")


class Provider:
    def descriptors(self) -> tuple[CapabilityDescriptor, ...]:
        # このディストリビューションはバイト列を取得するだけで、何も読みません。
        return ()

    def create(self, capability_id: CapabilityId) -> Any:
        raise ValueError(f"this provider declares no capabilities, so not {capability_id}")

    def source_loaders(self) -> tuple[SourceLoader, ...]:
        return (GcsLoader(),)

観測の media_types と異なり、schemes は動作を左右する宣言です。呼び出しの前にローダーを選択し、415 が列挙する内容であり、スナップショットが resolvable として公開する内容でもあります（小文字、末尾のコロンなし）。インストールされたローダーは indx 同梱のものより先に並ぶため、indx がすでに解決できるスキームを引き受けることもできます。

ローダーは取得だけを行います。計画が束縛されるダイジェスト、メディアタイプ、入力上限は indx-source が所有し、消費しながらカウントします。そのため、本体全体を一つのチャンクで返すのではなく、上限を検査できる大きさのチャンクで yield してください。resolvable はスナップショットのコンテンツハッシュから除外されています。ローダーのインストールは次に計画できる範囲を広げるだけで、進行中の計画を無効にしません。

チェックリスト

ローダーが解決するスキームをすべて宣言し、宣言したものだけを解決する。
デプロイメントの入力上限を検査できるよう、チャンク単位で yield する。
取得できないソースには例外を送出する。このデプロイメントが到達すべきでない宛先はコード source_forbidden で拒否し、許可するための設定名をメッセージに含める。
認証情報は INDX_* 環境変数から取得する。記述子や呼び出し側の URI には決して含めない。

ソースローダー

チェックリスト

参考

開発者向け