문서

한국어

English · Core guides

한국어

English · Core guides

테마

Function과 Component API ​

먼저 기능을 어디까지 재사용할지 정합니다. 현재 production Canvas에서는 지원되는 Function·built-in target을 배치하고, 기존 V1 Component target은 read-only `unsupported`로 보존합니다.

Decorator와 SDK data type은 @px.function, @px.component, px.Results처럼 px.로 시작합니다. 정의를 배치하는 작업은 특정 Flow가 소유하므로 flow.node(...)를 사용합니다.

문법별 페이지 ​

  • plain Python def · Function은 helpers=[...]로 선언해 revision에 싣고 Component는 module에 두는 helper
  • @px.function · 여러 Flow가 공유하는 Function
  • @px.component · 현재 companion metadata와 annotation-derived port를 등록하는 Component; V2 host Node와 별도 settings/rich surface는 successor 계획
필요한 범위작성 형태Studio에서 배치한 모습
Project가 소유하는 Python 계산@px.function(key=...)Function Reference Node
Component companion metadata 등록@px.component현재 read-only unsupported; V2는 host-owned declarative Node만 계획
port가 전달할 구조화 값 정의@px.recordNode가 아닌 data schema

다중 선언 container와 host-rendered presentation은 Node presentation과 third-party UI의 contract_only V2입니다.

현재 installer에는 안전한 inactive quarantine이 없습니다. exact ProjectScope data-path isolation은 구현됐지만 authenticated-principal authorization, execution-trust closure와 production gate가 닫히기 전에는 production third-party Component install admission과 activation을 열지 않습니다. V2는 package UI를 마운트하지 않고 host-owned component.declarative@2만 사용하며, settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. rich surface는 RFC-016의 component-rich-surface-declaration@1이 소유합니다.

plain Python def ​

Function 또는 Component body에서 반복되는 계산을 helper로 나눕니다. Function의 helper는 @px.function(..., helpers=[...])로 선언해야 그 revision에 저장되어 실행 시 존재합니다. helper는 독립 실행 계약과 stable key가 없으므로 flow.node(...)에 직접 전달하지 않습니다.

python
from pipelinexlab import px


class UtilizationResults(px.Results):
    value: float


def utilization_ratio(demand: float, resistance: float) -> float:
    return demand / resistance

현재 실행 가능한 Node target은 아래 @px.function으로 명시합니다. @px.component는 companion metadata이며 V1 wire/internal fixture의 target shape와 future post-closure placement에 사용합니다.

@px.function ​

python
@px.function(key=..., version=..., description=..., policy=..., capabilities=...)

여러 Flow에서 재사용하고 version별 영향 범위를 관리할 계산 Function을 등록합니다.

python
@px.function(
    key="calculate_utilization",
    version="1.0.0",
    description="Calculates demand-to-resistance utilization.",
)
def calculate_utilization(demand: float, resistance: float) -> UtilizationResults:
    return UtilizationResults(value=demand / resistance)

Function key는 key="calculate_utilization"이 소유합니다. Python symbol 이름을 바꿔도 key는 유지됩니다. Studio의 Definitions → Functions에서 source, version, input/result와 사용 중인 Node를 확인합니다.

python
check = flow.node("utilization_check", calculate_utilization)

배치된 Node는 shared source를 읽기 전용으로 보여 줍니다. Function을 변경하면 사용 중인 Node의 영향을 함께 검토하고, 한 Node만 다르게 만들 때 Function을 복제해 새 version 또는 새 key로 분기합니다.

@px.component ​

python
@px.component(key=..., label=..., description=..., category=None, subcategory=None)

portable Component declaration과 결합할 key·port shape의 companion metadata symbol을 정의합니다. 현재 decorator는 Node body, settings schema, executor나 editor presentation을 만들지 않습니다.

python
class ResultBadgeResults(px.Results):
    text: str


@px.component(
    key="result_badge",
    label="Result badge",
    description="Displays one numeric result as a compact badge.",
    category="review",
    subcategory="metrics",
)
def result_badge(
    value: float,
) -> ResultBadgeResults:
    ...  # metadata companion symbol; V1 fixture executor는 별도 artifact

다음은 Component package public module과 V1 wire/internal fixture placement의 대응 예입니다. 이 예제는 contract_only이며 현재 SDK에서 실행할 수 없습니다. production third-party 설치·배치·실행 workflow가 아닙니다.

python
from result_tools.components import result_badge

flow = px.Flow(
    "result_summary",
    label="Result summary",
    description="Displays one calculation result.",
)
value = flow.input("value", float, description="Result to display.")
badge = flow.node(
    "utilization_badge",
    result_badge,
    settings={"precision": 2},
)
flow.connect(value, badge.inputs.value)
flow.result(
    "text",
    badge.results.text,
    description="Formatted result badge text.",
)

Component 제작 metadata, 현재 차단선과 public import를 함께 정하는 방법은 Component 작성과 container 계약에서 이어집니다.

같이 보기 ​