sodas-python-sdk 1.0.3
SODAS 프레임워크를 위한 공식 Python SDK. DCAT 기반 데이터셋 메타데이터 관리.
Requires Python: <3.13,>=3.9
Keywords: sodas, sdk, dcat, metadata, data-catalog

# 🛠️ SODAS TS SDK

dist/index.node.js : for node
dist/index.browser.js : for browser
dist/index.legacy.js : for webpack version 4 [ especially for governace portal ]

---

## 📜 SODAS_SDK_CLASS Policy

- 모든 **SODAS_SDK_CLASS**는 해당 클래스와 **DTO 인터페이스**를 가진다.
- 모든 **SODAS_SDK_CLASS** 인스턴스는 **CRUDL 기능**을 제공하며, 인터페이스는 다음과 같다:
  - create_db_record
  - get_db_record
  - update_db_record
  - delete_db_record
  - list_db_records
- **time 필드**는 Backend API와의 통신 시 **iso_format**을 사용한다.
- **create_db_record** 메서드를 통해서만 **ID와 IRI**가 생성된다.
  - **ID와 IRI**가 이미 존재하는 경우, **create_db_record** 호출이 불가능하며 **update_db_record**만 호출 가능하다.
- **delete_db_resource** 호출 시 해당 객체는 기본생성인스턴스가 된다.
- **DCAT_MODEL**의 경우 다음 필드들은 **백엔드 create API** 호출을 통해서만 생성된다:
  - resource_type, ID, IRI, created_at, dcat_model_id (e.g., dataset_id 등)

---

### DCAT_RESOURCE - Thumbnail Policy

- 모든 **DCAT Resource CLASS**는 Thumbnail 프로퍼티를 가진다.
- Thumbnail 프로퍼티는 **SODAS_SDK_FILE** 클래스를 상속받은 **thumbnail_file** 클래스의 인스턴스이다.
- 이미 thumbnail_url이 있는 경우 Thumbnail 필드를 설정하면 thumbnail_url은 null로 설정된다.
- Thumbnail은 DCAT_RESOURCE 인스턴스의 create_db_record 메소드 호출 시 업로드된다. (단, Thumbnail의 업로드가 먼저 호출되므로 DCAT_RESOURCE.create_db_record에서 에러가 발생할 경우 Thumbnail만 업로드될 가능성이 있다.)
- 이미 db_record가 있으면서 Thumbnail을 설정한 경우에는 DCAT_RESOURCE 인스턴스의 update_db_record 메소드 호출 시 기존의 Thumbnail은 제거되고 새로운 Thumbnail을 연결한다.
- Thumbnail은 DCAT_RESOURCE 인스턴스의 삭제 시 삭제된다.
- SDK는 Thumbnail File의 생성요청의 책임을, SODAS_PROFILE 백엔드는 생성과 삭제의 책임을 가진다.

---

### DCAT_RESOURCE - version_info Policy

- DCAT_RESOURCE 인스턴스는 create_db_record/get_db_record/update_db_record/list_db_records를 통해 관련된 version_info들을 불러온다.
- create_db_record/update_db_record/delete_db_record를 통해 새롭게 버전 정보가 변경돼도 인스턴스 간 version_info는 동기화되지 않는다. 따라서 의식적으로 get_db_record를 통한 동기화가 필요하다.

---

### Distribution - uploading_data Policy

- 모든 **DCAT Distribution CLASS**는 uploading_data 프로퍼티를 가진다.
- uploading_data 프로퍼티는 **SODAS_SDK_FILE** 클래스를 상속받은 **data_file** 클래스의 인스턴스이다.
- 이미 download_url 있는 경우 uploading_data 필드를 설정하면 download_url은 null로 설정된다.
- uploading_data는 Distribution 인스턴스의 create_db_record 메소드 호출 시 업로드된다. (단, Data의 업로드가 먼저 호출되므로 Distribution.create_db_record에서 에러가 발생할 경우 Data만 업로드될 가능성이 있다.)
- 이미 db_record가 있으면서 uploading_data를 설정한 경우 update_db_record 메소드 호출 시 기존의 Object File은 제거되고 새로운 Object File을 download_url과 연결한다.
- uploading_data의 실제 Object File은 Distribution 인스턴스 삭제 시 삭제된다.
- SDK는 Object File의 생성 요청의 책임을, SODAS_PROFILE 백엔드는 생성과 삭제의 책임을 가진다.

---

### Dataset - Distribution Policy

- Dataset의 메서드로 Dataset Instance와 연관된 Distributions를 만들 수 있다.
- Dataset.create_db_record를 통해 연관된 Distribution들의 create_db_record가 호출되며, 최종적으로 Dataset과 Distribution 모두 ID와 IRI를 가지게 된다.
  - 이 시점에서 Distribution은 is_distribution_of를 연관된 Dataset의 ID로 가지게 된다.
- update_db_record 호출 시 하위 모든 Distribution의 update_db_record도 호출된다.
  - 새롭게 추가된 Distribution은 레코드를 새롭게 만들고, 연결이 끊어진 Distribution은 삭제된다.
- delete_db_resource 호출 시 Dataset과 연관된 모든 Distribution은 DB에서 삭제되며 인스턴스들은 기본생성인스턴스가 된다.

---

### DatasetSeries - Dataset Policy

- DatasetSeries는 create_db_record/get_db_record/update_db_record/list_db_records를 통해 관련된 series_members(Dataset)들을 불러온다.
- DatasetSeries는 series_member_ids 필드로 Dataset의 순서와 관계를 관리한다.
- delete_db_record 호출 시 DatasetSeries만 DB에서 삭제되며, 관련된 Dataset 인스턴스는 기본생성인스턴스로 초기화된다.

---

## 🧪 CRUDL Test Policy

### Test Levels

- **Small 테스트**: 클래스 자체의 메서드 테스트
- **Medium 테스트**: SDK와 백엔드의 통합 테스트
- **Big 테스트**: 사용자 시나리오 엔드투엔드 테스트 (현재는 없음)

---

### 🟢 1. CREATE

#### ✅ 테스트 케이스:

- **foreign_key 필드**를 제외한 모든 필드 중 하나만 null 값으로 설정한 케이스를 테스트한다.

#### 📝 테스트 정책:

1. DTO를 기반으로 인스턴스를 세팅한다.
2. **create_db_record** 호출 후 **ID와 IRI** 생성 여부를 확인한다.
3. API 결과와 인스턴스를 비교한다.
4. **ID와 IRI**가 설정된 인스턴스에서 **create_db_record** 호출 시 에러 발생을 확인한다.

---

### 🟢 2. GET

#### ✅ 테스트 케이스:

- **foreign_key 필드**를 제외한 모든 필드 중 하나만 null 값으로 설정한 케이스를 테스트한다.

#### 📝 테스트 정책:

1. DTO를 기반으로 인스턴스를 세팅한다.
2. **create_db_record**로 인스턴스를 생성한다.
3. **get_db_record**로 생성된 인스턴스를 가져온다.
4. 생성 및 조회된 인스턴스를 비교한다.

---

### 🟢 3. UPDATE

#### ✅ 테스트 케이스:

- **foreign_key 필드**를 제외한 모든 필드 중 하나만 null 값으로 설정한 케이스를 테스트한다.

#### 📝 테스트 정책:

1. 모든 필드가 채워진 인스턴스를 세팅한다.
2. **ID와 IRI**가 없는 인스턴스에서 **update_db_record** 호출 시 에러 발생을 확인한다.
3. **create_db_record**로 인스턴스를 생성한다.
4. DTO를 기반으로 인스턴스를 재설정한다.
5. **update_db_record**로 인스턴스를 업데이트한다.
6. API 결과와 인스턴스를 비교한다.

---

### 🟢 4. DELETE

#### ✅ 테스트 케이스:

- **모든 필드가 채워진 케이스 하나**로 테스트한다.

#### 📝 테스트 정책:

1. 모든 필드가 채워진 인스턴스를 세팅한다.
2. **create_db_record**로 인스턴스를 생성한다.
3. 생성된 인스턴스를 복사한다.
4. **delete_db_record**로 인스턴스를 삭제한다.
5. 삭제된 인스턴스의 모든 필드가 null인지 확인한다.
6. 복사된 인스턴스에서 **delete_db_record** 호출 시 에러 발생을 확인한다.

---

### 🟢 5. LIST

#### ✅ 테스트 케이스:

- **모든 필드가 채워진 인스턴스 12개**를 만들고, **페이지 수 5개**로 테스트한다.

#### 📝 테스트 정책:

1. 지정된 갯수만큼 인스턴스를 생성하고 저장한다.
2. **list_db_records**를 ASC 및 DESC 방식으로 호출하고 총 수량과 순서를 비교한다.

---

## 🧪 SODAS_SDK_FILE Test Policy

#### 📝 테스트 정책:

1. **SODAS_SDK_FILE.upload()** 호출 후 파일을 업로드한다.
2. **get_download_url()**로 다운로드 URL을 확인하고, 원본 파일과 동일한지 확인한다.
3. **SODAS_SDK_FILE.remove()** 호출 후 삭제 및 URL 유효성 확인.


MANAGED BY HAZE1211