image-api-sdk 0.1.0__tar.gz

image_api_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 seje06
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

image_api_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: image-api-sdk
+Version: 0.1.0
+Summary: Python SDK for a C++ image processing API server
+Author: seje06
+License: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: numpy>=1.24.0
+Dynamic: license-file
+
+# cv_api_python_sdk
+이미지 처리를 해주는 cv api 서버를 활용하기 위한 파이썬 라이브러리 개발
+
+## 세팅
+
+1. 가상환경
+    ```bash
+    > python -m venv .venv
+    > .venv\Scripts\activate
+    ```
+2. 필요 라이브러리 설치
+    ```bash
+    > pip install requests pillow numpy
+    > pip freeze > requirements.txt
+    ```
+
+## 라이브러리화
+
+- 구조
+    ```text
+    cv_api_python_sdk/
+    ├─ image_api_sdk/
+    │  ├─ __init__.py
+    │  ├─ client.py
+    │  └─ result.py
+    ├─ examples/
+    │  └─ basic_example.py
+    ├─ README.md
+    ├─ LICENSE
+    ├─ pyproject.toml
+    └─ requirements.txt
+    ```
+
+
+### 필요 파일 작성
+
+- pyproject.toml - [작성파일](pyproject.toml)
+    - 프로젝트의 모든 설정과 배포 명세서를 담은 표준 지도
+
+- LICENSE - [작성파일](LICENSE)
+    - 프로젝트를 사용하는 사람들에게 주는 허가증(권리 증명서) 역할
+
+### 필요 라이브러리 설치 및 실행
+
+1. 배포파일 생성
+    ```bash
+    pip install build
+    python -m build
+    ```
+2. 다른 가상환경에서 테스트
+- bash
+    ``` bash
+    pip install (프로젝트의 부모절대경로)\cv_api_python_sdk\dist\image_api_sdk-0.1.0-py3-none-any.whl
+    ```
+- python
+    ```python
+    from image_api_sdk import ImageApiClient
+    print("import success")
+    ```
+3. PYPI(공용파이썬 라이브러리 저장소) 에 올리기
+- twine 설치
+    ```bash
+    pip install twine
+    ```
+
+
+## 예시 사용법
+
+- 설치
+```bash
+pip install image-api-sdk
+```
+
+ - [예시코드](./examples/basic_example.py)
+

image_api_sdk-0.1.0/README.md

@@ -0,0 +1,75 @@
+# cv_api_python_sdk
+이미지 처리를 해주는 cv api 서버를 활용하기 위한 파이썬 라이브러리 개발
+
+## 세팅
+
+1. 가상환경
+    ```bash
+    > python -m venv .venv
+    > .venv\Scripts\activate
+    ```
+2. 필요 라이브러리 설치
+    ```bash
+    > pip install requests pillow numpy
+    > pip freeze > requirements.txt
+    ```
+
+## 라이브러리화
+
+- 구조
+    ```text
+    cv_api_python_sdk/
+    ├─ image_api_sdk/
+    │  ├─ __init__.py
+    │  ├─ client.py
+    │  └─ result.py
+    ├─ examples/
+    │  └─ basic_example.py
+    ├─ README.md
+    ├─ LICENSE
+    ├─ pyproject.toml
+    └─ requirements.txt
+    ```
+
+
+### 필요 파일 작성
+
+- pyproject.toml - [작성파일](pyproject.toml)
+    - 프로젝트의 모든 설정과 배포 명세서를 담은 표준 지도
+
+- LICENSE - [작성파일](LICENSE)
+    - 프로젝트를 사용하는 사람들에게 주는 허가증(권리 증명서) 역할
+
+### 필요 라이브러리 설치 및 실행
+
+1. 배포파일 생성
+    ```bash
+    pip install build
+    python -m build
+    ```
+2. 다른 가상환경에서 테스트
+- bash
+    ``` bash
+    pip install (프로젝트의 부모절대경로)\cv_api_python_sdk\dist\image_api_sdk-0.1.0-py3-none-any.whl
+    ```
+- python
+    ```python
+    from image_api_sdk import ImageApiClient
+    print("import success")
+    ```
+3. PYPI(공용파이썬 라이브러리 저장소) 에 올리기
+- twine 설치
+    ```bash
+    pip install twine
+    ```
+
+
+## 예시 사용법
+
+- 설치
+```bash
+pip install image-api-sdk
+```
+
+ - [예시코드](./examples/basic_example.py)
+

image_api_sdk-0.1.0/image_api_sdk/__init__.py

@@ -0,0 +1,10 @@
+# client.py에서 핵심 클라이언트 클래스와 에러 클래스를 가져온다.
+from .client import ImageApiClient, ImageApiError
+
+# result.py에서 결과 객체를 가져온다.
+from .result import ImageResult
+
+# 패키지 외부에서 공개할 이름 목록
+# 보통 "from image_api_sdk import *" 같은 상황에서 영향을 준다.
+# 명시적으로 어떤 심볼을 공개 API로 볼지 보여주는 역할도 한다.
+__all__ = ["ImageApiClient", "ImageApiError", "ImageResult"]

image_api_sdk-0.1.0/image_api_sdk/client.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+# 타입 힌트 편의용
+
+from typing import Any, Optional
+# Any:
+#   dict 안에 어떤 값이 올지 폭넓게 허용할 때 사용
+# Optional:
+#   int | None 같은 의미를 표현할 때 사용
+
+import requests
+# HTTP 요청을 보내기 위한 대표적인 파이썬 라이브러리
+# 여기서는 서버의 /health, /api/v1/process를 호출하는 데 사용한다.
+
+from .result import ImageResult
+# 같은 패키지 안의 result.py에 정의한 ImageResult 클래스를 가져온다.
+# 서버 응답(bytes)을 그냥 raw로 넘기지 않고, 사용하기 편한 객체로 감싸기 위함이다.
+
+
+class ImageApiError(Exception):
+    """
+    SDK 전용 예외 클래스.
+
+    그냥 ValueError나 RuntimeError를 쓰는 대신
+    ImageApiError를 만들어 두면,
+    SDK 사용자 입장에서 '이건 SDK/서버 요청 관련 오류구나' 하고 구분하기 쉽다.
+
+    사용 예:
+        try:
+            result = client.process_image(...)
+        except ImageApiError as e:
+            print("SDK 요청 실패:", e)
+    """
+    pass
+
+
+class ImageApiClient:
+    """
+    이미지 처리 서버와 통신하는 클라이언트 클래스.
+
+    역할:
+    - 서버 주소(base_url)를 기억한다.
+    - /health 요청을 보내 서버 상태를 확인한다.
+    - /api/v1/process 요청을 보내 이미지 처리를 수행한다.
+
+    사용 예:
+        client = ImageApiClient("http://localhost:8080")
+        health = client.health()
+        result = client.process_image(...)
+    """
+
+    def __init__(self, base_url: str, timeout: int = 30) -> None:
+        """
+        클라이언트 객체 초기화.
+
+        매개변수:
+        - base_url : 서버 주소
+                     예: "http://localhost:8080"
+        - timeout  : 요청 타임아웃(초 단위)
+
+        rstrip("/")를 쓰는 이유:
+        - 사용자가 "http://localhost:8080/" 처럼 끝에 슬래시를 붙여도
+        - 내부에선 "http://localhost:8080" 형태로 통일하기 위해서다.
+
+        이렇게 하면 나중에
+            f"{self.base_url}/health"
+        같은 URL 조합을 할 때 // 중복을 피할 수 있다.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def health(self) -> dict[str, Any]:
+        """
+        서버의 /health 엔드포인트를 호출해 상태를 확인한다.
+
+        반환값:
+        - 서버가 돌려준 JSON(dict)
+
+        예상 응답 예:
+            {
+                "status": "ok",
+                "message": "server is running"
+            }
+
+        동작 순서:
+        1. /health URL 생성
+        2. GET 요청 전송
+        3. HTTP 에러가 있으면 예외 발생
+        4. JSON 응답을 dict로 반환
+        """
+        # 최종 요청 URL 생성
+        url = f"{self.base_url}/health"
+
+        # GET 요청 전송
+        response = requests.get(url, timeout=self.timeout)
+
+        # 4xx/5xx 응답이면 HTTPError 예외 발생
+        response.raise_for_status()
+
+        # JSON 응답을 파이썬 dict로 변환해 반환
+        return response.json()
+
+    def process_image(
+        self,
+        image_url: str,
+        operations: list[dict[str, Any]],
+        output_format: str = "jpg",
+    ) -> ImageResult:
+        """
+        서버에 이미지 처리 요청을 보내고 결과 이미지를 받아온다.
+
+        매개변수:
+        - image_url     : 처리할 원본 이미지 URL
+        - operations    : 순서대로 적용할 작업 목록
+        - output_format : 결과 이미지 포맷 (기본값: jpg)
+
+        사용 예:
+            result = client.process_image(
+                image_url="https://example.com/a.jpg",
+                operations=[
+                    {"type": "grayscale"},
+                    {"type": "blur", "options": {"ksize": 9, "sigma": 2.0}}
+                ],
+                output_format="jpg"
+            )
+
+        서버는 성공 시 이미지 바이트를 반환하고,
+        SDK는 그걸 ImageResult 객체로 감싸서 반환한다.
+        """
+        # 처리 요청 엔드포인트 URL 생성
+        url = f"{self.base_url}/api/v1/process"
+
+        # 서버가 기대하는 JSON 요청 본문 구성
+        payload = {
+            "image_url": image_url,
+            "operations": operations,
+            "output_format": output_format,
+        }
+
+        # POST 요청 전송
+        # requests가 payload를 JSON으로 직렬화해서 보내고,
+        # Content-Type: application/json 헤더도 자동으로 넣어준다.
+        response = requests.post(url, json=payload, timeout=self.timeout)
+
+        # 응답 헤더에서 Content-Type 확인
+        # 성공 시 보통 image/jpeg 또는 image/png 같은 값이 올 것이다.
+        content_type = response.headers.get("Content-Type", "")
+
+        # HTTP 요청 실패(4xx, 5xx) 시
+        if not response.ok:
+            # 서버가 JSON 에러 메시지를 돌려줬을 수도 있으니 우선 JSON으로 읽어본다.
+            try:
+                error_json = response.json()
+            except Exception:
+                # JSON이 아니면 그냥 텍스트로 받아서 감싼다.
+                error_json = {"error": response.text}
+
+            # SDK 전용 예외 발생
+            raise ImageApiError(f"Request failed: {error_json}")
+
+        # 성공 응답인데도 image/*가 아니라면
+        # 우리가 기대한 형식이 아니므로 오류로 본다.
+        if not content_type.startswith("image/"):
+            raise ImageApiError(
+                f"Expected image response, but got Content-Type={content_type}"
+            )
+
+        # 서버가 추가 헤더로 결과 이미지 크기를 보내주도록 만들었으므로 읽는다.
+        width_header = response.headers.get("X-Image-Width")
+        height_header = response.headers.get("X-Image-Height")
+
+        # 헤더가 있으면 int로 변환, 없으면 None
+        width: Optional[int] = int(width_header) if width_header else None
+        height: Optional[int] = int(height_header) if height_header else None
+
+        # response.content에는 실제 이미지 파일 bytes가 들어 있다.
+        # 이걸 ImageResult 객체로 감싸서 반환한다.
+        return ImageResult(
+            data=response.content,
+            mime_type=content_type,
+            width=width,
+            height=height,
+        )

image_api_sdk-0.1.0/image_api_sdk/result.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+# 위 문장은 타입 힌트를 더 유연하게 쓰기 위한 설정이다.
+# 예를 들어 아직 정의 중인 클래스명을 타입으로 더 편하게 사용할 수 있다.
+# 지금 코드에선 꼭 필수는 아니지만, 요즘 파이썬 코드에서 자주 넣는다.
+
+import base64
+# 이미지 바이트를 base64 문자열로 바꿀 때 사용한다.
+# 예: DB text/json 컬럼 저장, 웹 전송용 문자열화 등에 쓸 수 있다.
+
+import io
+# 메모리 안의 bytes 데이터를 파일처럼 다루기 위해 사용한다.
+# Pillow가 BytesIO 객체를 통해 이미지 열 수 있다.
+
+from dataclasses import dataclass
+# dataclass를 쓰면 __init__, __repr__ 같은 기본 메서드를 자동으로 만들어준다.
+# 결과 객체를 간단하고 깔끔하게 정의할 수 있다.
+
+from typing import Optional
+# Optional[int]는 int 또는 None을 뜻한다.
+# 예: width가 없을 수도 있으니 Optional[int]로 표현
+
+from PIL import Image
+# Pillow 라이브러리의 Image 객체
+# 이미지 표시, 저장, 조작 등에 편리하다.
+
+import numpy as np
+# 이미지를 numpy 배열로 바꿔서 다른 라이브러리와 연동하기 좋다.
+# 예: 머신러닝 입력, 수치 처리 등
+
+
+@dataclass
+class ImageResult:
+    """
+    서버가 반환한 결과 이미지를 감싸는 객체.
+
+    이 클래스는 단순히 bytes만 들고 있는 게 아니라,
+    개발자가 바로 활용할 수 있도록 여러 편의 메서드를 제공한다.
+
+    필드 설명:
+    - data      : 실제 이미지 파일 바이트 (jpg/png 등)
+    - mime_type : 서버가 알려준 MIME 타입
+                  예: image/jpeg, image/png
+    - width     : 결과 이미지 가로 크기 (없을 수도 있음)
+    - height    : 결과 이미지 세로 크기 (없을 수도 있음)
+    """
+    data: bytes
+    mime_type: str
+    width: Optional[int] = None
+    height: Optional[int] = None
+
+    def save(self, path: str) -> None:
+        """
+        결과 이미지 바이트를 파일로 저장하는 메서드.
+
+        사용 예:
+            result.save("output.jpg")
+
+        동작:
+        - 바이너리 쓰기 모드("wb")로 파일을 열고
+        - self.data 내용을 그대로 저장한다.
+        """
+        with open(path, "wb") as f:
+            f.write(self.data)
+
+    def to_bytes(self) -> bytes:
+        """
+        결과 이미지를 raw bytes 형태로 그대로 반환한다.
+
+        사용 예:
+            image_bytes = result.to_bytes()
+
+        이 bytes는:
+        - 파일로 저장할 수도 있고
+        - DB BLOB에 넣을 수도 있고
+        - 다른 API로 전달할 수도 있다.
+        """
+        return self.data
+
+    def to_base64(self) -> str:
+        """
+        결과 이미지 바이트를 base64 문자열로 변환한다.
+
+        사용 예:
+            b64 = result.to_base64()
+
+        base64는:
+        - JSON에 넣기 편하고
+        - 텍스트 기반 저장소에 넣기 쉽다.
+
+        동작:
+        1. self.data(bytes)를 base64 bytes로 인코딩
+        2. 다시 utf-8 문자열로 디코딩해서 str로 반환
+        """
+        return base64.b64encode(self.data).decode("utf-8")
+
+    def to_pil(self) -> Image.Image:
+        """
+        결과 이미지를 Pillow Image 객체로 변환한다.
+
+        사용 예:
+            pil_img = result.to_pil()
+            pil_img.show()
+
+        동작:
+        - self.data는 단순 bytes이므로
+        - io.BytesIO로 '메모리 파일'처럼 감싼다.
+        - Pillow의 Image.open()으로 연다.
+        """
+        return Image.open(io.BytesIO(self.data))
+
+    def to_numpy(self) -> np.ndarray:
+        """
+        결과 이미지를 numpy 배열로 변환한다.
+
+        사용 예:
+            arr = result.to_numpy()
+
+        보통 shape는 이런 식이다:
+        - 컬러 이미지: (height, width, channel)
+        - 흑백 이미지: (height, width)
+
+        동작:
+        - 먼저 Pillow Image로 연다.
+        - 그걸 np.array(...)로 변환한다.
+        """
+        return np.array(self.to_pil())

image_api_sdk-0.1.0/image_api_sdk.egg-info/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: image-api-sdk
+Version: 0.1.0
+Summary: Python SDK for a C++ image processing API server
+Author: seje06
+License: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: numpy>=1.24.0
+Dynamic: license-file
+
+# cv_api_python_sdk
+이미지 처리를 해주는 cv api 서버를 활용하기 위한 파이썬 라이브러리 개발
+
+## 세팅
+
+1. 가상환경
+    ```bash
+    > python -m venv .venv
+    > .venv\Scripts\activate
+    ```
+2. 필요 라이브러리 설치
+    ```bash
+    > pip install requests pillow numpy
+    > pip freeze > requirements.txt
+    ```
+
+## 라이브러리화
+
+- 구조
+    ```text
+    cv_api_python_sdk/
+    ├─ image_api_sdk/
+    │  ├─ __init__.py
+    │  ├─ client.py
+    │  └─ result.py
+    ├─ examples/
+    │  └─ basic_example.py
+    ├─ README.md
+    ├─ LICENSE
+    ├─ pyproject.toml
+    └─ requirements.txt
+    ```
+
+
+### 필요 파일 작성
+
+- pyproject.toml - [작성파일](pyproject.toml)
+    - 프로젝트의 모든 설정과 배포 명세서를 담은 표준 지도
+
+- LICENSE - [작성파일](LICENSE)
+    - 프로젝트를 사용하는 사람들에게 주는 허가증(권리 증명서) 역할
+
+### 필요 라이브러리 설치 및 실행
+
+1. 배포파일 생성
+    ```bash
+    pip install build
+    python -m build
+    ```
+2. 다른 가상환경에서 테스트
+- bash
+    ``` bash
+    pip install (프로젝트의 부모절대경로)\cv_api_python_sdk\dist\image_api_sdk-0.1.0-py3-none-any.whl
+    ```
+- python
+    ```python
+    from image_api_sdk import ImageApiClient
+    print("import success")
+    ```
+3. PYPI(공용파이썬 라이브러리 저장소) 에 올리기
+- twine 설치
+    ```bash
+    pip install twine
+    ```
+
+
+## 예시 사용법
+
+- 설치
+```bash
+pip install image-api-sdk
+```
+
+ - [예시코드](./examples/basic_example.py)
+

image_api_sdk-0.1.0/image_api_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+image_api_sdk/__init__.py
+image_api_sdk/client.py
+image_api_sdk/result.py
+image_api_sdk.egg-info/PKG-INFO
+image_api_sdk.egg-info/SOURCES.txt
+image_api_sdk.egg-info/dependency_links.txt
+image_api_sdk.egg-info/requires.txt
+image_api_sdk.egg-info/top_level.txt

image_api_sdk-0.1.0/image_api_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

image_api_sdk-0.1.0/image_api_sdk.egg-info/requires.txt

@@ -0,0 +1,3 @@
+requests>=2.31.0
+pillow>=10.0.0
+numpy>=1.24.0

image_api_sdk-0.1.0/image_api_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+image_api_sdk

image_api_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "image-api-sdk"
+version = "0.1.0"
+description = "Python SDK for a C++ image processing API server"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "LICENSE" }
+authors = [
+  { name = "seje06" }
+]
+dependencies = [
+  "requests>=2.31.0",
+  "pillow>=10.0.0",
+  "numpy>=1.24.0"
+]
+
+[tool.setuptools]
+packages = ["image_api_sdk"]

image_api_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+