wonderfish-cp-sdk

共通仕様・共通方針はWonderfish共通仕様、開発・検証・配備の共通ルールは共通開発ルールを参照してください。

Product ServiceからMVP Control Planeを呼び出すPython SDK。型付きclient、Managed Identity認証、Catalog cache、顧客・Product Service間Token検証を提供する。公開仕様はSDK仕様書、HTTP契約はcontractsを参照する。

取得

公開済みSDKの導入

Python 3.12以上で、Public PyPIの公開済みversionを固定して導入する。公開済み版は12.2.0です。

pip install wonderfish-cp-sdk==12.2.0

接続先のControl Planeは、contracts/internal.openapi.jsonと同じHTTP契約を提供すること。クラウド環境はdev・prodとし、管理下ResourceとバージョンなしAPIパスを使う。

source checkoutからの開発

開発対象のversionは pyproject.toml を正本とする。開発版のCatalog・Bindingは、表示名と説明を言語コードで引く形式に統一したCP契約を使います。main統合だけではPyPIへ公開されません。

公開前のlocal検証では、以下のローカル検証手順で対象commitからwheelをビルドし、そのwheelを検証環境へ導入する。正式配置では公開済みwheelを使う。sampleの配備版は配備結果のSDK版・wheel hashで確認し、mainへの反映だけでsampleが更新済みとは扱わない。

ローカル検証

python -m pip install --require-hashes -r requirements-dev.lock
python -m pip install --require-hashes -r examples/product-service/requirements.lock
python -m ruff check src tests .github/scripts
python -m compileall -q src tests .github/scripts
python -m pytest
python -m pip_audit -r requirements-dev.lock
python -m pip_audit -r examples/product-service/requirements.lock
node --check examples/product-service/assets/ui.mjs
node --test tests/test_sample_*.mjs tests/test_shared_*.mjs
python examples/product-service/download_msal.py
python -c "import pathlib, shutil; [shutil.rmtree(p, ignore_errors=True) for p in [pathlib.Path('build'), pathlib.Path('dist'), *pathlib.Path('src').glob('*.egg-info')]]"
python -m build --wheel --no-isolation
python -m twine check --strict dist/*.whl
version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
python .github/scripts/validate_wheel.py dist "${version}"
python -m pip install --force-reinstall --no-deps dist/*.whl
python -c "import wonderfish_cp; import wonderfish_cp.external"
python examples/product-service/smoke.py

ブラウザー処理の検証にはNode.js 22.23.2を使う。MSAL取得はビルド時の固定hash検査であり、pytestとNodeテストにはネットワークを使わない。

pytestとNodeテスト、smokeはネットワーク不要の開発検証。依存導入・監査・MSAL取得にはネットワークを使う。実CPとのHTTP・画面の結合試験はサンプル開発手順と試験項目書に従い、localの実CPとDevの実Managed Identityの結果を別に記録する。sample Docker imageのlock同期はDockerfileが指定する固定Python imageでpip-compileして確認する。

開発用lockはsample Dockerfileの固定Python 3.12.14イメージとpip-tools==7.6.1で生成する。WindowsとLinuxで必要な条件付き依存をdev extraに明示し、同じlockを両OSで使う。lockは手で編集しない。特定の依存を更新するときは対応するpip-compileに--upgrade-package <name>を付ける。

image="$(awk '/^FROM /{print $2}' examples/product-service/Dockerfile)"
docker run --rm --volume "${PWD}:/work" --workdir /work "$image" \
  sh -c 'python -m pip install --quiet pip-tools==7.6.1 && pip-compile --quiet --allow-unsafe --extra=dev --generate-hashes --output-file=requirements-dev.lock pyproject.toml && cd examples/product-service && pip-compile --quiet --generate-hashes --output-file=requirements.lock requirements.in'

再生成後は、次のコマンドでWindows/Linux向けの全wheelのhashと、Python 3.12.14で有効な依存関係を検査する。pip downloadのplatform指定だけでは依存条件が実行ホストで評価されるため、wheel内のメタデータも対象OSの条件で検証する。これは対象OS上での動作試験とは区別する。

wheel_root="$(mktemp -d /tmp/$(date +%Y%m%d%H%M%S)_sdk-wheels.XXXXXX)"
python -m pip download --only-binary=:all: --require-hashes -r requirements-dev.lock \
  --python-version 3.12 --implementation cp --abi cp312 --platform win_amd64 --dest "$wheel_root/windows"
python -m pip download --only-binary=:all: --require-hashes -r requirements-dev.lock \
  --python-version 3.12 --implementation cp --abi cp312 --platform manylinux_2_28_x86_64 \
  --platform manylinux_2_17_x86_64 --platform manylinux2014_x86_64 --dest "$wheel_root/linux"
python .github/scripts/validate_dev_lock.py windows "$wheel_root/windows"
python .github/scripts/validate_dev_lock.py linux "$wheel_root/linux"

PyPIへの公開

pyproject.toml の version を未公開の正式Semantic Versionに更新し、ローカル検証後に main → release のPRを作成する。必須チェック sdk・release-ready の成功後にマージすると、wheelのビルド・検証、PyPIへの公開、v<version> tagの付与を順に実行する。公開workflowはreleaseへのpush時に、対象commitが同一リポジトリのマージ済みmain→release PRのmerge commitであることをGitHub APIで検証する。mainへのpush・PRでは公開しない。

認証はPyPIのTrusted Publisherを使用する。登録先はowner HappyHackInc、repository hh-wonderfish-ai-sdk、workflow publish-pypi.yml、Environment pypi とし、GitHub側の pypi Environmentは release ブランチだけを許可する。公開済みversionとtagは変更せず、修正には新しいversionを使う。

構成

SDKはApache License 2.0で提供する。脆弱性・秘密情報は公開Issueへ記載せずsupport@happyhack.co.jpへ連絡する。

試験項目書・実施結果・未確認事項は試験索引を参照してください。テストコードは既存の配置で管理します。