synapse-sdk 2025.9.1__py3-none-any.whl → 2025.9.4__py3-none-any.whl

synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/plugins/export-plugins.md

@@ -47,43 +47,43 @@ classDiagram
         +export_items: Generator
         +path_root: Path
         +params: dict
-        
+
         %% Main workflow methods
         +export(export_items, results, **kwargs) dict
         +process_data_conversion(export_item) object
         +process_file_saving(...) bool
         +setup_output_directories(path, flag) dict
-        
+
         %% Abstract methods (to be implemented)
         +convert_data(data)* object
-        +before_convert(data)* object  
+        +before_convert(data)* object
         +after_convert(data)* object
-        
+
         %% File operations
         +save_original_file(result, path, errors) ExportStatus
         +save_as_json(result, path, errors) ExportStatus
         +get_original_file_name(files) str
-        
+
         %% Helper methods
         -_create_unique_export_path(name) Path
         -_save_error_list(path, json_errors, file_errors)
         -_process_original_file_saving(...) bool
         -_process_json_file_saving(...) bool
     }
-    
+
     class Exporter {
         %% Inherited from BaseExporter
         +export(export_items, results, **kwargs) dict
-        
+
         %% Implemented abstract methods
         +convert_data(data) object
         +before_convert(data) object
         +after_convert(data) object
     }
-    
+
     %% Inheritance relationship
     BaseExporter <|-- Exporter
-    
+
     %% Apply styles
     class BaseExporter baseClass
     class Exporter childClass
@@ -99,44 +99,44 @@ flowchart TD
     A[export 메서드 호출] --> B[경로와 메트릭 초기화]
     B --> C[출력 디렉토리 설정]
     C --> D[export_items 순환]
-    
+
     %% Data processing pipeline
     D --> E[process_data_conversion]
     E --> F[before_convert]
     F --> G[convert_data]
     G --> H[after_convert]
-    
+
     %% File saving pipeline
     H --> I[process_file_saving]
     I --> J{원본 파일 저장?}
     J -->|예| K[_process_original_file_saving]
     J -->|아니오| L[_process_json_file_saving]
     K --> L
-    
+
     %% Continue or finish
     L --> M{더 많은 항목?}
     M -->|예| D
     M -->|아니오| N[오류 목록 저장]
     N --> O[내보내기 경로 반환]
-    
+
     %% Error handling
     K --> P{원본 파일 실패?}
     P -->|예| Q[다음 항목으로 건너뛰기]
     P -->|아니오| L
-    
+
     L --> R{JSON 파일 실패?}
     R -->|예| Q
     R -->|아니오| S[메트릭 업데이트]
     S --> M
     Q --> M
-    
+
     %% Styling for light/dark compatibility
     classDef startEnd fill:#e1f5fe,stroke:#01579b,color:#000
     classDef process fill:#f3e5f5,stroke:#4a148c,color:#000
     classDef decision fill:#fff3e0,stroke:#e65100,color:#000
     classDef data fill:#e8f5e8,stroke:#2e7d32,color:#000
     classDef error fill:#ffebee,stroke:#c62828,color:#000
-    
+
     class A,O startEnd
     class B,C,E,F,G,H,I,K,L,N,S process
     class J,M,P,R decision
@@ -147,18 +147,21 @@ flowchart TD
 ### 주요 관계 및 책임
 
 **BaseExporter (추상 기본 클래스)**
+
 - **핵심 기능**: 완전한 내보내기 워크플로우 인프라 제공
 - **템플릿 메서드**: `export()` 메서드가 전체 프로세스 조율
 - **훅 메서드**: 커스터마이징을 위한 `convert_data()`, `before_convert()`, `after_convert()`
 - **유틸리티**: 파일 작업, 디렉토리 설정, 오류 처리, 진행률 추적
 
-**Exporter (구체적 구현)**  
+**Exporter (구체적 구현)**
+
 - **상속**: `BaseExporter` 확장
 - **최소 구현**: 추상 메서드들의 기본 구현 제공
 - **위임 동작**: 대부분의 메서드가 부모 클래스에 위임
 - **커스터마이징 지점**: 특정 로직을 위해 변환 메서드 오버라이드
 
 ### 메서드 카테고리
+
 - **🔵 핵심 워크플로우**: 주요 내보내기 조율 메서드
 - **🟢 템플릿/훅**: 서브클래스에서 오버라이드하도록 설계된 메서드
 - **🟡 파일 작업**: 구체적인 파일 저장 및 처리 메서드
@@ -240,11 +243,11 @@ class Exporter(BaseExporter):
 ```python
 def additional_file_saving(self, unique_export_path):
     """모든 export 항목 처리 후 추가 파일 저장.
-    
+
     이 메서드는 주 export 루프가 완료된 후 호출되며, 모든 처리된 export 항목의
-    집합적 데이터를 기반으로 생성되어야 하는 파일들(예: 메타데이터 파일, 
+    집합적 데이터를 기반으로 생성되어야 하는 파일들(예: 메타데이터 파일,
     설정 파일, 요약 파일 등)을 저장하기 위한 것입니다.
-    
+
     Args:
         unique_export_path (str): 추가 파일이 저장될 고유한 export 디렉토리 경로.
     """
@@ -263,7 +266,7 @@ class YOLOExporter(BaseExporter):
             'total_annotations': 0,
             'class_distribution': {}
         }
-    
+
     def convert_data(self, data):
         # 변환 중 클래스와 통계 추적
         for annotation in data.get('annotations', []):
@@ -271,24 +274,24 @@ class YOLOExporter(BaseExporter):
             self.class_names.add(class_name)
             self.dataset_stats['class_distribution'][class_name] = \
                 self.dataset_stats['class_distribution'].get(class_name, 0) + 1
-        
+
         self.dataset_stats['total_images'] += 1
         self.dataset_stats['total_annotations'] += len(data.get('annotations', []))
-        
+
         return data  # ... 나머지 변환 로직
-    
+
     def additional_file_saving(self, unique_export_path):
         """YOLO 설정 및 메타데이터 파일 저장."""
         data_dir = Path(unique_export_path) / 'data'
         data_dir.mkdir(exist_ok=True)
-        
+
         # 1. classes.txt 파일 저장
         classes_file = data_dir / 'classes.txt'
         with classes_file.open('w') as f:
             for class_name in sorted(self.class_names):
                 f.write(f"{class_name}\n")
         self.run.log_message(f"클래스 파일 저장: {classes_file}")
-        
+
         # 2. dataset.yaml 파일 저장
         dataset_config = {
             'path': str(unique_export_path),
@@ -296,12 +299,12 @@ class YOLOExporter(BaseExporter):
             'val': 'images',
             'names': {i: name for i, name in enumerate(sorted(self.class_names))}
         }
-        
+
         dataset_file = data_dir / 'dataset.yaml'
         with dataset_file.open('w') as f:
             yaml.dump(dataset_config, f, default_flow_style=False)
         self.run.log_message(f"데이터셋 설정 저장: {dataset_file}")
-        
+
         # 3. export 통계 저장
         stats_file = data_dir / 'export_stats.json'
         with stats_file.open('w') as f:
@@ -312,6 +315,7 @@ class YOLOExporter(BaseExporter):
 ### 일반적인 사용 사례
 
 #### 1. 데이터셋 설정 파일
+
 ```python
 def additional_file_saving(self, unique_export_path):
     # 훈련 프레임워크용 데이터셋 설정 생성
@@ -321,13 +325,14 @@ def additional_file_saving(self, unique_export_path):
         'total_samples': len(self.processed_items),
         'classes': list(self.class_mapping.keys())
     }
-    
+
     config_file = Path(unique_export_path) / 'dataset_config.json'
     with config_file.open('w') as f:
         json.dump(config, f, indent=2)
 ```
 
 #### 2. Export 요약 보고서
+
 ```python
 def additional_file_saving(self, unique_export_path):
     # export 요약 생성
@@ -340,13 +345,14 @@ def additional_file_saving(self, unique_export_path):
         'statistics': self.get_export_statistics(),
         'errors': self.get_error_summary()
     }
-    
+
     summary_file = Path(unique_export_path) / 'export_summary.json'
     with summary_file.open('w') as f:
         json.dump(summary, f, indent=2)
 ```
 
 #### 3. 인덱스 및 매니페스트 파일
+
 ```python
 def additional_file_saving(self, unique_export_path):
     # 처리된 항목들에 대한 파일 인덱스 생성
@@ -357,7 +363,7 @@ def additional_file_saving(self, unique_export_path):
             'json_file': f"{item['stem']}.json",
             'processed_at': item['timestamp']
         })
-    
+
     index_file = Path(unique_export_path) / 'file_index.json'
     with index_file.open('w') as f:
         json.dump(file_index, f, indent=2)
@@ -540,6 +546,127 @@ my_plugin/
 └── manifest.yaml       # 플러그인 메타데이터
 ```
 
+## Export 액션 아키텍처
+
+데이터 내보내기 처리의 다양한 측면을 위한 특화된 구성 요소를 갖춘 모듈화된 아키텍처로 export 시스템이 리팩터링되었습니다:
+
+```mermaid
+classDiagram
+    %% Light/Dark mode compatible colors with semi-transparency
+    classDef baseClass fill:#e1f5fe80,stroke:#0288d1,stroke-width:2px
+    classDef childClass fill:#c8e6c980,stroke:#388e3c,stroke-width:2px
+    classDef modelClass fill:#fff9c480,stroke:#f57c00,stroke-width:2px
+    classDef utilClass fill:#f5f5f580,stroke:#616161,stroke-width:2px
+    classDef enumClass fill:#ffccbc80,stroke:#d32f2f,stroke-width:2px
+
+    class ExportAction {
+        +name: str = "export"
+        +category: PluginCategory.EXPORT
+        +method: RunMethod.JOB
+        +run_class: ExportRun
+        +params_model: ExportParams
+        +progress_categories: dict
+        +metrics_categories: dict
+
+        +start() dict
+        +get_exporter(...) object
+        +_get_export_items(target, filter) Generator
+        +_create_target_handler(target) object
+    }
+
+    class ExportRun {
+        +log_message_with_code(code, args, level) None
+        +log_export_event(code, args, level) None
+        +export_log_json_file(id, file_info, status) None
+        +export_log_original_file(id, file_info, status) None
+        +ExportEventLog: BaseModel
+        +DataFileLog: BaseModel
+        +MetricsRecord: BaseModel
+    }
+
+    class ExportParams {
+        +name: str
+        +storage: int
+        +target: Literal["assignment", "ground_truth", "task"]
+        +filter: dict
+        +path: str
+        +save_original_file: bool = True
+        +extra_params: dict = {}
+
+        +check_storage_exists(value) str
+        +validate_target_filter(cls, values) dict
+    }
+
+    class LogCode {
+        +EXPORT_STARTED: str
+        +ITEMS_DISCOVERED: str
+        +CONVERSION_STARTED: str
+        +CONVERSION_COMPLETED: str
+        +FILE_SAVED: str
+        +EXPORT_COMPLETED: str
+        +EXPORT_FAILED: str
+    }
+
+    class ExportStatus {
+        +SUCCESS: str = "success"
+        +FAILED: str = "failed"
+        +SKIPPED: str = "skipped"
+    }
+
+    class ExportError {
+        +message: str
+        +code: str
+    }
+
+    class ExportValidationError {
+        +message: str
+        +field: str
+    }
+
+    class ExportTargetError {
+        +message: str
+        +target: str
+    }
+
+    %% Relationships
+    ExportAction --> ExportRun : uses
+    ExportAction --> ExportParams : validates with
+    ExportRun --> LogCode : logs with
+    ExportRun --> ExportStatus : tracks status
+    ExportAction --> ExportError : may raise
+    ExportAction --> ExportValidationError : may raise
+    ExportAction --> ExportTargetError : may raise
+
+    %% Apply styles
+    class ExportAction baseClass
+    class ExportRun childClass
+    class ExportParams modelClass
+    class LogCode,ExportStatus enumClass
+    class ExportError,ExportValidationError,ExportTargetError utilClass
+```
+
+### 모듈화된 구조
+
+Export 액션은 깔끔한 모듈화된 구성을 따릅니다:
+
+```
+synapse_sdk/plugins/categories/export/actions/export/
+├── __init__.py        # 깔끔한 모듈 인터페이스
+├── action.py          # ExportAction 클래스
+├── enums.py          # ExportStatus, LogCode + LOG_MESSAGES
+├── exceptions.py     # Export 특화 예외
+├── models.py         # ExportParams 모델
+├── run.py           # ExportRun 클래스
+└── utils.py         # 대상 핸들러 및 유틸리티
+```
+
+**주요 장점:**
+
+- **향상된 유지보수성**: 작고 집중된 파일로 이해하고 수정하기 쉬움
+- **코드 일관성**: Export 액션이 이제 upload 액션과 동일한 패턴을 따름
+- **더 나은 구성**: 관련 기능이 논리적으로 그룹화됨
+- **향상된 가독성**: 모듈 전반에 걸친 명확한 관심사 분리
+
 ## Export 플러그인 생성
 
 Export 플러그인은 더 나은 구성과 재사용성을 위해 BaseExporter 클래스 기반 접근 방식을 사용합니다. 커스텀 export 플러그인을 생성하는 방법은 다음과 같습니다:
@@ -557,7 +684,7 @@ synapse plugin create
 `ExportParams` 모델이 필요한 매개변수를 정의합니다:
 
 ```python
-from synapse_sdk.plugins.categories.export.actions.export import ExportParams
+from synapse_sdk.plugins.categories.export.actions.export.models import ExportParams
 from pydantic import BaseModel
 from typing import Literal
 
@@ -664,7 +791,7 @@ BaseExporter 메서드를 오버라이드하여 파일 저장 및 구성을 커
 ```python
 import json
 from pathlib import Path
-from synapse_sdk.plugins.categories.export.enums import ExportStatus
+from synapse_sdk.plugins.categories.export.actions.export.enums import ExportStatus
 
 class Exporter(BaseExporter):
     """다중 형식 지원을 포함한 커스텀 export 플러그인."""
@@ -923,4 +1050,4 @@ A: `process_file_saving()` 메서드를 오버라이드하여 여러 형식으
 A: `convert_data()`에서 한 번에 모든 데이터를 로드하지 말고, 스트리밍 방식으로 처리하는 것을 고려해보세요.
 
 **Q: 진행률이 올바르게 표시되지 않는다면?**  
-A: `self.run.set_progress()`를 적절한 간격으로 호출하고 있는지 확인하세요. 0-100 사이의 정수 값을 사용해야 합니다.
+A: `self.run.set_progress()`를 적절한 간격으로 호출하고 있는지 확인하세요. 0-100 사이의 정수 값을 사용해야 합니다.