mdtpy 0.2.2__tar.gz → 0.2.4__tar.gz

mdtpy-0.2.4/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: mdtpy
+Version: 0.2.4
+Summary: A Python client library for the MDT (Manufacturing Digital Twin) Platform.
+Author-email: Kang-Woo Lee <kwlee@etri.re.kr>
+Keywords: MDT,AAS,digital-twin,manufacturing,basyx
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: basyx-python-sdk<3.0.0,>=2.0.0
+Requires-Dist: dataclass-wizard<1,>=0.22
+Requires-Dist: isodate>=0.7.2
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: pandas>=2.3.3
+Requires-Dist: requests>=2.32.5
+Requires-Dist: typing_extensions>=4.2.0
+Requires-Dist: urllib3<3.0.0,>=2.6.2
+
+# mdtpy
+
+MDT(Manufacturing Digital Twin) 플랫폼을 위한 Python 클라이언트 라이브러리.
+Asset Administration Shell(AAS) 표준을 기반으로 MDT Instance Manager 및 개별
+FA³ST 인스턴스에 HTTP REST로 접근하는 API를 제공한다.
+
+내부적으로 [`basyx-python-sdk`](https://pypi.org/project/basyx-python-sdk/)를
+사용해 AAS 모델(`Property`, `SubmodelElementCollection`, `SubmodelElementList`,
+`File`, `Range`, `MultiLanguageProperty`, `Operation`, `TimeSeries` 등)을 다룬다.
+
+## 요구 사항
+
+- Python 3.10 이상
+- [uv](https://docs.astral.sh/uv/) (의존성/빌드 관리)
+
+## 설치
+
+```bash
+uv sync                  # 런타임 의존성
+make install-dev         # 개발 의존성(pytest)까지 함께 설치
+```
+
+소스 레이아웃은 `src/mdtpy/`이며, `src/`가 Python path에 등록되어 있다
+(`.vscode/settings.json`).
+
+## 빠른 시작
+
+```python
+import mdtpy
+
+# 1. MDT Instance Manager에 접속
+manager = mdtpy.connect("http://localhost:12985/instance-manager")
+
+# 2. 인스턴스 가져오기 / 시작
+instance = manager.instances['my_twin']
+if not instance.is_running():
+    instance.start()
+
+# 3. 파라미터 읽기/쓰기
+param = instance.parameters['Status']
+print(param.read_value())
+param.update_value('Running')
+
+# 4. Operation 호출
+op = instance.operations['Inspect']
+result = op.invoke(Image=instance.parameters['UpperImage'])
+op.output_arguments.update_value(result)
+
+# 5. 시계열 데이터
+ts = instance.timeseries['WelderAmpereLog'].timeseries()
+df = ts.segments['Latest'].records_as_pandas()
+```
+
+상세 사용법은 [`doc/programming_guide.md`](doc/programming_guide.md) 참조.
+
+## 주요 모듈
+
+| 모듈 | 역할 |
+|---|---|
+| `mdtpy.instance` | `connect()`, `MDTInstanceManager`, `MDTInstance`, 컬렉션, 폴러 |
+| `mdtpy.reference` | `ElementReference` 추상화 (`DefaultElementReference`, `LazyElementReference`) |
+| `mdtpy.parameter` | `MDTParameter`, `MDTParameterCollection` |
+| `mdtpy.submodel` | `SubmodelService`, `SubmodelServiceCollection`, `SubmodelElementCollection` |
+| `mdtpy.operation` | `OperationSubmodelService`, `Argument`, `ArgumentList` |
+| `mdtpy.timeseries` | `TimeSeriesService` (pandas 통합) |
+| `mdtpy.value` | SME ↔ Python 값 ↔ 서버 wire JSON 변환 |
+| `mdtpy.descriptor` | 불변 dataclass 디스크립터, semantic_id 기반 분류 |
+| `mdtpy.aas_misc` | AAS wire 포맷 dataclass (`Endpoint`, `OperationVariable` 등) |
+| `mdtpy.fa3st` | 개별 FA³ST 인스턴스용 HTTP 헬퍼 (`call_get`/`call_put`/...) |
+| `mdtpy.http_client` | Instance Manager용 응답 파서, 공통 예외 변환 |
+| `mdtpy.exceptions` | `MDTException` 계층 |
+| `mdtpy.utils` | ISO 8601 / timedelta / SME→Python 변환 헬퍼 |
+| `mdtpy.airflow` | Apache Airflow DAG 통합 (선택, 자동 import되지 않음) |
+| `mdtpy.basyx.serde` | basyx-python-sdk 직렬화 래퍼 |
+
+## 개발
+
+### 테스트 실행
+
+```bash
+make test              # 전체 pytest suite
+make test-cov          # 커버리지 보고서 포함
+```
+
+또는 직접 실행:
+
+```bash
+uv run --env-file .env pytest tests/test_instance.py
+uv run --env-file .env pytest tests/test_instance.py::TestMDTInstanceCollection -v
+```
+
+> **참고**: ROS2(`/opt/ros/humble/...`)를 source한 셸에서는 시스템
+> `launch_pytest` 플러그인이 자동 로드되어 `yaml` 누락으로 충돌한다. `Makefile`
+> 과 `.env`가 `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`을 주입하여 이를 우회한다.
+> ROS가 source되지 않은 셸이라면 `uv run pytest`만으로도 충분하다.
+
+`tests/` 폴더의 단위 테스트는 외부 서버 의존 없이 mock으로 동작한다
+(300+ tests). `src/samples/sample_*.py` 스크립트들은 **실서버 대상 사용 예제 /
+스모크 테스트**이므로 별도 환경에서 실행한다 (예: `python src/samples/sample_reference.py`).
+
+### 코드 스타일
+
+- 코드 주석/docstring: 한국어 (평서문 "~한다")
+- 로깅/예외 메시지: 영어
+- import 순서: `__future__` → `typing` → 표준 → 서드파티 → 로컬
+- 타입 힌트: built-in 우선 (`list`/`dict`/`tuple`), `Optional[X]` 권장
+- 들여쓰기: 4-space
+- 라인 길이: 100자 (신규 코드)
+
+자세한 규칙과 아키텍처는 [`CLAUDE.md`](CLAUDE.md) 참조.
+
+## 빌드
+
+```bash
+uv build               # sdist + wheel을 dist/에 생성
+```

mdtpy-0.2.4/README.md

@@ -0,0 +1,116 @@
+# mdtpy
+
+MDT(Manufacturing Digital Twin) 플랫폼을 위한 Python 클라이언트 라이브러리.
+Asset Administration Shell(AAS) 표준을 기반으로 MDT Instance Manager 및 개별
+FA³ST 인스턴스에 HTTP REST로 접근하는 API를 제공한다.
+
+내부적으로 [`basyx-python-sdk`](https://pypi.org/project/basyx-python-sdk/)를
+사용해 AAS 모델(`Property`, `SubmodelElementCollection`, `SubmodelElementList`,
+`File`, `Range`, `MultiLanguageProperty`, `Operation`, `TimeSeries` 등)을 다룬다.
+
+## 요구 사항
+
+- Python 3.10 이상
+- [uv](https://docs.astral.sh/uv/) (의존성/빌드 관리)
+
+## 설치
+
+```bash
+uv sync                  # 런타임 의존성
+make install-dev         # 개발 의존성(pytest)까지 함께 설치
+```
+
+소스 레이아웃은 `src/mdtpy/`이며, `src/`가 Python path에 등록되어 있다
+(`.vscode/settings.json`).
+
+## 빠른 시작
+
+```python
+import mdtpy
+
+# 1. MDT Instance Manager에 접속
+manager = mdtpy.connect("http://localhost:12985/instance-manager")
+
+# 2. 인스턴스 가져오기 / 시작
+instance = manager.instances['my_twin']
+if not instance.is_running():
+    instance.start()
+
+# 3. 파라미터 읽기/쓰기
+param = instance.parameters['Status']
+print(param.read_value())
+param.update_value('Running')
+
+# 4. Operation 호출
+op = instance.operations['Inspect']
+result = op.invoke(Image=instance.parameters['UpperImage'])
+op.output_arguments.update_value(result)
+
+# 5. 시계열 데이터
+ts = instance.timeseries['WelderAmpereLog'].timeseries()
+df = ts.segments['Latest'].records_as_pandas()
+```
+
+상세 사용법은 [`doc/programming_guide.md`](doc/programming_guide.md) 참조.
+
+## 주요 모듈
+
+| 모듈 | 역할 |
+|---|---|
+| `mdtpy.instance` | `connect()`, `MDTInstanceManager`, `MDTInstance`, 컬렉션, 폴러 |
+| `mdtpy.reference` | `ElementReference` 추상화 (`DefaultElementReference`, `LazyElementReference`) |
+| `mdtpy.parameter` | `MDTParameter`, `MDTParameterCollection` |
+| `mdtpy.submodel` | `SubmodelService`, `SubmodelServiceCollection`, `SubmodelElementCollection` |
+| `mdtpy.operation` | `OperationSubmodelService`, `Argument`, `ArgumentList` |
+| `mdtpy.timeseries` | `TimeSeriesService` (pandas 통합) |
+| `mdtpy.value` | SME ↔ Python 값 ↔ 서버 wire JSON 변환 |
+| `mdtpy.descriptor` | 불변 dataclass 디스크립터, semantic_id 기반 분류 |
+| `mdtpy.aas_misc` | AAS wire 포맷 dataclass (`Endpoint`, `OperationVariable` 등) |
+| `mdtpy.fa3st` | 개별 FA³ST 인스턴스용 HTTP 헬퍼 (`call_get`/`call_put`/...) |
+| `mdtpy.http_client` | Instance Manager용 응답 파서, 공통 예외 변환 |
+| `mdtpy.exceptions` | `MDTException` 계층 |
+| `mdtpy.utils` | ISO 8601 / timedelta / SME→Python 변환 헬퍼 |
+| `mdtpy.airflow` | Apache Airflow DAG 통합 (선택, 자동 import되지 않음) |
+| `mdtpy.basyx.serde` | basyx-python-sdk 직렬화 래퍼 |
+
+## 개발
+
+### 테스트 실행
+
+```bash
+make test              # 전체 pytest suite
+make test-cov          # 커버리지 보고서 포함
+```
+
+또는 직접 실행:
+
+```bash
+uv run --env-file .env pytest tests/test_instance.py
+uv run --env-file .env pytest tests/test_instance.py::TestMDTInstanceCollection -v
+```
+
+> **참고**: ROS2(`/opt/ros/humble/...`)를 source한 셸에서는 시스템
+> `launch_pytest` 플러그인이 자동 로드되어 `yaml` 누락으로 충돌한다. `Makefile`
+> 과 `.env`가 `PYTEST_DISABLE_PLUGIN_AUTOLOAD=1`을 주입하여 이를 우회한다.
+> ROS가 source되지 않은 셸이라면 `uv run pytest`만으로도 충분하다.
+
+`tests/` 폴더의 단위 테스트는 외부 서버 의존 없이 mock으로 동작한다
+(300+ tests). `src/samples/sample_*.py` 스크립트들은 **실서버 대상 사용 예제 /
+스모크 테스트**이므로 별도 환경에서 실행한다 (예: `python src/samples/sample_reference.py`).
+
+### 코드 스타일
+
+- 코드 주석/docstring: 한국어 (평서문 "~한다")
+- 로깅/예외 메시지: 영어
+- import 순서: `__future__` → `typing` → 표준 → 서드파티 → 로컬
+- 타입 힌트: built-in 우선 (`list`/`dict`/`tuple`), `Optional[X]` 권장
+- 들여쓰기: 4-space
+- 라인 길이: 100자 (신규 코드)
+
+자세한 규칙과 아키텍처는 [`CLAUDE.md`](CLAUDE.md) 참조.
+
+## 빌드
+
+```bash
+uv build               # sdist + wheel을 dist/에 생성
+```

mdtpy-0.2.4/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mdtpy"
+version = "0.2.4"
+description = "A Python client library for the MDT (Manufacturing Digital Twin) Platform."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Kang-Woo Lee", email = "kwlee@etri.re.kr" }]
+keywords = ["MDT", "AAS", "digital-twin", "manufacturing", "basyx"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "basyx-python-sdk>=2.0.0,<3.0.0",
+    "dataclass-wizard>=0.22,<1",
+    "isodate>=0.7.2",
+    "jinja2>=3.1.6",
+    "pandas>=2.3.3",
+    "requests>=2.32.5",
+    "typing_extensions>=4.2.0",
+    "urllib3>=2.6.2,<3.0.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["mdtpy*"]
+exclude = ["samples*"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# 참고: ROS2를 source한 쉘에서는 /opt/ros/.../launch_pytest 플러그인이
+# 자동 로드되어 yaml 누락으로 충돌한다. `.env`의 PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
+# 을 uv가 픽업하도록 호출해야 하므로 다음 중 하나를 사용한다.
+#   make test
+#   uv run --env-file .env pytest
+# 또는 셸에 `export UV_ENV_FILE=.env`를 등록하면 `uv run pytest`도 그대로 동작한다.

{mdtpy-0.2.2 → mdtpy-0.2.4}/src/mdtpy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 # SSL 인증서 검증 경고 억제
 import urllib3

mdtpy-0.2.4/src/mdtpy/aas_misc.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Iterable
+from enum import Enum, auto
+
+import json
+import datetime
+from dataclasses import dataclass, field
+from dataclass_wizard import JSONWizard
+
+from basyx.aas import model
+from .basyx import serde as basyx_serde
+from . import utils
+
+
+class SecurityTypeEnum(Enum):
+    """AAS Endpoint의 보안 속성 종류."""
+
+    NONE = auto()
+    RFC_TLSA = auto()
+    W3C_DID = auto()
+
+
+@dataclass(slots=True)
+class SecurityAttributeObject(JSONWizard):
+    """
+    AAS Endpoint에 부여되는 보안 속성 단위.
+
+    Attributes:
+        type (SecurityTypeEnum): 보안 속성 종류.
+        key (str): 속성 키.
+        value (str): 속성 값.
+    """
+    type: SecurityTypeEnum
+    key: str
+    value: str
+
+
+@dataclass(slots=True)
+class ProtocolInformation:
+    """
+    AAS Endpoint의 프로토콜 정보를 나타내는 wire 포맷.
+
+    필드 이름이 camelCase인 것은 서버(JSON) 표기를 그대로 따른 것이다.
+
+    Attributes:
+        href (Optional[str]): 엔드포인트 URL.
+        endpointProtocol (Optional[str]): 프로토콜 이름 (예: "HTTP").
+        endpointProtocolVersion (Optional[str]): 프로토콜 버전 (예: "1.1").
+        subprotocol (Optional[str]): 서브프로토콜 이름.
+        subprotocolBody (Optional[str]): 서브프로토콜 본문.
+        subprotocolBody_encoding (Optional[str]): 서브프로토콜 본문 인코딩.
+        securityAttributes (list[SecurityAttributeObject]): 보안 속성 목록.
+    """
+    href: Optional[str]
+    endpointProtocol: Optional[str] = field(default=None)
+    endpointProtocolVersion: Optional[str] = field(default=None)
+    subprotocol: Optional[str] = field(default=None)
+    subprotocolBody: Optional[str] = field(default=None)
+    subprotocolBody_encoding: Optional[str] = field(default=None)
+    securityAttributes: list[SecurityAttributeObject] = field(default_factory=list)
+
+
+@dataclass(slots=True)
+class Endpoint:
+    """
+    AAS Endpoint (interface + protocolInformation 묶음).
+
+    Attributes:
+        interface (str): 인터페이스 식별자 (예: "SUBMODEL").
+        protocolInformation (ProtocolInformation): 접속 프로토콜 정보.
+    """
+    interface: str
+    protocolInformation: ProtocolInformation
+
+
+@dataclass(slots=True)
+class OperationVariable:
+    """
+    AAS Operation의 입력/출력/입출력 변수를 감싸는 컨테이너.
+
+    내부적으로는 basyx의 `model.SubmodelElement`를 그대로 들고 있으며,
+    JSON 변환은 `basyx_serde`에 위임한다.
+
+    Attributes:
+        value (model.SubmodelElement): 변수의 값을 담은 SubmodelElement.
+    """
+    value: model.SubmodelElement
+
+    @classmethod
+    def from_dict(cls, data: dict) -> OperationVariable:
+        """
+        JSON 객체에서 OperationVariable을 만든다.
+
+        Args:
+            data (dict): `{'value': <SubmodelElement JSON>}` 형식의 dict.
+        Returns:
+            OperationVariable: basyx로 역직렬화된 변수 객체.
+        """
+        return cls(value=basyx_serde.from_dict(data['value']))
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        JSON 직렬화 가능한 dict로 변환한다.
+
+        Returns:
+            dict[str, Any]: `{'value': <SubmodelElement JSON dict>}`.
+        """
+        return {'value': json.loads(basyx_serde.to_json(self.value))}
+
+
+@dataclass(slots=True)
+class OperationResult:
+    """
+    AAS Operation 호출 결과.
+
+    Attributes:
+        messages (Optional[list[str]]): 서버가 반환한 메시지 목록.
+        execution_state (str): 실행 상태 ("Completed", "Failed" 등).
+        success (bool): 성공 여부.
+        output_op_variables (Optional[list[OperationVariable]]): 출력 인자 변수.
+        inoutput_op_variables (Optional[list[OperationVariable]]): 입출력 인자 변수.
+    """
+    messages: Optional[list[str]]
+    execution_state: str
+    success: bool
+    output_op_variables: Optional[list[OperationVariable]]
+    inoutput_op_variables: Optional[list[OperationVariable]]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> OperationResult:
+        """
+        서버 JSON 응답에서 OperationResult를 구성한다.
+
+        서버 키 `outputArguments` / `inoutputArguments`를 OperationVariable
+        목록으로 변환한다.
+
+        Args:
+            data (dict): JSON으로 파싱된 응답 본문.
+        Returns:
+            OperationResult: 변환된 결과 객체.
+        """
+        output_arguments = data.get('outputArguments')
+        if output_arguments:
+            output_arguments = [OperationVariable.from_dict(arg) for arg in output_arguments]
+        inoutput_arguments = data.get('inoutputArguments')
+        if inoutput_arguments:
+            inoutput_arguments = [OperationVariable.from_dict(arg) for arg in inoutput_arguments]
+
+        return cls(
+            messages=data.get('messages'),
+            execution_state=data['executionState'],
+            success=data['success'],
+            output_op_variables=output_arguments,
+            inoutput_op_variables=inoutput_arguments,
+        )
+
+    @classmethod
+    def from_json(cls, json_str: str) -> OperationResult:
+        """JSON 문자열로부터 OperationResult를 구성한다."""
+        return cls.from_dict(json.loads(json_str))
+
+
+@dataclass(slots=True)
+class OperationHandle:
+    """
+    비동기 Operation 호출이 반환하는 핸들.
+
+    Attributes:
+        handle_id (str): 서버가 발급한 비동기 작업 식별자.
+    """
+    handle_id: str
+
+    @classmethod
+    def from_json(cls, json_str: str) -> OperationHandle:
+        """
+        JSON 문자열에서 OperationHandle을 만든다.
+
+        서버는 `handleId` 키(camelCase)를 사용하므로 그에 맞춰 매핑한다.
+
+        Args:
+            json_str (str): `{"handleId": "..."}` 형식의 JSON.
+        Returns:
+            OperationHandle: 핸들 객체.
+        """
+        json_dict = json.loads(json_str)
+        return cls(handle_id=json_dict['handleId'])
+
+
+@dataclass(slots=True)
+class OperationRequest:
+    """
+    AAS Operation 호출 요청 본문.
+
+    Attributes:
+        input_arguments (Iterable[OperationVariable]): 입력 인자 변수 목록.
+        inoutput_arguments (Iterable[OperationVariable]): 입출력 인자 변수 목록.
+        client_timeout_duration (datetime.timedelta): 클라이언트 측 타임아웃.
+            JSON 직렬화 시 ISO 8601 duration 문자열로 변환된다.
+    """
+    input_arguments: Iterable[OperationVariable]
+    inoutput_arguments: Iterable[OperationVariable]
+    client_timeout_duration: datetime.timedelta
+
+    def to_json(self) -> str:
+        """
+        요청 본문을 JSON 문자열로 직렬화한다.
+
+        현재 fa3st 서버는 `inputArguments`만 인식하므로 `inoutputArguments`는
+        직렬화에서 제외한다. (필요 시 아래 주석을 해제하여 포함시킬 수 있다.)
+
+        Returns:
+            str: JSON 문자열.
+        """
+        in_opv_list = [op_var.to_dict() for op_var in self.input_arguments]
+        return json.dumps({
+            'inputArguments': in_opv_list,
+            # 'inoutputArguments': [op_var.to_dict() for op_var in self.inoutput_arguments],
+            'clientTimeoutDuration': utils.timedelta_to_iso8601(self.client_timeout_duration),
+        })

{mdtpy-0.2.2 → mdtpy-0.2.4}/src/mdtpy/airflow/invocation.py

@@ -1,11 +1,13 @@
 from __future__ import annotations
 
-from dataclasses import dataclass, field
 from typing import Optional, TypedDict
 from typing_extensions import NotRequired
 
 from abc import ABC, abstractmethod
 
+import logging
+logger = logging.getLogger(__name__)
+
 from ..reference import ElementReference
 from ..operation import OperationSubmodelService
 from .argument_spec import ElementReferenceArgumentSpec, LiteralArgumentSpec, TaskOutputArgumentSpec
@@ -58,6 +60,7 @@ class AASOperationTaskInvocation(Invocation):
     self.argument_specs = argument_specs
 
   def run(self, context:Optional[DagContext]=None) -> None:
+    logger.info(f"Invoking operation {self.instance}:{self.submodel} with arguments {self.argument_specs}")
     if context is None:
       context = AirflowDagContext()
 
@@ -75,21 +78,3 @@ class AASOperationTaskInvocation(Invocation):
     return ( f"{self.__class__.__name__}(task={self.instance}:{self.submodel}, "
              f"inputs={self.argument_specs['inputs']}, "
              f"outputs={get_output_argument_specs(self.argument_specs)})" )
-
-
-# def add_task_output_values(context:DagContext, out_arg_values:ElementValueDict,
-#                           out_arg_specs_dict:dict[str, OutputArgumentSpecType]) -> None:
-#   task_id = context.task_id
-#   for arg_id, arg_value in out_arg_values.items():
-#     if arg_id not in out_arg_specs_dict:
-#       continue
-
-#     out_arg_specs = out_arg_specs_dict[arg_id]
-#     if isinstance(out_arg_specs, list):
-#       for arg_spec in out_arg_specs:
-#         if isinstance(arg_spec, OutputArgumentSpec):
-#           context.add_task_output_value(task_id, arg_id, arg_value)
-#           break
-#     else:
-#       if isinstance(out_arg_specs, OutputArgumentSpec):
-#           context.add_task_output_value(task_id, arg_id, arg_value)