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} 형식으로 반환합니다.

사용 가능한 패키지

파이프라인 Python 환경에서 주로 사용하는 데이터 처리·공간 분석 라이브러리입니다.

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

추가 패키지

기본 환경에 없는 패키지는 코드의 패키지 항목에 입력합니다. 설치가 허용된 패키지는 관리자에게 확인합니다.

코드 예시

데이터 필터링

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​

출력 키​

사용 가능한 패키지​

코드 예시​

데이터 필터링​

여러 입력 받기​

옵션 사용하기​

디버깅 팁​

관련 문서​