pro-sejongpeia 1.2.30__tar.gz

pro_sejongpeia-1.2.30/.gitignore

@@ -0,0 +1,91 @@
+/.idea
+/.claude/settings.local.json
+/.report
+
+# 작업 과정 문서 (projectops 이슈·보고서·점검 증거, superpowers 설계·계획) 는 추적하지 않음
+# 사용자용 문서(docs/*.md, docs/assets)는 계속 추적
+/docs/projectops/
+/docs/superpowers/
+
+# Gradle
+.gradle/
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!gradle/wrapper/gradle-wrapper.properties
+gradle.properties
+
+# Compiled Files
+*.class
+*.jar
+!gradle/wrapper/gradle-wrapper.jar
+
+# IDE - IntelliJ IDEA
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+# IDE - Eclipse
+.classpath
+.project
+.settings/
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+# IDE - VS Code
+.vscode/
+
+# IDE - NetBeans
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nbgradle/
+
+# OS Files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+.AppleDouble
+.LSOverride
+
+# Logs
+*.log
+*.log.*
+
+# Local Configuration
+*.local
+
+# Test Reports
+.report/
+
+# Test Configuration (민감 정보 포함)
+**/src/test/resources/application-dev.yml
+
+# Python (기존 항목 유지)
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Python
+python/.venv/
+python/dist/
+.pytest_cache/
+*.egg-info/
+
+# Node
+node/node_modules/
+node/dist/
+*.tgz
+
+# SDD workspace
+.superpowers/
+node/src/version.ts

pro_sejongpeia-1.2.30/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Suh Saechan
+
+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.

pro_sejongpeia-1.2.30/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: pro-sejongpeia
+Version: 1.2.30
+Summary: Sejong University login API for Python: verify students with portal SSO in one line (세종대 로그인 API)
+Project-URL: Homepage, https://cassiiopeia.github.io/pro-sejongpeia/
+Project-URL: Source, https://github.com/Cassiiopeia/pro-sejongpeia
+Project-URL: Issues, https://github.com/Cassiiopeia/pro-sejongpeia/issues
+Author: Suh Saechan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: authentication,sejong,sejong-university,sso,student-verification,세종대
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Korean
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# pro-sejongpeia (Python)
+
+**세종대 로그인 API (Python)** · Sejong University login API
+
+한국어 | [English](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/README.en.md)
+
+학번과 포털 비밀번호로 세종대 재학생 여부를 확인하고 학과, 학년, 고전독서 인증, 연락처를 가져옵니다. 표준 라이브러리 외 의존성이 없습니다.
+
+**[▶ 브라우저에서 바로 체험하기](https://cassiiopeia.github.io/pro-sejongpeia/#demo)** · 호출 한 번에 포털 로그인 한 번 (약 0.8초) · Java·Node 패키지와 같은 결과 · 비밀번호가 틀리면 바로 멈춤 · 매일 실제 포털로 점검
+
+```bash
+pip install pro-sejongpeia
+```
+
+```python
+from sejongpeia import authenticate, SejongAuthError, ErrorCode
+
+try:
+    result = authenticate("21011234", "비밀번호")
+    print(result.name, result.major, result.grade)
+except SejongAuthError as error:
+    if error.code == ErrorCode.AUTHENTICATION_FAILED:
+        print("학번 또는 비밀번호가 틀렸습니다")
+    elif error.code == ErrorCode.ACCOUNT_LOCKED:
+        print("포털 계정이 잠겼습니다. 포털에서 비밀번호를 재설정하세요")
+```
+
+| 함수 | 반환 |
+|---|---|
+| `authenticate(id, pw)` | 학생 정보 + 고전독서 + 연락처 (연락처 조회가 실패하면 연락처만 `None`) |
+| `authenticate_dhc(id, pw, include_raw=False)` | 학생 정보 + 고전독서 |
+| `authenticate_sis(id, pw, include_raw=False)` | 학생 정보 + 이메일, 전화번호, 영문 이름 |
+
+### 대신 해결해 주는 것
+
+직접 구현하려면 모두 풀어야 하는 부분입니다.
+
+- 최신 환경의 기본 설정이 막는, 포털이 유일하게 허용하는 암호(`TLS_RSA_WITH_AES_256_CBC_SHA`)를 Python `ssl` 설정으로 자동 허용
+- 방화벽이 막는 기본 User-Agent 대신 식별 가능한 User-Agent 전송
+- 여러 세종대 도메인에 걸친 SSO 쿠키와 리다이렉트 처리
+- 200 응답 안의 판정으로 비밀번호 오류, 계정 잠금, 이용 불가를 즉시 구분 (틀린 비밀번호는 재시도하지 않음)
+- DHC의 HTML 표와 SIS의 JSON을 타입이 있는 결과로 변환
+
+설정: `SejongAuthClient(timeout_seconds=10, max_retry=3, ssl_verification=True)`.
+
+에러 코드(`error.code`): `AUTHENTICATION_FAILED`, `ACCOUNT_LOCKED`, `ACCOUNT_UNAVAILABLE`, `INVALID_INPUT`, `CONNECTION_FAILED`, `CONNECTION_TIMEOUT`, `SESSION_ERROR`, `DATA_FETCH_FAILED`, `PARSE_ERROR`, `SSL_CONFIGURATION_ERROR`. 메시지가 아니라 코드로 분기하세요.
+
+> **계정 잠금.** 세종대 포털은 비밀번호를 여러 번 틀리면(약 5회) 계정을 잠급니다. <https://portal.sejong.ac.kr/jsp/inquiry/pwinquiry.jsp> 에서 비밀번호를 재설정해야 풀립니다. 라이브러리는 거부된 로그인을 재시도하지 않습니다. 누구나 학번을 입력할 수 있는 서비스라면 학번별 실패 횟수를 제한하세요.
+
+Python 3.9 이상. 세종대학교 공식 제품이 아닙니다.
+
+문서, 라이브 데모, Java·Node 버전: https://cassiiopeia.github.io/pro-sejongpeia/
+
+## English
+
+Verify a Sejong University student with a student ID and portal password, and get their major, year, classic-reading certification and contact info. The API above is the same in English; error messages are in English. Full English docs: [README.en.md](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/README.en.md).

pro_sejongpeia-1.2.30/README.md

@@ -0,0 +1,56 @@
+# pro-sejongpeia (Python)
+
+**세종대 로그인 API (Python)** · Sejong University login API
+
+한국어 | [English](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/README.en.md)
+
+학번과 포털 비밀번호로 세종대 재학생 여부를 확인하고 학과, 학년, 고전독서 인증, 연락처를 가져옵니다. 표준 라이브러리 외 의존성이 없습니다.
+
+**[▶ 브라우저에서 바로 체험하기](https://cassiiopeia.github.io/pro-sejongpeia/#demo)** · 호출 한 번에 포털 로그인 한 번 (약 0.8초) · Java·Node 패키지와 같은 결과 · 비밀번호가 틀리면 바로 멈춤 · 매일 실제 포털로 점검
+
+```bash
+pip install pro-sejongpeia
+```
+
+```python
+from sejongpeia import authenticate, SejongAuthError, ErrorCode
+
+try:
+    result = authenticate("21011234", "비밀번호")
+    print(result.name, result.major, result.grade)
+except SejongAuthError as error:
+    if error.code == ErrorCode.AUTHENTICATION_FAILED:
+        print("학번 또는 비밀번호가 틀렸습니다")
+    elif error.code == ErrorCode.ACCOUNT_LOCKED:
+        print("포털 계정이 잠겼습니다. 포털에서 비밀번호를 재설정하세요")
+```
+
+| 함수 | 반환 |
+|---|---|
+| `authenticate(id, pw)` | 학생 정보 + 고전독서 + 연락처 (연락처 조회가 실패하면 연락처만 `None`) |
+| `authenticate_dhc(id, pw, include_raw=False)` | 학생 정보 + 고전독서 |
+| `authenticate_sis(id, pw, include_raw=False)` | 학생 정보 + 이메일, 전화번호, 영문 이름 |
+
+### 대신 해결해 주는 것
+
+직접 구현하려면 모두 풀어야 하는 부분입니다.
+
+- 최신 환경의 기본 설정이 막는, 포털이 유일하게 허용하는 암호(`TLS_RSA_WITH_AES_256_CBC_SHA`)를 Python `ssl` 설정으로 자동 허용
+- 방화벽이 막는 기본 User-Agent 대신 식별 가능한 User-Agent 전송
+- 여러 세종대 도메인에 걸친 SSO 쿠키와 리다이렉트 처리
+- 200 응답 안의 판정으로 비밀번호 오류, 계정 잠금, 이용 불가를 즉시 구분 (틀린 비밀번호는 재시도하지 않음)
+- DHC의 HTML 표와 SIS의 JSON을 타입이 있는 결과로 변환
+
+설정: `SejongAuthClient(timeout_seconds=10, max_retry=3, ssl_verification=True)`.
+
+에러 코드(`error.code`): `AUTHENTICATION_FAILED`, `ACCOUNT_LOCKED`, `ACCOUNT_UNAVAILABLE`, `INVALID_INPUT`, `CONNECTION_FAILED`, `CONNECTION_TIMEOUT`, `SESSION_ERROR`, `DATA_FETCH_FAILED`, `PARSE_ERROR`, `SSL_CONFIGURATION_ERROR`. 메시지가 아니라 코드로 분기하세요.
+
+> **계정 잠금.** 세종대 포털은 비밀번호를 여러 번 틀리면(약 5회) 계정을 잠급니다. <https://portal.sejong.ac.kr/jsp/inquiry/pwinquiry.jsp> 에서 비밀번호를 재설정해야 풀립니다. 라이브러리는 거부된 로그인을 재시도하지 않습니다. 누구나 학번을 입력할 수 있는 서비스라면 학번별 실패 횟수를 제한하세요.
+
+Python 3.9 이상. 세종대학교 공식 제품이 아닙니다.
+
+문서, 라이브 데모, Java·Node 버전: https://cassiiopeia.github.io/pro-sejongpeia/
+
+## English
+
+Verify a Sejong University student with a student ID and portal password, and get their major, year, classic-reading certification and contact info. The API above is the same in English; error messages are in English. Full English docs: [README.en.md](https://github.com/Cassiiopeia/pro-sejongpeia/blob/main/README.en.md).

pro_sejongpeia-1.2.30/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pro-sejongpeia"
+version = "1.2.30"
+description = "Sejong University login API for Python: verify students with portal SSO in one line (세종대 로그인 API)"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Suh Saechan" }]
+keywords = ["sejong", "sejong-university", "세종대", "authentication", "sso", "student-verification"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Intended Audience :: Developers",
+  "Natural Language :: Korean",
+  "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://cassiiopeia.github.io/pro-sejongpeia/"
+Source = "https://github.com/Cassiiopeia/pro-sejongpeia"
+Issues = "https://github.com/Cassiiopeia/pro-sejongpeia/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sejongpeia"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src", "tests"]

pro_sejongpeia-1.2.30/src/sejongpeia/__init__.py

@@ -0,0 +1,61 @@
+"""세종대 로그인 API: 학번·비밀번호로 세종대학교 포털(SSO) 인증
+
+    from sejongpeia import authenticate
+    result = authenticate("21011234", "password")
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # 버전 단일 원본: pyproject.toml (projectops 가 version.yml 과 함께 갱신)
+    __version__ = version("pro-sejongpeia")
+except PackageNotFoundError:  # 설치 없이 소스로 실행 (테스트)
+    __version__ = "0.0.0-dev"
+
+from .client import SejongAuthClient  # noqa: E402
+from .errors import ErrorCode, SejongAuthError  # noqa: E402
+from .models import (  # noqa: E402
+    ClassicCertification,
+    ClassicContestRecord,
+    ClassicExamRecord,
+    ClassicSubjectRecord,
+    SejongAuthResult,
+    SejongClassicReading,
+    SejongDhcAuthResult,
+    SejongSisAuthResult,
+)
+from .public_data import SejongPublicData  # noqa: E402
+from .public_data_models import (  # noqa: E402
+    CafeteriaMenuItem, CalendarEvent, CampusPlace, CourseType, Department, DormitoryMenuDay,
+    DormitoryNotice, DormitoryNotices, ExtracurricularEvent, Lecture, OrganizationCategory,
+    SelectiveDomain, Term,
+)
+
+_default_client = SejongAuthClient()
+
+
+def authenticate(student_id: str, password: str) -> SejongAuthResult:
+    """통합 인증 (기본 설정: 10초, 재시도 3회, 인증서 검증)"""
+    return _default_client.authenticate(student_id, password)
+
+
+def authenticate_dhc(student_id: str, password: str, include_raw: bool = False) -> SejongDhcAuthResult:
+    """DHC 인증: 학생 정보 + 고전독서"""
+    return _default_client.authenticate_dhc(student_id, password, include_raw=include_raw)
+
+
+def authenticate_sis(student_id: str, password: str, include_raw: bool = False) -> SejongSisAuthResult:
+    """SIS 인증: 학생 정보 + 연락처"""
+    return _default_client.authenticate_sis(student_id, password, include_raw=include_raw)
+
+
+__all__ = [
+    "authenticate", "authenticate_dhc", "authenticate_sis", "SejongAuthClient",
+    "SejongAuthError", "ErrorCode",
+    "SejongAuthResult", "SejongDhcAuthResult", "SejongSisAuthResult", "SejongClassicReading",
+    "ClassicCertification", "ClassicExamRecord", "ClassicSubjectRecord", "ClassicContestRecord",
+    "SejongPublicData", "OrganizationCategory", "Term", "Department", "CourseType", "SelectiveDomain", "Lecture",
+    "CalendarEvent", "DormitoryMenuDay", "DormitoryNotice", "DormitoryNotices", "CafeteriaMenuItem",
+    "CampusPlace", "ExtracurricularEvent",
+    "__version__",
+]

pro_sejongpeia-1.2.30/src/sejongpeia/client.py

@@ -0,0 +1,207 @@
+"""세종대 포털 인증 클라이언트: 입력 검증 > 포털 로그인(재시도) > SSO > 데이터 조회 > 파싱 (흐름: spec/PORTAL_FLOW.md)"""
+
+import base64
+import json
+import logging
+import ssl
+import urllib.parse
+from datetime import datetime
+from typing import Callable, Optional
+
+from . import __version__
+from .errors import ErrorCode, SejongAuthError
+from .models import SejongAuthResult, SejongDhcAuthResult, SejongSisAuthResult
+from .parsers import ensure_portal_login_accepted, ensure_sis_logged_in, parse_classic_reading, parse_sis_user_info, parse_student_info
+from .portal_main_parser import parse_parent_unit_name
+from .transport import USER_AGENT, HttpResponse, UrllibSession, create_ssl_context
+
+# 라이브러리 로거: 출력 방식은 사용하는 앱이 설정
+LOGGER = logging.getLogger("sejongpeia")
+
+PORTAL_LOGIN_URL = "https://portal.sejong.ac.kr/jsp/login/login_action.jsp"
+PORTAL_REFERER = "https://portal.sejong.ac.kr"
+# 포털이 요구하는 초기 쿠키 (없으면 로그인 폼 거부)
+PORTAL_DEFAULT_COOKIE = "chknos=false"
+
+# 로그인 후 SSO 대상 (rtUrl)
+CLASSIC_RETURN_URL = "classic.sejong.ac.kr"
+SIS_RETURN_URL = "sjpt.sejong.ac.kr/main/view/Login/doSsoLogin.do?p="
+
+CLASSIC_SSO_URL = "https://classic.sejong.ac.kr/_custom/sejong/sso/sso-return.jsp?returnUrl=https://classic.sejong.ac.kr/classic/index.do"
+CLASSIC_STATUS_URL = "https://classic.sejong.ac.kr/classic/reading/status.do"
+# 포털 메인 (소속 표기 조회), 세션 만료 시 돌아오는 로그인 페이지는 form 대상 문구로 판별
+PORTAL_MAIN_URL = "https://portal.sejong.ac.kr/user/index.do"
+PORTAL_LOGIN_PAGE_MARKER = "login_action.jsp"
+SIS_SSO_URL = "https://sjpt.sejong.ac.kr/main/view/Login/doSsoLogin.do?p="
+SIS_USER_INFO_URL = "https://sjpt.sejong.ac.kr/main/sys/UserInfo/initUserInfo.do"
+SIS_ORIGIN = "https://sjpt.sejong.ac.kr"
+# 브라우저 초기 호출과 같은 빈 addParam (JSON > URL 폼 인코딩 > Base64)
+SIS_EMPTY_ADD_PARAM = base64.b64encode(
+    urllib.parse.quote_plus('{"_runIntgUsrNo":"","_runPgLoginDt":"","_runningSejong":""}').encode("utf-8")
+).decode("ascii")
+
+HTTP_UNAUTHORIZED = 401
+
+
+class SejongAuthClient:
+    """세종대 포털 인증 (설정: 제한 시간 초, 로그인 재시도 횟수, 인증서 검증)"""
+
+    def __init__(self, timeout_seconds: float = 10, max_retry: int = 3, ssl_verification: bool = True,
+                 _session_factory: Optional[Callable[[], object]] = None):
+        self.timeout_seconds = timeout_seconds
+        self.max_retry = max_retry
+        self.ssl_verification = ssl_verification
+        self._session_factory = _session_factory or self._create_session
+
+    def authenticate(self, student_id: str, password: str) -> SejongAuthResult:
+        """통합 인증: 포털 로그인 1회 > DHC 학생 정보·고전독서 > 같은 세션으로 SIS 연락처, 포털 메인 상위 소속 (보조 조회 실패는 무시하고 None)"""
+        self._validate_credentials(student_id, password)
+        session = self._session_factory()
+        self._login(session, student_id, password, CLASSIC_RETURN_URL)
+        dhc_result = self._fetch_dhc_with_session(session, should_include_raw_html=False)
+
+        email = phone_number = english_name = user_category = None
+        try:
+            sis_user_info = parse_sis_user_info(self._fetch_sis_json_with_session(session))
+            email, phone_number, english_name = sis_user_info.email, sis_user_info.phone_number, sis_user_info.english_name
+            user_category = sis_user_info.user_category
+        except Exception as error:  # SIS 는 연락처 보조 조회 > 어떤 실패든 통합 결과를 막지 않음 (Java 와 동일)
+            LOGGER.warning("[sejong auth] SIS contact lookup failed (ignored) : %s", type(error).__name__)
+        parent_unit_name = self._fetch_parent_unit_name(session, dhc_result.major)
+
+        return SejongAuthResult(
+            success=True, student_id=dhc_result.student_id, name=dhc_result.name, major=dhc_result.major,
+            grade=dhc_result.grade, status=dhc_result.status, classic_reading=dhc_result.classic_reading,
+            email=email, phone_number=phone_number, english_name=english_name, user_category=user_category,
+            parent_unit_name=parent_unit_name, authenticated_at=datetime.now(),
+        )
+
+    def authenticate_dhc(self, student_id: str, password: str, include_raw: bool = False) -> SejongDhcAuthResult:
+        """DHC 인증: 학생 정보 + 고전독서 (include_raw=True 면 원본 HTML 포함)"""
+        self._validate_credentials(student_id, password)
+        return self._fetch_dhc(student_id, password, should_include_raw_html=include_raw)
+
+    def authenticate_sis(self, student_id: str, password: str, include_raw: bool = False) -> SejongSisAuthResult:
+        """SIS 인증: 학생 정보 + 연락처 (학년·상태 빈 문자열, include_raw=True 면 원본 JSON 포함)"""
+        self._validate_credentials(student_id, password)
+        json_text = self._fetch_sis_json(student_id, password)
+        user_info = parse_sis_user_info(json_text)
+        return SejongSisAuthResult(
+            success=True, student_id=user_info.student_id, name=user_info.name, major=user_info.major,
+            grade="", status="", email=user_info.email, phone_number=user_info.phone_number,
+            english_name=user_info.english_name, user_category=user_info.user_category, authenticated_at=datetime.now(),
+            raw_json=json_text if include_raw else None,
+        )
+
+    def _fetch_dhc(self, student_id: str, password: str, should_include_raw_html: bool) -> SejongDhcAuthResult:
+        """포털 로그인 > DHC 조회"""
+        session = self._session_factory()
+        self._login(session, student_id, password, CLASSIC_RETURN_URL)
+        return self._fetch_dhc_with_session(session, should_include_raw_html)
+
+    def _fetch_dhc_with_session(self, session, should_include_raw_html: bool) -> SejongDhcAuthResult:
+        """로그인된 세션 > classic SSO > 고전독서 페이지 > 학생 정보·고전독서 파싱"""
+        self._expect_session_step(self._call(session, "GET", CLASSIC_SSO_URL), "SSO redirect failed")
+        html = self._expect_data(self._call(session, "GET", CLASSIC_STATUS_URL), "Classic reading page request failed")
+        student_info = parse_student_info(html)
+        return SejongDhcAuthResult(
+            success=True, student_id=student_info.student_id, name=student_info.name, major=student_info.major,
+            grade=student_info.grade, status=student_info.status, classic_reading=parse_classic_reading(html),
+            authenticated_at=datetime.now(), raw_html=html if should_include_raw_html else None,
+        )
+
+    def _fetch_sis_json(self, student_id: str, password: str) -> str:
+        """포털 로그인 (rtUrl sjpt) > SIS 조회"""
+        session = self._session_factory()
+        self._login(session, student_id, password, SIS_RETURN_URL)
+        return self._fetch_sis_json_with_session(session)
+
+    def _fetch_sis_json_with_session(self, session) -> str:
+        """로그인된 세션 > sjpt SSO > initUserInfo JSON"""
+        self._expect_session_step(
+            self._call(session, "GET", SIS_SSO_URL, headers={"Referer": PORTAL_REFERER}), "SIS SSO page request failed")
+        response = self._call(session, "POST", f"{SIS_USER_INFO_URL}?addParam={SIS_EMPTY_ADD_PARAM}", data=b"{}", headers={
+            "Accept": "application/json",
+            "Content-Type": "application/json; charset=UTF-8",
+            "Referer": SIS_SSO_URL,
+            "Origin": SIS_ORIGIN,
+        })
+        json_text = self._expect_data(response, "initUserInfo API request failed")
+        # 틀린 비밀번호는 401 이 아니라 200 + _SUBMIT_ERROR_(LOGOUT)
+        ensure_sis_logged_in(json_text)
+        return json_text
+
+    def _fetch_parent_unit_name(self, session, major: str) -> Optional[str]:
+        """같은 세션으로 포털 메인 1회 조회 > 상위 소속명 (재시도 없음, 호출 실패·세션 만료·빈 본문은 None, 요소 없음은 빈 문자열)"""
+        try:
+            response = self._call(session, "GET", PORTAL_MAIN_URL, headers={"Referer": PORTAL_REFERER})
+            if not response.is_successful or not response.body:
+                return None
+            html = response.text()
+            if PORTAL_LOGIN_PAGE_MARKER in html:
+                return None
+            return parse_parent_unit_name(html, major)
+        except Exception as error:  # 부가 정보 > 어떤 실패든 통합 결과를 막지 않음
+            LOGGER.warning("[sejong auth] portal main lookup failed (ignored) : %s", type(error).__name__)
+            return None
+
+    def _login(self, session, student_id: str, password: str, return_url: str) -> None:
+        """포털 로그인 (실패 응답·시간 초과 시 max_retry 회까지) > 포털 판정값 확인 (틀린 비밀번호·잠금은 재시도 없이 즉시 실패)"""
+        form = urllib.parse.urlencode({"mainLogin": "N", "rtUrl": return_url, "id": student_id, "password": password})
+        headers = {"Content-Type": "application/x-www-form-urlencoded", "Referer": PORTAL_REFERER, "Cookie": PORTAL_DEFAULT_COOKIE}
+        for attempt in range(1, self.max_retry + 1):
+            try:
+                response = self._call_raw(session, "POST", PORTAL_LOGIN_URL, data=form.encode("utf-8"), headers=headers)
+                if response.is_successful:
+                    ensure_portal_login_accepted(response.text())
+                    return
+            except TimeoutError as error:
+                if attempt == self.max_retry:
+                    raise SejongAuthError(ErrorCode.CONNECTION_TIMEOUT) from error
+        raise SejongAuthError(ErrorCode.CONNECTION_FAILED, f"Max retry count exceeded : {self.max_retry}")
+
+    def _call(self, session, method: str, url: str, **kwargs) -> HttpResponse:
+        """로그인 외 요청 (시간 초과·네트워크 오류 > CONNECTION_FAILED)"""
+        try:
+            return self._call_raw(session, method, url, **kwargs)
+        except TimeoutError as error:
+            raise SejongAuthError(ErrorCode.CONNECTION_FAILED) from error
+
+    @staticmethod
+    def _call_raw(session, method: str, url: str, **kwargs) -> HttpResponse:
+        try:
+            return session.request(method, url, **kwargs)
+        except (TimeoutError, SejongAuthError):
+            raise
+        except ssl.SSLError as error:
+            raise SejongAuthError(ErrorCode.CONNECTION_FAILED, "TLS handshake with the portal failed") from error
+        except OSError as error:
+            raise SejongAuthError(ErrorCode.CONNECTION_FAILED) from error
+
+    @staticmethod
+    def _expect_session_step(response: HttpResponse, failure_message: str) -> None:
+        if not response.is_successful:
+            raise SejongAuthError(ErrorCode.SESSION_ERROR, f"{failure_message} : {response.status}")
+
+    @staticmethod
+    def _expect_data(response: HttpResponse, failure_message: str) -> str:
+        """데이터 응답 판정: 401 > AUTHENTICATION_FAILED, 그 외 200 아님·빈 본문 > DATA_FETCH_FAILED"""
+        if response.status == HTTP_UNAUTHORIZED:
+            raise SejongAuthError(ErrorCode.AUTHENTICATION_FAILED)
+        if response.status != 200 or not response.body:
+            raise SejongAuthError(ErrorCode.DATA_FETCH_FAILED, f"{failure_message} : {response.status}")
+        return response.text()
+
+    @staticmethod
+    def _validate_credentials(student_id: Optional[str], password: Optional[str]) -> None:
+        if not student_id or not str(student_id).strip():
+            raise SejongAuthError(ErrorCode.INVALID_INPUT, "Student ID is empty")
+        if not password or not str(password).strip():
+            raise SejongAuthError(ErrorCode.INVALID_INPUT, "Password is empty")
+
+    def _create_session(self) -> UrllibSession:
+        try:
+            ssl_context = create_ssl_context(self.ssl_verification)
+        except ssl.SSLError as error:
+            raise SejongAuthError(ErrorCode.SSL_CONFIGURATION_ERROR) from error
+        return UrllibSession(ssl_context, self.timeout_seconds, USER_AGENT)

pro_sejongpeia-1.2.30/src/sejongpeia/errors.py

@@ -0,0 +1,43 @@
+"""에러 코드·예외: Java SejongAuthErrorCode 와 같은 이름 (spec/RESULT_SCHEMA.md)"""
+
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    """인증 실패 사유 코드 (값 = Java enum 이름)"""
+
+    INVALID_INPUT = "INVALID_INPUT"
+    AUTHENTICATION_FAILED = "AUTHENTICATION_FAILED"
+    CONNECTION_FAILED = "CONNECTION_FAILED"
+    CONNECTION_TIMEOUT = "CONNECTION_TIMEOUT"
+    SESSION_ERROR = "SESSION_ERROR"
+    DATA_FETCH_FAILED = "DATA_FETCH_FAILED"
+    PARSE_ERROR = "PARSE_ERROR"
+    SSL_CONFIGURATION_ERROR = "SSL_CONFIGURATION_ERROR"
+    ACCOUNT_LOCKED = "ACCOUNT_LOCKED"
+    ACCOUNT_UNAVAILABLE = "ACCOUNT_UNAVAILABLE"
+
+
+# 코드별 기본 메시지 (Java 메시지와 같은 영어 문구)
+DEFAULT_MESSAGE_BY_CODE = {
+    ErrorCode.INVALID_INPUT: "Invalid input.",
+    ErrorCode.AUTHENTICATION_FAILED: "Sejong University portal authentication failed. Check the student ID and password.",
+    ErrorCode.CONNECTION_FAILED: "Cannot connect to the Sejong University portal.",
+    ErrorCode.CONNECTION_TIMEOUT: "Connection to the Sejong University portal timed out.",
+    ErrorCode.SESSION_ERROR: "An error occurred while handling the portal session.",
+    ErrorCode.DATA_FETCH_FAILED: "Failed to fetch student information.",
+    ErrorCode.PARSE_ERROR: "Failed to parse student information.",
+    ErrorCode.SSL_CONFIGURATION_ERROR: "Failed to configure SSL.",
+    ErrorCode.ACCOUNT_LOCKED: "The portal account is locked after too many wrong passwords. "
+    "Reset the password at https://portal.sejong.ac.kr/jsp/inquiry/pwinquiry.jsp",
+    ErrorCode.ACCOUNT_UNAVAILABLE: "The portal account cannot sign in (use period ended or blocked by the administrator).",
+}
+
+
+class SejongAuthError(Exception):
+    """세종 인증 실패 (code 로 분기, 메시지에 비밀번호·개인정보 없음)"""
+
+    def __init__(self, code: ErrorCode, message: str = ""):
+        self.code = code
+        self.message = message or DEFAULT_MESSAGE_BY_CODE[code]
+        super().__init__(f"{code.value}: {self.message}")