データ接続と統合Python基本的なトランスフォームプロジェクト構造

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

プロジェクト構造

読み進める前に、必ず入門ガイドに目を通してください。また、このページでは、セットアップした Python トランスフォームリポジトリに含まれるデフォルトのプロジェクト構造を使用していることを前提としています。

セットアップしたリポジトリのデフォルト構造

セットアップした Python トランスフォームリポジトリの標準的な構造は次のとおりです。

transforms-python
├── conda_recipe
│   └── meta.yaml
└── src
    ├── myproject
    │   ├── __init__.py
    │   ├── datasets
    │   │   ├── __init__.py
    │   │   └── examples.py
    │   └── pipeline.py
    ├── setup.cfg
    └── setup.py

リポジトリ内には、このほかにもファイルがあります。Code Repositories のファイルエクスプローラータブで設定の歯車アイコンを開き、隠しファイル・フォルダを表示を選択すると表示できます。ほとんどの場合、これらの隠しファイルは編集しないでください。Palantir は、これらの隠しファイルに独自の変更を加えたリポジトリをサポートしていません。

以下のファイルについて、以降で詳しく説明します。

リポジトリのアップグレードによるファイルの変更

リポジトリを初めて作成すると、その時点で最新の Python トランスフォームテンプレートのバージョンのデフォルト内容でセットアップされます。その後のリポジトリのアップグレードでは、最新の Python トランスフォームテンプレートのバージョンの内容に揃えるため、リポジトリ内のファイルがアップグレードされます。整合性を確保するため、新しいテンプレートへのアップグレード時に、これらのファイルにユーザーが加えた独自の変更が上書きされる場合があります。これらのファイルへの独自の変更は、予期しない動作につながる可能性があるため、サポートしていません。

次のファイルは、リポジトリのアップグレードによって上書きされません。

  • conda_recipe フォルダーおよび src フォルダー内のデフォルトファイル
  • 内側と外側の build.gradle ファイル

次のファイルは、リポジトリのアップグレード時に最新の Python テンプレートファイルとマージされます。共通するキーがある場合は、Python テンプレート側のバージョンが選択されます。

  • gradle.properties
  • versions.properties

残りのファイルは、最新の Python テンプレートのバージョンのファイルと一致するように、アップグレードによって上書きされます。

pipeline.py

このファイルでは、プロジェクトの Pipeline を定義します。Pipeline は、データ変換に関連付けられた Transform オブジェクトのレジストリです。デフォルトの src/myproject/pipeline.py ファイルは次のとおりです。

Copied!
1 2 3 4 from transforms.api import Pipeline from myproject import datasets my_pipeline = Pipeline() my_pipeline.discover_transforms(datasets)

デフォルトの pipeline.py ファイルは、自動登録を使用して、プロジェクトの Pipeline に Transform オブジェクトを追加します。自動登録では、プロジェクトの datasets パッケージ内にあるすべての Transform オブジェクトが発見されます。そのため、変換ロジックが datasets フォルダー内に含まれないようにプロジェクトの構造を変更した場合は、必ず src/myproject/pipeline.py ファイルを適切に更新してください。

または、手動登録を使用して、各 Transform オブジェクト、つまり @transform でデコレートした各関数を、プロジェクトの Pipeline に自分で追加することもできます。手動登録が必要なワークフローでない限り、自動登録を使用します。Pipeline の背景について詳しくは、Pipelineを参照してください。

setup.py

このファイルでは、プロジェクトの Pipeline に関連付けられた、root という名前の transforms.pipelines エントリーポイントを定義します。これにより、Python トランスフォームがプロジェクトの Pipeline を発見できるようになります。デフォルトの src/setup.py ファイルは次のとおりです。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 #!/usr/bin/env python """Python プロジェクトのセットアップスクリプトです。""" import os from setuptools import find_packages, setup setup( name=os.environ["PKG_NAME"], version=os.environ["PKG_VERSION"], description="Python data transformation project", author="{{REPOSITORY_PROJECT_NAME}}", packages=find_packages(exclude=["contrib", "docs", "test"]), # 依存関係は代わりに conda_recipe/meta.yaml で指定してください。 install_requires=[], entry_points={"transforms.pipelines": ["root = myproject.pipeline:my_pipeline"]}, )

ファイルの先頭にある #!/usr/bin/env python 行はそのまま残してください。Foundry は、プロジェクトのソースディレクトリを探す際に、この行を使用して setup.py を識別します。

デフォルトのプロジェクト構造を変更する場合は、src/setup.py ファイルの内容も変更する必要がある場合があります。詳しくは、transforms.pipelines エントリーポイントについて説明するセクションを参照してください。

examples.py

このファイルには、データ変換コードを記述します。デフォルトの src/myproject/datasets/examples.py ファイルのコメントを解除したものは次のとおりです。

Copied!
1 2 3 4 5 6 7 8 9 from transforms.api import Input, Output, transform, LightweightInput, LightweightOutput @transform.using( output_dataset=Output("/path/to/output/dataset"), input_dataset=Input("/path/to/input/dataset"), ) def compute(input_dataset: LightweightInput, output_dataset: LightweightOutput) -> None: output_dataset.write_table(input_dataset.polars(lazy=True))

サンプルコードのコメントを解除した後、/path/to/input/dataset を入力データセットのフルパスに、/path/to/output/dataset を出力データセットのフルパスに置き換えることができます。データ変換が複数のデータセットに依存する場合は、入力データセットを追加で指定できます。compute 関数を更新して、入力データセットを出力データセットに変換するコードを記述できます。また、1つの Python ファイルで複数の出力データセットを作成できることにも留意してください。

サンプルコードは Polars コンピュートエンジンを使用しています。ほかのコンピュートオプションを使用するようにコードを変更することもできます。コンピュートオプションの詳細についてはコンピュートエンジンを、すべてのエンジンのコード例については入門を参照してください。

入力データセット、出力データセット、および変換ロジックを記述する Transform オブジェクトの作成について詳しくは、Transform について説明するセクションを参照してください。

meta.yaml

conda のビルド Recipe は、conda ↗ パッケージのビルドに必要なすべてのメタデータとスクリプトを含むディレクトリです。ビルド Recipe 内のファイルの1つである meta.yaml には、すべてのメタデータが含まれています。このファイルの構造の詳細については、meta.yaml ファイルに関する conda ドキュメント ↗を参照してください。 デフォルトの conda_recipe/meta.yaml ファイルは次のとおりです。

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 # パッケージの実行時の要件を変更する必要がある場合は、 # このファイルの 'requirements.run' セクションを更新します。 package: name: "{{ PACKAGE_NAME }}" version: "{{ PACKAGE_VERSION }}" source: path: ../src requirements: # パッケージのビルドに必要なツールです。これらのパッケージはビルドシステム上で実行され、 # リビジョン管理システム (Git, SVN)、make ツール (GNU make, Autotool, CMake)、 # コンパイラー(実クロス、擬似クロス、またはクロスコンパイルしない場合はネイティブ)、および任意のソースプリプロセッサーなどが含まれます。 # https://docs.conda.io/projects/conda-build/en/latest/resources/define-metadata.html#build build: - python 3.9.* - setuptools # パッケージの実行に必要なパッケージです。これらは、パッケージがインストールされるたびに # 自動的にインストールされる依存関係です。 # https://docs.conda.io/projects/conda-build/en/latest/resources/define-metadata.html#run run: - python 3.9.* - transforms {{ PYTHON_TRANSFORMS_VERSION }} - transforms-expectations - transforms-verbs build: script: python setup.py install --single-version-externally-managed --record=record.txt

Python トランスフォームのプロジェクトで追加のビルド依存関係が必要な場合は、パッケージタブで利用可能なパッケージを探し、Python ライブラリの共有に関するドキュメントの説明に従って、meta.yml ファイルに自動的に追加できます。このステップでは、インポートしようとしているパッケージの提供元チャネルが自動的に検出され、取得元リポジトリとして追加されます。

このファイルの「requirements」セクションを手動で更新することもできます。ただし、利用できないパッケージやバージョンを要求してしまい、その結果リポジトリのチェックが失敗するリスクがあるため、手動での更新は避けることを強く推奨します。依存関係を追加する際は、その依存関係に必要なパッケージが利用可能であることを確認してください。

「requirements」以外のセクションを変更する必要はほとんどありません。

サポート対象の Python 3 バージョン

Palantir は、Python Software Foundation のサポート終了スケジュールに従って、アクティブなバージョンの Python をサポートしています。詳細については、Python バージョンのサポートページを参照してください。

使用例:

Copied!
1 2 3 4 5 6 7 8 9 requirements: build: - python 3.9.* - setuptools # パッケージの実行に必要な追加のパッケージです。 run: - python 3.9.* - transforms {{ PYTHON_TRANSFORMS_VERSION }}
  • build セクションと run セクションの Python の依存関係が同一であることを必ず確認してください。Python の依存関係が一致していないと、意図しない結果や失敗につながる可能性があります。
  • Python のバージョン指定では、python >=3.9 や python >3.9,<=3.10.11 のような範囲指定に対応していません。

ランタイムのバージョンを固定する

トランスフォームで特定のライブラリバージョンに固定する必要があり、推奨されるパッケージタブを使わずに手動で追加したい場合は、requirements ブロック内でライブラリ名とともにバージョンを明示的に指定できます。固定の例を以下に示します。

Copied!
1 2 3 4 5 6 7 requirements: run: # 以下では、明示的なバージョンに固定します - mylibrary 1.0.1 # 以下では、最大バージョン(そのバージョン以下)を指定します: - scipy <=1.4.0

注:

  • 演算子の後にスペースを入れることはできません。たとえば、scipy <= 1.4.0 は CI チェックに失敗します。
  • Foundry では、バージョン指定の演算子 >= にはまだ対応していません。

pip で管理される依存関係を使用する

トランスフォームで必要な特定のライブラリが Conda では利用できず、pip ↗ を使ってインストールすれば利用できる場合は、追加の pip セクションで宣言できます。この依存関係は Conda 環境に追加でインストールされます。pip の依存関係を追加する例を以下に示します。

Copied!
1 2 3 4 5 6 7 8 9 10 11 requirements: build: - python 3.9.* - setuptools run: - python 3.9.* - transforms {{ PYTHON_TRANSFORMS_VERSION }} pip: - pypicloud

注:

  • pip セクションに追加した依存関係は、run セクションのパッケージから作成される Conda 環境に追加でインストールされます。そのため、run または build を削除すると失敗します。
  • pip セクションは Python トランスフォームのリポジトリでのみ使用でき、Python ライブラリでは使用できません。