datagsm-openapi-sdk 1.0.0b1__py3-none-any.whl

datagsm_openapi/__init__.py

@@ -0,0 +1,61 @@
+"""DataGSM OpenAPI SDK for Python.
+
+Official Python SDK for the DataGSM OpenAPI service.
+
+Example:
+    Basic usage::
+
+        from datagsm_openapi import DataGsmClient
+
+        with DataGsmClient(api_key="your-api-key") as client:
+            students = client.students.get_students()
+            print(f"Total students: {students.total_elements}")
+"""
+
+from .api import (
+    ClubApi,
+    ClubRequest,
+    MealRequest,
+    NeisApi,
+    ProjectApi,
+    ProjectRequest,
+    ScheduleRequest,
+    StudentApi,
+    StudentRequest,
+)
+from .client import DataGsmClient
+from .exceptions import (
+    BadRequestException,
+    DataGsmException,
+    ForbiddenException,
+    NetworkException,
+    NotFoundException,
+    RateLimitException,
+    ServerErrorException,
+    UnauthorizedException,
+    ValidationException,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BadRequestException",
+    "ClubApi",
+    "ClubRequest",
+    "DataGsmClient",
+    "DataGsmException",
+    "ForbiddenException",
+    "MealRequest",
+    "NeisApi",
+    "NetworkException",
+    "NotFoundException",
+    "ProjectApi",
+    "ProjectRequest",
+    "RateLimitException",
+    "ScheduleRequest",
+    "ServerErrorException",
+    "StudentApi",
+    "StudentRequest",
+    "UnauthorizedException",
+    "ValidationException",
+]

datagsm_openapi/_http.py

@@ -0,0 +1,291 @@
+"""HTTP client abstraction layer for DataGSM OpenAPI SDK."""
+
+from typing import Any, Optional
+
+import httpx
+
+from .exceptions import (
+    BadRequestException,
+    DataGsmException,
+    ForbiddenException,
+    NetworkException,
+    NotFoundException,
+    RateLimitException,
+    ServerErrorException,
+    UnauthorizedException,
+)
+
+
+class HttpClient:
+    """HTTP client wrapper around httpx with error handling.
+
+    This class provides a clean interface for making HTTP requests to the DataGSM API
+    with automatic error handling and exception mapping.
+
+    Attributes:
+        base_url: Base URL for the API
+        api_key: API key for authentication
+        timeout: Request timeout in seconds
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the HTTP client.
+
+        Args:
+            base_url: Base URL for the API
+            api_key: API key for authentication
+            timeout: Request timeout in seconds (default: 30.0)
+        """
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._client: Optional[httpx.Client] = None
+
+    def __enter__(self) -> "HttpClient":
+        """Enter context manager."""
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            headers=self._get_headers(),
+        )
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Exit context manager and close the client."""
+        self.close()
+
+    def _get_headers(self) -> dict[str, str]:
+        """Get common headers for all requests.
+
+        Returns:
+            Dictionary of HTTP headers
+        """
+        return {
+            "X-API-KEY": self.api_key,
+            "Accept": "application/json",
+            "User-Agent": "datagsm-openapi-sdk-python/0.1.0",
+        }
+
+    def _get_client(self) -> httpx.Client:
+        """Get or create the HTTP client.
+
+        Returns:
+            The httpx.Client instance
+        """
+        if self._client is None:
+            self._client = httpx.Client(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                headers=self._get_headers(),
+            )
+        return self._client
+
+    def _handle_error(self, response: httpx.Response) -> None:
+        """Handle HTTP error responses.
+
+        Args:
+            response: The HTTP response object
+
+        Raises:
+            BadRequestException: For 400 errors
+            UnauthorizedException: For 401 errors
+            ForbiddenException: For 403 errors
+            NotFoundException: For 404 errors
+            RateLimitException: For 429 errors
+            ServerErrorException: For 5xx errors
+            DataGsmException: For other errors
+        """
+        try:
+            error_body = response.json()
+            error_message = error_body.get("message", response.text)
+        except Exception:
+            error_body = None
+            error_message = response.text or f"HTTP {response.status_code} error"
+
+        status_code = response.status_code
+
+        if status_code == 400:
+            raise BadRequestException(message=error_message, response_body=error_body)
+        elif status_code == 401:
+            raise UnauthorizedException(message=error_message, response_body=error_body)
+        elif status_code == 403:
+            raise ForbiddenException(message=error_message, response_body=error_body)
+        elif status_code == 404:
+            raise NotFoundException(message=error_message, response_body=error_body)
+        elif status_code == 429:
+            raise RateLimitException(message=error_message, response_body=error_body)
+        elif 500 <= status_code < 600:
+            raise ServerErrorException(
+                message=error_message,
+                status_code=status_code,
+                response_body=error_body,
+            )
+        else:
+            raise DataGsmException(
+                message=error_message,
+                status_code=status_code,
+                response_body=error_body,
+            )
+
+    def get(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make a GET request.
+
+        Args:
+            path: API endpoint path (e.g., "/students")
+            params: Query parameters
+
+        Returns:
+            JSON response as a dictionary
+
+        Raises:
+            NetworkException: For connection or timeout errors
+            DataGsmException: For API errors
+        """
+        try:
+            client = self._get_client()
+            response = client.get(path, params=params)
+            response.raise_for_status()
+            return response.json()  # type: ignore[no-any-return]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e.response)
+            raise  # This line will never be reached, but makes mypy happy
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkException(
+                message=f"Network error: {e!s}",
+                original_exception=e,
+            ) from e
+        except httpx.HTTPError as e:
+            raise NetworkException(
+                message=f"HTTP error: {e!s}",
+                original_exception=e,
+            ) from e
+
+    def post(
+        self,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make a POST request.
+
+        Args:
+            path: API endpoint path
+            json: JSON request body
+            params: Query parameters
+
+        Returns:
+            JSON response as a dictionary
+
+        Raises:
+            NetworkException: For connection or timeout errors
+            DataGsmException: For API errors
+        """
+        try:
+            client = self._get_client()
+            response = client.post(path, json=json, params=params)
+            response.raise_for_status()
+            return response.json()  # type: ignore[no-any-return]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e.response)
+            raise
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkException(
+                message=f"Network error: {e!s}",
+                original_exception=e,
+            ) from e
+        except httpx.HTTPError as e:
+            raise NetworkException(
+                message=f"HTTP error: {e!s}",
+                original_exception=e,
+            ) from e
+
+    def put(
+        self,
+        path: str,
+        json: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make a PUT request.
+
+        Args:
+            path: API endpoint path
+            json: JSON request body
+            params: Query parameters
+
+        Returns:
+            JSON response as a dictionary
+
+        Raises:
+            NetworkException: For connection or timeout errors
+            DataGsmException: For API errors
+        """
+        try:
+            client = self._get_client()
+            response = client.put(path, json=json, params=params)
+            response.raise_for_status()
+            return response.json()  # type: ignore[no-any-return]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e.response)
+            raise
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkException(
+                message=f"Network error: {e!s}",
+                original_exception=e,
+            ) from e
+        except httpx.HTTPError as e:
+            raise NetworkException(
+                message=f"HTTP error: {e!s}",
+                original_exception=e,
+            ) from e
+
+    def delete(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Make a DELETE request.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+
+        Returns:
+            JSON response as a dictionary
+
+        Raises:
+            NetworkException: For connection or timeout errors
+            DataGsmException: For API errors
+        """
+        try:
+            client = self._get_client()
+            response = client.delete(path, params=params)
+            response.raise_for_status()
+            return response.json()  # type: ignore[no-any-return]
+        except httpx.HTTPStatusError as e:
+            self._handle_error(e.response)
+            raise
+        except (httpx.ConnectError, httpx.TimeoutException) as e:
+            raise NetworkException(
+                message=f"Network error: {e!s}",
+                original_exception=e,
+            ) from e
+        except httpx.HTTPError as e:
+            raise NetworkException(
+                message=f"HTTP error: {e!s}",
+                original_exception=e,
+            ) from e
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        if self._client is not None:
+            self._client.close()
+            self._client = None

datagsm_openapi/_json.py

@@ -0,0 +1,53 @@
+"""JSON serialization utilities for DataGSM OpenAPI SDK."""
+
+from datetime import date, datetime
+from typing import Any
+
+
+def serialize_date(value: date) -> str:
+    """Serialize a date to ISO format string.
+
+    Args:
+        value: Date object to serialize
+
+    Returns:
+        ISO format date string (YYYY-MM-DD)
+    """
+    return value.isoformat()
+
+
+def serialize_datetime(value: datetime) -> str:
+    """Serialize a datetime to ISO format string.
+
+    Args:
+        value: Datetime object to serialize
+
+    Returns:
+        ISO format datetime string
+    """
+    return value.isoformat()
+
+
+def clean_params(params: dict[str, Any]) -> dict[str, Any]:
+    """Clean query parameters by removing None values and serializing dates.
+
+    Args:
+        params: Dictionary of query parameters
+
+    Returns:
+        Cleaned dictionary with None values removed and dates serialized
+    """
+    cleaned: dict[str, Any] = {}
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, datetime):
+            cleaned[key] = serialize_datetime(value)
+        elif isinstance(value, date):
+            cleaned[key] = serialize_date(value)
+        elif isinstance(value, bool):
+            # Convert boolean to lowercase string for query params
+            cleaned[key] = str(value).lower()
+        else:
+            cleaned[key] = value
+    return cleaned

datagsm_openapi/api/__init__.py

@@ -0,0 +1,18 @@
+"""API modules for DataGSM OpenAPI SDK."""
+
+from .club import ClubApi, ClubRequest
+from .neis import MealRequest, NeisApi, ScheduleRequest
+from .project import ProjectApi, ProjectRequest
+from .student import StudentApi, StudentRequest
+
+__all__ = [
+    "ClubApi",
+    "ClubRequest",
+    "MealRequest",
+    "NeisApi",
+    "ProjectApi",
+    "ProjectRequest",
+    "ScheduleRequest",
+    "StudentApi",
+    "StudentRequest",
+]

datagsm_openapi/api/_base.py

@@ -0,0 +1,73 @@
+"""Base API class for DataGSM OpenAPI SDK."""
+
+from typing import Any, Optional, Type, TypeVar, cast
+
+from pydantic import ValidationError
+
+from .._http import HttpClient
+from .._json import clean_params
+from ..exceptions import ValidationException
+from ..models import CommonApiResponse
+
+T = TypeVar("T")
+
+
+class BaseApi:
+    """Base class for all API modules.
+
+    Provides common functionality for making HTTP requests and parsing responses.
+    """
+
+    def __init__(self, http_client: HttpClient) -> None:
+        """Initialize the base API.
+
+        Args:
+            http_client: HTTP client instance
+        """
+        self._http = http_client
+
+    def _get(
+        self,
+        path: str,
+        params: Optional[dict[str, Any]] = None,
+        response_type: Optional[Type[T]] = None,
+    ) -> T:
+        """Make a GET request and parse the response.
+
+        Args:
+            path: API endpoint path
+            params: Query parameters
+            response_type: Pydantic model class for response data
+
+        Returns:
+            Parsed response data
+
+        Raises:
+            ValidationException: If response validation fails
+        """
+        # Clean params (remove None values, serialize dates, etc.)
+        clean = clean_params(params) if params else None
+
+        # Make HTTP request
+        response_data = self._http.get(path, params=clean)
+
+        # If no response type specified, return raw data
+        if response_type is None:
+            return response_data  # type: ignore[return-value]
+
+        # Parse as CommonApiResponse
+        try:
+            wrapped_response = CommonApiResponse[response_type].model_validate(  # type: ignore[valid-type]
+                response_data
+            )
+            if wrapped_response.data is None:
+                raise ValidationException(
+                    message="Response data is None",
+                    validation_errors=[],
+                )
+            return cast(T, wrapped_response.data)
+        except ValidationError as e:
+            raise ValidationException(
+                message=f"Response validation failed: {e!s}",
+                validation_errors=cast(list[dict[str, Any]], e.errors()),
+            ) from e

datagsm_openapi/api/club.py

@@ -0,0 +1,106 @@
+"""Club API module for DataGSM OpenAPI SDK."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..models import ClubDetail, ClubResponse, ClubSortBy, ClubType, SortDirection
+from ._base import BaseApi
+
+
+@dataclass
+class ClubRequest:
+    """동아리 조회 요청 파라미터 (Club Query Parameters).
+
+    Attributes:
+        club_id: Club ID for exact match
+        club_name: Club name for filtering
+        club_type: Club type filter (MAJOR_CLUB, JOB_CLUB, AUTONOMOUS_CLUB)
+        page: Page number (default: 0)
+        size: Page size (default: 100)
+        include_leader_in_participants: Include leader in participants list (default: False)
+        sort_by: Sort field
+        sort_direction: Sort direction (default: ASC)
+    """
+
+    club_id: Optional[int] = None
+    club_name: Optional[str] = None
+    club_type: Optional[ClubType] = None
+    page: int = 0
+    size: int = 100
+    include_leader_in_participants: bool = False
+    sort_by: Optional[ClubSortBy] = None
+    sort_direction: SortDirection = SortDirection.ASC
+
+    def to_params(self) -> dict[str, Optional[object]]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary of query parameters
+        """
+        params: dict[str, Optional[object]] = {
+            "clubId": self.club_id,
+            "clubName": self.club_name,
+            "clubType": self.club_type.value if self.club_type else None,
+            "page": self.page,
+            "size": self.size,
+            "includeLeaderInParticipants": self.include_leader_in_participants,
+            "sortBy": self.sort_by.value if self.sort_by else None,
+            "sortDirection": self.sort_direction.value,
+        }
+        return params
+
+
+class ClubApi(BaseApi):
+    """동아리 데이터 API (Club Data API).
+
+    Provides methods for querying club information.
+    """
+
+    def get_clubs(self, request: Optional[ClubRequest] = None) -> ClubResponse:
+        """동아리 목록 조회 (Get Club List).
+
+        Query clubs with optional filtering, sorting, and pagination.
+
+        Args:
+            request: Query parameters (optional)
+
+        Returns:
+            Paginated club response
+
+        Example:
+            >>> api = ClubApi(http_client)
+            >>> # Get all clubs
+            >>> response = api.get_clubs()
+            >>> print(f"Total: {response.total_elements}")
+            >>>
+            >>> # Filter by type
+            >>> request = ClubRequest(club_type=ClubType.MAJOR_CLUB)
+            >>> major_clubs = api.get_clubs(request)
+        """
+        req = request or ClubRequest()
+        return self._get("/v1/clubs", params=req.to_params(), response_type=ClubResponse)
+
+    def get_club(self, club_id: int) -> Optional[ClubDetail]:
+        """특정 동아리 조회 (Get Specific Club).
+
+        Retrieve a single club by ID with detailed information.
+
+        Args:
+            club_id: Club ID
+
+        Returns:
+            Club detail information if found, None otherwise
+
+        Example:
+            >>> api = ClubApi(http_client)
+            >>> club = api.get_club(1)
+            >>> if club:
+            ...     print(f"Club: {club.name}")
+            ...     print(f"Leader: {club.leader.name}")
+        """
+        request = ClubRequest(club_id=club_id)
+        response = self.get_clubs(request)
+
+        if response.clubs:
+            return response.clubs[0]
+        return None