プロジェクト構造

読み進める前に、はじめにのガイドを確認してください。また、このページでは、セットアップ済みの 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 は、これらの隠しファイルに独自の変更を加えたリポジトリをサポートしません。

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

• pipeline.py
• setup.py
• examples.py
• meta.yaml

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

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

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

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

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

• gradle.properties
• versions.properties

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

pipeline.py

このファイルでは、データ変換に関連する Transform オブジェクトを登録する、プロジェクトの Pipeline を定義します。デフォルトの 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 ファイルを適切に更新してください。

また、手動登録を使用して、プロジェクトの Pipeline に Transform オブジェクトを個別に明示的に追加することもできます。Pipeline に Transform オブジェクトを個別に明示的に追加する必要があるワークフローでない限り、自動登録の使用を推奨します。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 で、このファイルにはすべてのメタデータが含まれます。このファイルの構造について詳しくは、conda の meta.yaml ファイルに関するドキュメント ↗を参照してください。 デフォルトの 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 }}

実行時のバージョンを固定する

トランスフォームで特定のライブラリバージョンを固定する必要があり、推奨されるパッケージタブを使わずに手動で追加する場合は、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 ライブラリでは使用できません。