Metadata-Version: 2.4
Name: steam-mongodb-client
Version: 0.2.0
Summary: Simple MongoDB/GridFS client for STEAM partner institutions
Author: GNU STEAM Project
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pymongo<5,>=4.6
Provides-Extra: pcd
Requires-Dist: open3d>=0.19; extra == "pcd"

# STEAM MongoDB Client

타 기관 사용자가 MongoDB/GridFS 기능을 간단한 Python 함수로 사용할 수 있도록 만든 배포용 패키지입니다.

## 1. 사용자 설치

PyPI에 배포한 뒤 사용자는 터미널에서 한 번만 설치합니다.

```powershell
pip install steam-mongodb-client
```

PCD를 Open3D 객체로 직접 읽을 사용자는 다음 중 하나를 실행합니다.

```powershell
pip install "steam-mongodb-client[pcd]"
```

또는

```powershell
pip install open3d
```

## 2. 기본 사용 순서

```python
from steam_mongodb import connect, search, download, close

connect(
    host="203.xxx.xxx.xxx",
    username="기관계정",
    password="기관비밀번호",
    ca_file=r"C:\mongodb-certs\ca.pem",
)

files = search(site="site", pcd_type="UAV_PCD")
print(files)

download(
    files[0]["file_id"],
    r"D:\STEAM_DATA\downloaded.pcd",
)

close()
```

## 3. 제공 함수

| 함수 | 용도 |
|---|---|
| `connect()` | MongoDB 연결 |
| `ping()` | 연결 확인 |
| `search()` | 파일 검색/조회 |
| `download()` | 파일 저장 |
| `read_pcd()` | PCD를 Open3D 객체로 읽기 |
| `upload()` | 파일 업로드 |
| `update()` | 파일명/메타데이터 수정 |
| `delete()` | GridFS 파일 삭제 |
| `close()` | 연결 종료 |

## 4. 검색 예시

```python
files = search(
    site="site",
    date="2026-08-15",
    pcd_type="UAV_PCD",
)
```

조건은 필요한 것만 입력하면 됩니다.

```python
files = search(site="site")
```

```python
files = search(filename="sample")
```

## 5. PCD 직접 읽기

```python
from steam_mongodb import read_pcd

pcd = read_pcd(file_id)
print(pcd)
```

`read_pcd()`는 임시 PCD 파일을 만든 뒤 Open3D 객체로 읽고 임시 파일을 자동 삭제합니다.

## 6. 업로드

```python
from steam_mongodb import upload

file_id = upload(
    file_path=r"D:\STEAM_DATA\sample.pcd",
    site="site",
    date="2026-08-15",
    pcd_type="UAV_PCD",
    institution="snu_const",
)

print(file_id)
```

## 7. 수정

```python
from steam_mongodb import update

update(
    file_id,
    pcd_type="Reg_PCD",
)
```

## 8. 삭제

```python
from steam_mongodb import delete

delete(file_id)
```

삭제 권한이 있는 계정에서만 제공하는 것을 권장합니다.

## 9. 코드 보호 구조

사용자가 설치하는 wheel에는 `_core.pyx` 원본을 넣지 않고 Cython으로 컴파일된 확장 모듈을 넣도록 구성되어 있습니다.

사용자가 일반적으로 볼 수 있는 `__init__.py`에는 아래와 같이 공개 함수 이름만 존재합니다.

```python
from ._core import connect, search, download, read_pcd, upload, update, delete, close
```

따라서 일반적인 순수 Python 패키지보다 내부 구현 코드를 쉽게 열어보거나 수정하기 어렵습니다.

단, 사용자 PC에 설치된 프로그램을 기술적으로 100% 수정 불가능하게 만드는 것은 불가능합니다. 이 구조의 목적은 **원본 소스 비공개 + 일반 사용자의 임의 수정 방지 + 단순한 함수 호출 인터페이스 제공**입니다.

## 10. GitHub 권장 구조

### 개발 저장소

- GitHub Private Repository
- 관리자/개발자만 접근
- `_core.pyx` 포함
- MongoDB 비밀번호, 인증서 개인키, 실제 기관 비밀번호는 절대 업로드 금지

### 배포

태그를 push하면 GitHub Actions가 Windows용 wheel을 만들고 PyPI에 wheel만 배포하도록 설정되어 있습니다.

```powershell
git tag v0.1.0
git push origin v0.1.0
```

PyPI의 Trusted Publisher 설정이 먼저 필요합니다.

## 11. 중요 보안 원칙

1. MongoDB 관리자 계정 비밀번호를 패키지에 넣지 않기
2. 기관별 계정과 비밀번호를 사용자에게 따로 전달하기
3. 실제 IP, 인증서 개인키, 비밀번호를 GitHub 코드에 하드코딩하지 않기
4. 기관 계정별 MongoDB 권한을 필요한 범위로 제한하기
5. 일반 조회 기관에 `delete()` 권한이 필요 없다면 MongoDB 계정 권한 자체에서 삭제를 막기
6. 소스 배포판(`.tar.gz`)은 공개 배포하지 않고 compiled wheel만 배포하기

## 12. 현재 기본 GridFS 구조

기본 bucket 이름은 `data`입니다.

따라서 MongoDB에서는 일반적으로 다음 두 컬렉션을 사용합니다.

```text
data.files
data.chunks
```

현재 서버의 실제 bucket 이름이 다르면 `connect(bucket_name="...")`로 변경할 수 있습니다.

## 13. 인증 DB가 다른 경우

기본값은 다음과 같습니다.

```python
auth_db="admin"
```

기관 계정을 `steam_db`에서 생성했다면 다음처럼 바꿉니다.

```python
connect(
    ...,
    auth_db="steam_db",
)
```
