Python transforms 저장소 구조

기본 Python transforms 템플릿은 변환 코드, Pipeline 등록과 Conda 패키지 정의를 나눕니다.

transforms-python/
  conda_recipe/
    meta.yaml
  src/
    myproject/
      __init__.py
      datasets/
        __init__.py
        examples.py
      pipeline.py
    setup.cfg
    setup.py

Files의 설정 톱니바퀴에서 Show hidden files and folders를 켜면 추가 빌드 파일을 볼 수 있습니다. 템플릿이 관리하는 숨김 파일의 임의 변경은 지원하지 않는 동작이나 업그레이드 충돌을 만들 수 있습니다.

업그레이드의 파일 처리

CI 설정 같은 생성 파일에 영구 사용자 로직을 넣기보다 지원되는 설정 경로를 사용합니다.

pipeline.py

Pipeline은 변환의 등록부입니다. 기본 src/myproject/pipeline.py는 datasets 패키지를 자동 발견합니다.

from transforms.api import Pipeline
from myproject import datasets

my_pipeline = Pipeline()
my_pipeline.discover_transforms(datasets)

코드를 다른 패키지로 옮기면 발견 대상도 바꿔야 합니다. 수동 등록이 필요한 경우에는 Pipeline 계약의 add_transforms를 사용할 수 있습니다.

setup.py

src/setup.py는 패키지와 Pipeline entry point를 노출합니다. 맨 위의 #!/usr/bin/env python은 Foundry가 소스 디렉터리를 찾으며 setup.py를 식별하는 데 사용하므로 유지해야 합니다.

#!/usr/bin/env python
"""Python transform package metadata."""

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="Example Project",
    packages=find_packages(exclude=["contrib", "docs", "test"]),
    install_requires=[],
    entry_points={
        "transforms.pipelines": ["root = myproject.pipeline:my_pipeline"]
    },
)

PKG_NAME과 PKG_VERSION은 템플릿의 패키지 빌드 환경이 제공하는 값입니다. 위 author는 예시 이름이며 실제 프로젝트의 메타데이터를 사용합니다. 패키지 의존성은 install_requires 대신 Conda recipe에서 관리합니다.

Entry point의 root는 등록 이름, myproject.pipeline은 모듈, my_pipeline은 그 모듈의 Pipeline 객체입니다. 디렉터리를 바꾸면 이 연결도 함께 바꿉니다.

변환 모듈

src/myproject/datasets/examples.py에는 실제 변환을 둡니다. 다음은 입력 표를 lazy Polars로 읽어 그대로 출력 데이터셋에 복사하는 예입니다. 가상 경로를 실제 자산으로 바꿉니다.

from transforms.api import Input, LightweightInput, LightweightOutput, Output, transform


@transform.using(
    output_dataset=Output("/Example Project/Outputs/copied_table"),
    input_dataset=Input("/Example Project/Inputs/table"),
)
def compute(input_dataset: LightweightInput, output_dataset: LightweightOutput) -> None:
    output_dataset.write_table(input_dataset.polars(lazy=True))

하나의 Python 파일에 여러 변환을 정의할 수 있습니다. 실제 계산과 엔진 선택은 변환 API의 계약을 따릅니다.

Conda recipe

conda_recipe/meta.yaml은 패키지 이름, 버전, 소스 위치와 build 및 run 의존성을 정의합니다. 다음은 Python 3.12와 Polars를 사용하는 구성 예입니다.

package:
  name: "{{ PACKAGE_NAME }}"
  version: "{{ PACKAGE_VERSION }}"

source:
  path: ../src

requirements:
  build:
    - python 3.12.*
    - setuptools
  run:
    - python 3.12.*
    - transforms {{ PYTHON_TRANSFORMS_VERSION }}
    - transforms-expectations
    - transforms-verbs
    - polars

build:
  script: python setup.py install --single-version-externally-managed --record=record.txt

중괄호 값들은 템플릿 빌드가 채우는 변수입니다. build는 패키지를 만드는 도구의 환경, run은 설치 후 실제로 실행할 환경입니다. 두 곳의 Python 버전은 동일해야 합니다.

Python을 고정할 때는 지원하는 major.minor 범위를 사용합니다. python >=3.9나 python >3.9,<=3.10.11 같은 범위식은 이 Python 버전 설정 경로에서 지원하지 않습니다. 종료한 버전 대신 지원 일정에 맞는 버전을 선택합니다.

패키지 추가와 pin

가능하면 Libraries 검색 UI로 패키지를 추가합니다. 이 경로는 필요한 backing repository와 프로젝트 참조를 찾고 recipe를 갱신합니다. 직접 수정하면 사용할 수 없는 패키지나 버전을 요청하여 checks가 실패할 수 있습니다.

수동 버전 지정은 패키지 이름 뒤에 버전을 쓰거나 <=와 버전을 이어 쓰는 방식입니다. 연산자 뒤에는 공백을 넣지 않습니다. 이 recipe의 수동 설정에서는 >= 지원을 전제로 하지 말고 UI가 제공하는 선택 조건을 사용합니다. Workbook의 일반 Conda 버전 입력과 모든 제약을 동일하게 취급하지 않습니다.

대부분은 requirements 밖의 항목을 바꿀 필요가 없습니다.

Pip 의존성

Conda로 제공되지 않고 pip로만 설치할 수 있는 패키지는 requirements.pip에 넣을 수 있습니다. 예를 들어 기존 requirements에 다음 키를 병합합니다.

requirements:
  pip:
    - pypicloud

이 조각으로 기존 recipe를 덮어쓰지 않습니다. 기존 build와 run은 반드시 유지해야 하며, pip 패키지는 run에서 해석한 Conda 환경 위에 설치됩니다.

이 pip 구역은 Python transforms 저장소에서만 사용할 수 있고 공유 Python library 저장소에서는 사용할 수 없습니다.