Python 코드 참조

D.Hub의 Python 코드는 데이터를 변환하고 분석합니다. 기본 데이터 처리 라이브러리는 Polars입니다.

적용 위치

컬렉션의 코드에서 Python 코드를 만들고 관리합니다.
파이프라인에 Python 코드 노드를 추가한 뒤 기존 코드 자산을 선택하거나 새 코드를 작성합니다.
코드의 실행 결과는 파이프라인의 다음 노드로 전달됩니다.

실행 계약

Python 코드 노드는 run 함수를 진입점으로 사용합니다. 각 입력은 Polars DataFrame이며 반환값은 출력별 DataFrame을 담은 딕셔너리입니다. 매개변수 이름과 반환 키는 코드 노드의 옵션 탭에 설정한 입력·출력 키와 일치해야 합니다.

import polars as pl

def run(input, *, options=None, contexts=None):
    # input   : Polars DataFrame (입력 데이터)
    # options : dict (사용자 정의 옵션)
    # contexts: dict (단계 간 공유 값)
    output = input.with_columns(
        (pl.col("value") * 2).alias("doubled_value")
    )
    return {"output": output}

이 예제의 input과 output은 새 연결에서 사용할 수 있는 기본 이름입니다. 옵션 탭에서 키를 바꿨다면 함수와 반환값도 같은 이름으로 바꿉니다.

입력 키

각 입력은 옵션 탭의 입력 키와 같은 이름의 매개변수로 전달됩니다.
새 단일 입력에는 input이 기본 이름으로 제안될 수 있습니다. 연결 키를 바꾸면 run의 매개변수도 바꿉니다.
입력이 여러 개인 노드는 각 입력 키를 별도 매개변수로 받습니다. 여러 입력 받기에서 예시를 확인합니다.

옵션 `options`

코드 노드의 스텝 옵션에 입력한 값이 options 딕셔너리로 전달됩니다.
실행마다 달라지는 날짜나 필터 조건을 옵션으로 전달합니다.

공유 값 `contexts`

단계 간 공유 값이 contexts 딕셔너리로 전달됩니다.
contexts는 실행할 때 항상 전달됩니다. 사용하지 않더라도 키워드 전용 매개변수로 선언합니다.

출력 키

반드시 딕셔너리를 반환해야 하며 각 키는 옵션 탭의 출력 키와 같아야 합니다. 값은 Polars DataFrame입니다. 새 단일 출력에는 output이 기본 이름으로 제안될 수 있습니다.

반환 형식 주의

return output처럼 DataFrame을 직접 반환하면 오류가 발생합니다. 예를 들어 출력 키가 output이면 {"output": output} 형식으로 반환합니다.

사용 가능한 패키지

기본 파이프라인 이미지에 포함된 주요 데이터 처리·공간 분석 라이브러리입니다. 전체 패키지 목록이나 버전 목록은 아닙니다. 사용자 지정 이미지는 포함된 패키지가 다를 수 있습니다.

패키지	용도
`polars`	DataFrame 처리(기본 라이브러리)
`pandas`	범용 DataFrame 처리
`pyarrow`	Apache Arrow 컬럼형 데이터 처리
`numpy`	수치 계산
`h3`	H3 육각형 공간 인덱싱
`pyproj`	좌표계 변환
`rdflib`	RDF/온톨로지 데이터 처리

포털은 현재 실행 이미지에 설치된 패키지의 정확한 버전 목록을 표시하지 않습니다. 특정 버전이 필요하면 관리자나 이미지 제공자에게 해당 이미지의 패키지 목록과 버전을 확인합니다. geopandas는 기본 제공 패키지가 아니므로 필요하면 추가로 선언합니다.

추가 패키지

기본 환경에 없는 패키지는 파이프라인의 설정 → 옵션 → Python 패키지에 한 줄에 하나씩 입력합니다. 각 항목은 패키지명==버전으로 정확한 버전을 지정합니다. API에서는 파이프라인의 options.packages 배열에 선언합니다. 코드 자산이나 개별 스텝의 옵션에 선언한 패키지는 설치 대상이 아닙니다.

기본 이미지에 포함된 패키지는 추가 선언 없이 사용합니다. 설치 시점과 호환성 확인 방법은 파이프라인 설정에서 확인합니다.

코드 예시

데이터 필터링

import polars as pl

def run(input, *, options=None, contexts=None):
    return {"output": input.filter(
        (pl.col("status") == "active") & (pl.col("age") >= 18)
    )}

여러 입력 받기

입력 연결이 여러 개인 노드는 옵션 탭에 설정한 입력 키를 매개변수 이름으로 받습니다. 다음 예시는 입력 키가 orders와 customers, 출력 키가 output인 경우입니다. options와 contexts는 입력 매개변수 뒤에 키워드 전용 매개변수로 선언합니다.

import polars as pl

def run(orders, customers, *, options=None, contexts=None):
    output = orders.join(customers, on="customer_id", how="left")
    return {"output": output}

옵션 사용하기

import polars as pl

def run(input, *, options=None, contexts=None):
    threshold = float(options.get("threshold", 100))
    return {"output": input.filter(pl.col("value") > threshold)}

일반적인 DataFrame 변환과 함수 사용법은 Polars 사용자 가이드에서 확인합니다. Pandas·GIS 패키지를 사용하더라도 D.Hub의 run 입력·출력 계약은 같습니다.

디버깅 팁

print() 출력은 파이프라인 실행 로그에서 확인합니다.
중간 결과는 print(input.head(5)), 스키마는 print(input.schema)로 확인합니다.
오류가 발생하면 트레이스백이 실행 로그에 표시됩니다.

적용 위치​

실행 계약​

입력 키​

옵션 options​

공유 값 contexts​

출력 키​

사용 가능한 패키지​

코드 예시​

데이터 필터링​

여러 입력 받기​

옵션 사용하기​

디버깅 팁​

관련 문서​