`@px.function`

@px.function은 Canvas에서 실행할 계산을 이름과 version이 있는 Function으로 등록합니다. Project 안에서만 쓰는 계산과 여러 Flow가 공유하는 계산 모두 같은 문법을 사용합니다.

무엇을 만드나요?

입력, 결과, 계산 코드와 version이 함께 관리되는 Function definition을 만듭니다. Decorator를 붙이는 것만으로 Node가 생기거나 계산이 실행되지는 않습니다.

Studio에서는 어디에 보이나요?

Definitions → Functions에서 source, version, input/result와 사용 중인 Node를 확인합니다. flow.node(...)로 배치하면 source가 읽기 전용인 Function Reference Node로 보입니다.

문법

python

@px.function(*, key, version, description, policy=..., capabilities=..., helpers=..., dependencies=...)

최소 예제

python

from pipelinexlab import px


class CheckResults(px.Results):
    utilization: float


@px.function(
    key="check_resistance",
    version="1.0.0",
    description="Checks demand against resistance.",
)
def check_resistance(demand: float, resistance: float) -> CheckResults:
    return CheckResults(utilization=demand / resistance)


flow = px.Flow(
    "resistance_check",
    label="Resistance check",
    description="Checks demand against resistance.",
)
check = flow.node("resistance_check", check_resistance)

함수 본문은 실제 계산 과정입니다. -> CheckResults는 계산식이 아니라 이 Function이 반환할 이름 있는 result 묶음의 타입 계약입니다. 마지막 return CheckResults(...)가 계산한 값을 그 타입의 utilization result port에 넣습니다. 따라서 Studio에는 함수 본문의 각 Python 문장 대신 Function Reference Node 하나와 demand, resistance, utilization port가 보입니다.

매개변수

이름	설명
`key`	Function을 참조하는 stable `lower_snake_case` 이름
`version`	Function 계약과 계산 의미의 SemVer
`description`	무엇을 계산하고 언제 쓰는지 설명하는 문장
`policy`	cache, retry, timeout과 병렬 안전성 같은 실행 정책
`capabilities`	파일, network, secret, GPU처럼 요청할 수 있는 권한의 상한
`helpers`	이 Function이 부르는 일반 `def` 목록. 선언한 helper의 소스는 같은 Function revision에 저장되어 실행 시 존재합니다
(미집행 거부)	`policy`·`capabilities`의 기본값 외 선언은 현재 저장 시 이름 있는 거부를 받습니다
`dependencies`	`{package: exact_version}` 고정 목록. revision의 dependency lock에 저장되고, pin이 바뀌면 새 revision이 됩니다

외부 Python 패키지

dependencies={"package-name": "1.2.3"} 선언을 저장할 수 있습니다. 저장은 패키지를 설치하거나 실행 환경을 만드는 작업이 아닙니다. 실행하려면 host가 해당 패키지와 전이 의존성을 포함한 검증된 보관 환경을 준비해야 합니다. 현재 이 실행 경로는 Linux/glibc CPython의 version 2 환경 lock을 사용하며, 환경 등록·자동 설치용 공개 SDK API는 아직 제공하지 않습니다.

Runtime은 직접 Function과 중첩 Subflow 안의 Function 모두에 대해 exact dependency pin을 Run의 환경과 대조합니다. 패키지 누락·버전 불일치·보관 환경 부재는 source 실행 전에 거절합니다. Run.diagnostics의 PX_EXECUTION_INFRASTRUCTURE_FAILED에서 params["reason"]을 확인합니다. 대표 값은 dependencyMissing, dependencyVersionMismatch, environmentNotPinned, environmentCaptureRequired입니다. 일반 사용자 예외의 PX_FUNCTION_FAILED와 구분합니다.

패키지 이름은 대소문자와 ., _, -를 정규화하여 대조합니다. 정규화했을 때 같은 이름을 두 번 선언하면 저장이 거절됩니다. 기존 Function revision의 원본 이름·bytes를 다시 쓰지는 않습니다. 자세한 환경 의미는 실행과 결과를 따릅니다.

Python 함수 이름은 구현 symbol이고 input/result는 함수 선언에서 읽습니다. -> ResultsType은 반환 shape를 선언하고 return ResultsType(...)은 실행 시 실제 result 값을 만듭니다. 저장된 Flow와 Definitions는 Python symbol 이름이 아니라 명시한 key로 Function을 참조합니다.

반환값과 handle

Decorated symbol은 Python 함수로 호출할 수 있는 계산 target이며 Function metadata도 함께 가집니다. flow.node(...)에 전달하면 Function Reference Node handle을 반환합니다.

규칙과 진단

key, version과 description은 필수입니다.
Python 구현 symbol을 바꿔도 key가 같으면 Function identity는 유지됩니다.
Function version은 유효한 SemVer여야 하며 Component package version과 별도로 관리합니다.
저장·배포된 (package, key, version)의 source, contract와 digest는 immutable입니다. body, port, 실행 정책 또는 계산 의미를 바꾸면 새 Function version과 revision을 만듭니다.
Function을 변경하면 Definitions에서 사용 중인 Node의 영향을 확인합니다. 한 Node만 다르게 만들려면 Function을 복제해 새 key 또는 version으로 분기합니다.
선언만으로 Canvas Node를 만들지 않습니다. 실제 배치는 flow.node(...)에서 합니다.
Decorator 없는 일반 def는 Function body에서 호출하는 helper이며 flow.node(...)에 직접 배치하지 않습니다.
실행 중 처리하지 못한 실패는 PX_FUNCTION_FAILED 진단으로 정규화됩니다.

@px.function ​

무엇을 만드나요? ​

Studio에서는 어디에 보이나요? ​

문법 ​

최소 예제 ​

매개변수 ​

외부 Python 패키지 ​

반환값과 handle ​

규칙과 진단 ​

다음 ​