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

datagsm_openapi/api/neis.py

@@ -0,0 +1,141 @@
+"""NEIS API module for DataGSM OpenAPI SDK."""
+
+from dataclasses import dataclass
+from datetime import date as Date
+from typing import Optional
+
+from ..models import Meal, Schedule
+from ._base import BaseApi
+
+
+@dataclass
+class MealRequest:
+    """급식 조회 요청 파라미터 (Meal Query Parameters).
+
+    Use either 'date' for a single day or 'from_date' and 'to_date' for a date range.
+
+    Attributes:
+        date: Single date to query
+        from_date: Start date for range query
+        to_date: End date for range query
+    """
+
+    date: Optional[Date] = None
+    from_date: Optional[Date] = None
+    to_date: Optional[Date] = None
+
+    def to_params(self) -> dict[str, Optional[object]]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary of query parameters
+        """
+        params: dict[str, Optional[object]] = {
+            "date": self.date,
+            "fromDate": self.from_date,
+            "toDate": self.to_date,
+        }
+        return params
+
+
+@dataclass
+class ScheduleRequest:
+    """학사일정 조회 요청 파라미터 (Schedule Query Parameters).
+
+    Use either 'date' for a single day or 'from_date' and 'to_date' for a date range.
+
+    Attributes:
+        date: Single date to query
+        from_date: Start date for range query
+        to_date: End date for range query
+    """
+
+    date: Optional[Date] = None
+    from_date: Optional[Date] = None
+    to_date: Optional[Date] = None
+
+    def to_params(self) -> dict[str, Optional[object]]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary of query parameters
+        """
+        params: dict[str, Optional[object]] = {
+            "date": self.date,
+            "fromDate": self.from_date,
+            "toDate": self.to_date,
+        }
+        return params
+
+
+class NeisApi(BaseApi):
+    """NEIS 데이터 API (NEIS Data API).
+
+    Provides methods for querying school meal and schedule information from NEIS.
+    """
+
+    def get_meals(self, request: Optional[MealRequest] = None) -> list[Meal]:
+        """급식 정보 조회 (Get Meal Information).
+
+        Query school meal information for a specific date or date range.
+
+        Args:
+            request: Query parameters (optional, defaults to today)
+
+        Returns:
+            List of meals
+
+        Example:
+            >>> from datetime import date
+            >>> api = NeisApi(http_client)
+            >>>
+            >>> # Get today's meals
+            >>> today_meals = api.get_meals()
+            >>>
+            >>> # Get meals for a specific date
+            >>> request = MealRequest(date=date(2026, 2, 3))
+            >>> meals = api.get_meals(request)
+            >>>
+            >>> # Get meals for a date range
+            >>> request = MealRequest(
+            ...     from_date=date(2026, 2, 1),
+            ...     to_date=date(2026, 2, 7)
+            ... )
+            >>> week_meals = api.get_meals(request)
+        """
+        req = request or MealRequest(date=Date.today())
+        return self._get("/v1/neis/meals", params=req.to_params(), response_type=list[Meal])
+
+    def get_schedules(self, request: Optional[ScheduleRequest] = None) -> list[Schedule]:
+        """학사일정 정보 조회 (Get Schedule Information).
+
+        Query school schedule/event information for a specific date or date range.
+
+        Args:
+            request: Query parameters (optional, defaults to today)
+
+        Returns:
+            List of schedules
+
+        Example:
+            >>> from datetime import date
+            >>> api = NeisApi(http_client)
+            >>>
+            >>> # Get today's schedules
+            >>> today_events = api.get_schedules()
+            >>>
+            >>> # Get schedules for a specific date
+            >>> request = ScheduleRequest(date=date(2026, 3, 1))
+            >>> schedules = api.get_schedules(request)
+            >>>
+            >>> # Get schedules for a date range
+            >>> request = ScheduleRequest(
+            ...     from_date=date(2026, 3, 1),
+            ...     to_date=date(2026, 3, 31)
+            ... )
+            >>> month_schedules = api.get_schedules(request)
+        """
+        req = request or ScheduleRequest(date=Date.today())
+        return self._get(
+            "/v1/neis/schedules", params=req.to_params(), response_type=list[Schedule]
+        )

datagsm_openapi/api/project.py

@@ -0,0 +1,103 @@
+"""Project API module for DataGSM OpenAPI SDK."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..models import Project, ProjectResponse, ProjectSortBy, SortDirection
+from ._base import BaseApi
+
+
+@dataclass
+class ProjectRequest:
+    """프로젝트 조회 요청 파라미터 (Project Query Parameters).
+
+    Attributes:
+        project_id: Project ID for exact match
+        project_name: Project name for filtering
+        club_id: Club ID filter
+        page: Page number (default: 0)
+        size: Page size (default: 100)
+        sort_by: Sort field
+        sort_direction: Sort direction (default: ASC)
+    """
+
+    project_id: Optional[int] = None
+    project_name: Optional[str] = None
+    club_id: Optional[int] = None
+    page: int = 0
+    size: int = 100
+    sort_by: Optional[ProjectSortBy] = 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]] = {
+            "projectId": self.project_id,
+            "projectName": self.project_name,
+            "clubId": self.club_id,
+            "page": self.page,
+            "size": self.size,
+            "sortBy": self.sort_by.value if self.sort_by else None,
+            "sortDirection": self.sort_direction.value,
+        }
+        return params
+
+
+class ProjectApi(BaseApi):
+    """프로젝트 데이터 API (Project Data API).
+
+    Provides methods for querying project information.
+    """
+
+    def get_projects(self, request: Optional[ProjectRequest] = None) -> ProjectResponse:
+        """프로젝트 목록 조회 (Get Project List).
+
+        Query projects with optional filtering, sorting, and pagination.
+
+        Args:
+            request: Query parameters (optional)
+
+        Returns:
+            Paginated project response
+
+        Example:
+            >>> api = ProjectApi(http_client)
+            >>> # Get all projects
+            >>> response = api.get_projects()
+            >>> print(f"Total: {response.total_elements}")
+            >>>
+            >>> # Filter by club
+            >>> request = ProjectRequest(club_id=1)
+            >>> club_projects = api.get_projects(request)
+        """
+        req = request or ProjectRequest()
+        return self._get("/v1/projects", params=req.to_params(), response_type=ProjectResponse)
+
+    def get_project(self, project_id: int) -> Optional[Project]:
+        """특정 프로젝트 조회 (Get Specific Project).
+
+        Retrieve a single project by ID.
+
+        Args:
+            project_id: Project ID
+
+        Returns:
+            Project information if found, None otherwise
+
+        Example:
+            >>> api = ProjectApi(http_client)
+            >>> project = api.get_project(1)
+            >>> if project:
+            ...     print(f"Project: {project.name}")
+            ...     print(f"Description: {project.description}")
+        """
+        request = ProjectRequest(project_id=project_id)
+        response = self.get_projects(request)
+
+        if response.projects:
+            return response.projects[0]
+        return None

datagsm_openapi/api/student.py

@@ -0,0 +1,128 @@
+"""Student API module for DataGSM OpenAPI SDK."""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from ..models import Sex, SortDirection, Student, StudentResponse, StudentRole, StudentSortBy
+from ._base import BaseApi
+
+
+@dataclass
+class StudentRequest:
+    """학생 조회 요청 파라미터 (Student Query Parameters).
+
+    Attributes:
+        student_id: Student ID for exact match
+        name: Student name for filtering
+        email: Email address for filtering
+        grade: Grade (1-3)
+        class_num: Class number
+        number: Student number within class
+        sex: Gender filter
+        role: Student role filter
+        dormitory_room: Dormitory room number
+        is_leave_school: Filter by leave school status
+        is_graduate: Filter by graduate status
+        page: Page number (default: 0)
+        size: Page size (default: 300)
+        sort_by: Sort field
+        sort_direction: Sort direction (default: ASC)
+    """
+
+    student_id: Optional[int] = None
+    name: Optional[str] = None
+    email: Optional[str] = None
+    grade: Optional[int] = None
+    class_num: Optional[int] = None
+    number: Optional[int] = None
+    sex: Optional[Sex] = None
+    role: Optional[StudentRole] = None
+    dormitory_room: Optional[int] = None
+    is_leave_school: Optional[bool] = None
+    is_graduate: Optional[bool] = None
+    page: int = 0
+    size: int = 300
+    sort_by: Optional[StudentSortBy] = 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]] = {
+            "studentId": self.student_id,
+            "name": self.name,
+            "email": self.email,
+            "grade": self.grade,
+            "classNum": self.class_num,
+            "number": self.number,
+            "sex": self.sex.value if self.sex else None,
+            "role": self.role.value if self.role else None,
+            "dormitoryRoom": self.dormitory_room,
+            "isLeaveSchool": self.is_leave_school,
+            "isGraduated": self.is_graduate,
+            "page": self.page,
+            "size": self.size,
+            "sortBy": self.sort_by.value if self.sort_by else None,
+            "sortDirection": self.sort_direction.value,
+        }
+        return params
+
+
+class StudentApi(BaseApi):
+    """학생 데이터 API (Student Data API).
+
+    Provides methods for querying student information.
+    """
+
+    def get_students(
+        self, request: Optional[StudentRequest] = None
+    ) -> StudentResponse:
+        """학생 목록 조회 (Get Student List).
+
+        Query students with optional filtering, sorting, and pagination.
+
+        Args:
+            request: Query parameters (optional)
+
+        Returns:
+            Paginated student response
+
+        Example:
+            >>> api = StudentApi(http_client)
+            >>> # Get all students
+            >>> response = api.get_students()
+            >>> print(f"Total: {response.total_elements}")
+            >>>
+            >>> # Filter by grade
+            >>> request = StudentRequest(grade=1)
+            >>> first_graders = api.get_students(request)
+        """
+        req = request or StudentRequest()
+        return self._get("/v1/students", params=req.to_params(), response_type=StudentResponse)
+
+    def get_student(self, student_id: int) -> Optional[Student]:
+        """특정 학생 조회 (Get Specific Student).
+
+        Retrieve a single student by ID.
+
+        Args:
+            student_id: Student ID
+
+        Returns:
+            Student information if found, None otherwise
+
+        Example:
+            >>> api = StudentApi(http_client)
+            >>> student = api.get_student(123)
+            >>> if student:
+            ...     print(f"Name: {student.name}")
+        """
+        request = StudentRequest(student_id=student_id)
+        response = self.get_students(request)
+
+        if response.students:
+            return response.students[0]
+        return None

datagsm_openapi/client.py

@@ -0,0 +1,118 @@
+"""Main client class for DataGSM OpenAPI SDK."""
+
+from typing import Any, Optional
+
+from ._http import HttpClient
+from .api import ClubApi, NeisApi, ProjectApi, StudentApi
+
+
+class DataGsmClient:
+    """Main client for interacting with the DataGSM OpenAPI.
+
+    This is the main entry point for the SDK. Create an instance with your API key
+    and use it to access various API endpoints.
+
+    Example:
+        Basic usage::
+
+            with DataGsmClient(api_key="your-api-key") as client:
+                students = client.students.get_students()
+
+    Attributes:
+        base_url: Base URL for the API
+        timeout: Request timeout in seconds
+    """
+
+    DEFAULT_BASE_URL = "https://openapi.data.hellogsm.kr"
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        """Initialize the DataGSM client.
+
+        Args:
+            api_key: Your DataGSM API key
+            base_url: Base URL for the API (default: https://openapi.data.hellogsm.kr)
+            timeout: Request timeout in seconds (default: 30.0)
+        """
+        self.base_url = base_url or self.DEFAULT_BASE_URL
+        self.timeout = timeout
+        self._http_client = HttpClient(
+            base_url=self.base_url,
+            api_key=api_key,
+            timeout=timeout,
+        )
+
+        # Initialize API modules
+        self._student_api = StudentApi(self._http_client)
+        self._club_api = ClubApi(self._http_client)
+        self._project_api = ProjectApi(self._http_client)
+        self._neis_api = NeisApi(self._http_client)
+
+    @property
+    def students(self) -> StudentApi:
+        """Access the Student API.
+
+        Returns:
+            StudentApi instance
+
+        Example:
+            >>> with DataGsmClient(api_key="key") as client:
+            ...     students = client.students.get_students()
+        """
+        return self._student_api
+
+    @property
+    def clubs(self) -> ClubApi:
+        """Access the Club API.
+
+        Returns:
+            ClubApi instance
+
+        Example:
+            >>> with DataGsmClient(api_key="key") as client:
+            ...     clubs = client.clubs.get_clubs()
+        """
+        return self._club_api
+
+    @property
+    def projects(self) -> ProjectApi:
+        """Access the Project API.
+
+        Returns:
+            ProjectApi instance
+
+        Example:
+            >>> with DataGsmClient(api_key="key") as client:
+            ...     projects = client.projects.get_projects()
+        """
+        return self._project_api
+
+    @property
+    def neis(self) -> NeisApi:
+        """Access the NEIS API.
+
+        Returns:
+            NeisApi instance
+
+        Example:
+            >>> with DataGsmClient(api_key="key") as client:
+            ...     meals = client.neis.get_meals()
+        """
+        return self._neis_api
+
+    def __enter__(self) -> "DataGsmClient":
+        """Enter context manager."""
+        self._http_client.__enter__()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Exit context manager and close resources."""
+        self._http_client.__exit__(*args)
+
+    def close(self) -> None:
+        """Close the client and release resources."""
+        self._http_client.close()

datagsm_openapi/exceptions.py

@@ -0,0 +1,213 @@
+"""Exception classes for DataGSM OpenAPI SDK."""
+
+from typing import Any, Optional
+
+
+class DataGsmException(Exception):
+    """Base exception for all DataGSM API errors.
+
+    Attributes:
+        message: Human-readable error message
+        status_code: HTTP status code if available
+        response_body: Raw response body if available
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            status_code: HTTP status code
+            response_body: Raw response body
+        """
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+
+    def __str__(self) -> str:
+        """Return string representation of the exception."""
+        if self.status_code:
+            return f"[{self.status_code}] {self.message}"
+        return self.message
+
+    def __repr__(self) -> str:
+        """Return detailed representation of the exception."""
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code!r})"
+        )
+
+
+class BadRequestException(DataGsmException):
+    """Exception raised for 400 Bad Request errors.
+
+    Indicates that the request was malformed or contained invalid parameters.
+    """
+
+    def __init__(
+        self,
+        message: str = "Bad request",
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            response_body: Raw response body
+        """
+        super().__init__(message=message, status_code=400, response_body=response_body)
+
+
+class UnauthorizedException(DataGsmException):
+    """Exception raised for 401 Unauthorized errors.
+
+    Indicates that the API key is missing or invalid.
+    """
+
+    def __init__(
+        self,
+        message: str = "Unauthorized: Invalid or missing API key",
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            response_body: Raw response body
+        """
+        super().__init__(message=message, status_code=401, response_body=response_body)
+
+
+class ForbiddenException(DataGsmException):
+    """Exception raised for 403 Forbidden errors.
+
+    Indicates that the API key doesn't have permission for the requested resource.
+    """
+
+    def __init__(
+        self,
+        message: str = "Forbidden: Insufficient permissions",
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            response_body: Raw response body
+        """
+        super().__init__(message=message, status_code=403, response_body=response_body)
+
+
+class NotFoundException(DataGsmException):
+    """Exception raised for 404 Not Found errors.
+
+    Indicates that the requested resource was not found.
+    """
+
+    def __init__(
+        self,
+        message: str = "Not found",
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            response_body: Raw response body
+        """
+        super().__init__(message=message, status_code=404, response_body=response_body)
+
+
+class RateLimitException(DataGsmException):
+    """Exception raised for 429 Too Many Requests errors.
+
+    Indicates that the rate limit has been exceeded.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            response_body: Raw response body
+        """
+        super().__init__(message=message, status_code=429, response_body=response_body)
+
+
+class ServerErrorException(DataGsmException):
+    """Exception raised for 5xx Server Error responses.
+
+    Indicates that the server encountered an error processing the request.
+    """
+
+    def __init__(
+        self,
+        message: str = "Internal server error",
+        status_code: int = 500,
+        response_body: Optional[dict[str, Any]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            status_code: HTTP status code (5xx)
+            response_body: Raw response body
+        """
+        super().__init__(
+            message=message,
+            status_code=status_code,
+            response_body=response_body,
+        )
+
+
+class NetworkException(DataGsmException):
+    """Exception raised for network-related errors.
+
+    Indicates connection failures, timeouts, or other network issues.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        original_exception: Optional[Exception] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            original_exception: The underlying exception that caused this error
+        """
+        super().__init__(message=message)
+        self.original_exception = original_exception
+
+
+class ValidationException(DataGsmException):
+    """Exception raised for data validation errors.
+
+    Indicates that response data failed validation against the expected schema.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        validation_errors: Optional[list[dict[str, Any]]] = None,
+    ) -> None:
+        """Initialize the exception.
+
+        Args:
+            message: Error message
+            validation_errors: List of validation errors from Pydantic
+        """
+        super().__init__(message=message)
+        self.validation_errors = validation_errors or []