Metadata-Version: 2.4
Name: korail-mobile-api
Version: 4.0.0
Summary: Unauthenticated read-only Python client for selected KORAIL mobile data
Author: yakisoba0728
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/yakisoba0728/korail-mobile-api
Project-URL: Documentation, https://yaki.kr/korail-mobile-api/
Project-URL: Repository, https://github.com/yakisoba0728/korail-mobile-api
Project-URL: Issues, https://github.com/yakisoba0728/korail-mobile-api/issues
Project-URL: Changelog, https://github.com/yakisoba0728/korail-mobile-api/blob/v4.0.0/CHANGELOG.md
Keywords: korail,ktx,railway,train,schedule,api,client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24.1
Provides-Extra: dev
Requires-Dist: actionlint-py>=1.7.12; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: build>=1.2.2; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Requires-Dist: ruff>=0.11; extra == "dev"
Requires-Dist: mypy>=1.18.1; extra == "dev"
Requires-Dist: pyright>=1.1.400; extra == "dev"
Requires-Dist: setuptools>=78.1.1; extra == "dev"
Requires-Dist: packaging>=24.2; extra == "dev"
Dynamic: license-file

> [!TIP]
> 이 프로젝트가 도움이 됐다면 [저장소 스타](https://github.com/yakisoba0728/korail-mobile-api)와 [개발자 팔로우](https://github.com/yakisoba0728)를 남겨 주세요. 둘 다 선택 사항이며 개발을 이어 가는 데 힘이 됩니다.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/v4.0.0/docs/assets/banner-dark.svg">
    <img src="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/v4.0.0/docs/assets/banner-light.svg" alt="korail-mobile-api — 로그인 없는 조회 전용 Python 클라이언트" width="100%">
  </picture>
</p>

<p align="center">
  <a href="https://github.com/yakisoba0728/korail-mobile-api/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://github.com/yakisoba0728/korail-mobile-api/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI · main"></a>
  <a href="https://pypi.org/project/korail-mobile-api/4.0.0/"><img src="https://img.shields.io/pypi/v/korail-mobile-api" alt="PyPI"></a>
  <img src="https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776AB?logo=python&amp;logoColor=white" alt="Python 3.11 | 3.12 | 3.13 | 3.14">
  <img src="https://img.shields.io/badge/typing-mypy%20strict-2A6DB2" alt="mypy strict">
  <a href="LICENSE"><img src="https://img.shields.io/github/license/yakisoba0728/korail-mobile-api" alt="Apache License 2.0"></a>
</p>

<p align="center">
  <a href="https://yaki.kr/korail-mobile-api/getting-started/">시작하기</a> ·
  <a href="https://yaki.kr/korail-mobile-api/api/">API 레퍼런스</a> ·
  <a href="https://yaki.kr/korail-mobile-api/concepts/how-it-works/">요청 흐름</a> ·
  <a href="https://yaki.kr/korail-mobile-api/migration-4.0/">4.0으로 옮기기</a>
</p>

열차 운행 스케줄, 역 정보와 공통 데이터를 조회하는 비공식 동기 Python 클라이언트입니다. **4.0.0은 로그인·DynaPath·NetFunnel 없이 사용하는 조회 기능 14개**를 제공합니다. Python 3.11 이상이 필요하며 런타임 의존성은 HTTPX 하나입니다.

> **4.0은 3.x와 호환되지 않습니다.** 인증·예약·결제 기능을 제거한 조회 전용 버전입니다. 기존 사용자는 [마이그레이션 안내](https://yaki.kr/korail-mobile-api/migration-4.0/)를 먼저 확인하세요.

> [!IMPORTANT]
> **4.0 기능 축소 안내**
>
> 한국철도공사(코레일) 측의 소스코드 삭제 또는 저장소 비공개 요청에 대응하여, 기존 기능을 조회 전용으로 축소했습니다.
> 로그인·세션·DynaPath·NetFunnel, 일반 직통·환승 검색과 운임, 예약·발권·결제·환불, 계정·승차권·패스·체크인·공항버스 운행·좌석 조회 및 관련 구현을 제거했습니다.
> 유지하는 기능은 아래의 조회 14개이며, 자세한 변경 사항은 [4.0 마이그레이션 안내](https://yaki.kr/korail-mobile-api/migration-4.0/)에 있습니다.

## 설치

Python 3.11 이상이 필요합니다. 필수 런타임 의존성은 HTTPX 하나입니다.

```sh
python -m pip install --upgrade korail-mobile-api
```

이 문서와 같은 버전을 고정하려면 `korail-mobile-api==4.0.0`으로 설치하세요. 가상환경 설정과 소스 설치는 [시작하기](https://yaki.kr/korail-mobile-api/getting-started/)에 있습니다. 로그인 정보와 로컬 세션 파일은 필요하지 않습니다.

## 빠르게 써보기

열차 한 편의 운행 스케줄은 운행일과 열차번호로 조회합니다. 로그인 정보와 로컬 세션 파일은 필요하지 않습니다.

```python
from datetime import datetime, timedelta, timezone

from korail_mobile_api import KorailClient

kst = timezone(timedelta(hours=9))
run_date = (datetime.now(kst) + timedelta(days=1)).strftime("%Y%m%d")
with KorailClient() as client:
    schedule = client.get_train_schedule(run_date, "00001")
    for stop in schedule.stops:
        print(stop.station_name, stop.arrival_time, stop.departure_time)
```

<p align="center">
  <img src="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/v4.0.0/docs/assets/demo.svg" alt="운행 스케줄 조회 예시 · 합성 데이터" width="100%">
</p>

날짜와 열차번호는 실제 조회할 대상으로 바꾸세요. 예제를 실행하면 서버에 조회 요청을 보냅니다. 위 그림은 실행 화면의 구성을 보여 주는 합성 데이터입니다.

좌석배정용 열차 목록의 전체 입력 예제는 [시작하기](https://yaki.kr/korail-mobile-api/getting-started/)에 있습니다. 일반 `search_trains`와는 다른 조회 경로입니다. 전체 역 목록은 `client.list_stations()`로 받을 수 있습니다.

## 지원 기능

| 메서드 | 기능 | 반환 타입 |
|---|---|---|
| `get_train_schedule` | 열차 한 편의 정차역·시각·지연 | `TrainScheduleResponse` |
| `get_seat_assignment_schedule` | 좌석배정용 열차 목록 | `SeatAssignmentScheduleResponse` |
| `list_stations` | 전체 역 코드·이름·좌표 | `StationDataResponse` |
| `get_station_list_version` | 역 데이터 판본과 수록 역 수 | `StationInfoResponse` |
| `get_train_calendar` | 운행일 달력 | `TrainCalendarResponse` |
| `list_transfer_stations` | 구간별 환승 가능 역 | `TransferStationListResponse` |
| `get_free_seat_cars` | 자유석 호차 안내 | `FreeSeatCarResponse` |
| `get_service_status` | 서비스 운영 상태 | `ServiceStatusResponse` |
| `get_app_data` | 앱 메인 캐시·버전·공지 | `AppDataResponse` |
| `get_common_codes` | 공통 코드와 설정 | `BaseKorailResponse` |
| `get_uuid` | 서버 발급 단말 검증값 | `UuidResponse` |
| `list_crew_request_reasons` | 승무원 호출 사유 목록 | `CrewRequestListResponse` |
| `list_maas_menus` | 일반 부가서비스 메뉴 | `MaasMenuListResponse` |
| `list_maas_stations` | 부가서비스 지원 역 | `StationDataResponse` |

일반 직통·환승 열차 검색, 운임, 예약·취소, 발권·결제·환불, 계정·승차권, 체크인, 패스와 공항버스 운행·좌석 조회는 제공하지 않습니다. 관련 인증·세션·토큰·대기열 구현과 설정도 포함하지 않습니다.

## 요청 흐름

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/v4.0.0/docs/assets/flow-dark.svg">
    <img src="https://raw.githubusercontent.com/yakisoba0728/korail-mobile-api/v4.0.0/docs/assets/flow-light.svg" alt="입력 검사 → 조회 전송 → 응답 파싱 → dataclass" width="100%">
  </picture>
</p>

입력을 검사하고 지원 조회 경로에 한 번 요청한 뒤 응답을 dataclass로 읽습니다. 내부 규칙과 원문 보존 방식은 [요청 흐름](https://yaki.kr/korail-mobile-api/concepts/how-it-works/)에 정리했습니다.

## 응답과 연결

- 응답은 타입이 지정된 dataclass이며 목록은 tuple로 반환합니다. 서버가 생략한 선택 필드는 `None`일 수 있습니다.
- `with KorailClient()` 또는 `close()`로 HTTP 연결을 정리합니다.
- 자동 페이지 순회·재시도·리다이렉트·자동 로그인은 없습니다. 쿠키와 환경변수 프록시도 사용하지 않습니다.
- HTTP 실패, 서버의 업무 오류, 잘못된 응답 형식은 각각 구분된 예외로 반환합니다.
- 응답과 예외의 `raw`는 자동 마스킹되지 않습니다. 단말 검증값을 포함한 원문을 그대로 로그에 남기지 마세요.

## 자주 묻는 질문

**로그인 없이 일반 열차 검색도 가능한가요?** 4.0은 운행 스케줄과 좌석배정용 목록만 제공합니다. 일반 직통·환승 검색은 제거했으며 두 조회를 같은 API로 취급하지 않습니다.

**3.x를 쓰던 코드는 그대로 실행되나요?** 지원 메서드 14개의 이름은 유지하지만 간편 API와 인증·거래 기능 및 관련 모델은 제거했습니다. [마이그레이션 안내](https://yaki.kr/korail-mobile-api/migration-4.0/)를 확인하세요.

**서버가 P058이나 MACRO ERROR를 반환하면요?** `KorailAppError`에서 서버 코드와 메시지를 확인할 수 있습니다. 자동 로그인·대기열 처리·재시도는 수행하지 않습니다.

**4.0의 실서버 성공을 확인한 건가요?** 유지 범위의 근거는 3.0.0에서 세 기능을 모두 끈 관측입니다. 4.0 자체의 검증은 합성 응답을 이용한 오프라인 검사이며 [확인 범위](https://yaki.kr/korail-mobile-api/status/)를 구분해 기록했습니다.

## 문서와 참여

4.0 API에 맞춘 배포 문서입니다.

- [설치와 사용 예제](https://yaki.kr/korail-mobile-api/getting-started/)
- [API 목록](https://yaki.kr/korail-mobile-api/api/) · [설정](https://yaki.kr/korail-mobile-api/guide/configuration/) · [오류 처리](https://yaki.kr/korail-mobile-api/guide/errors/)
- [3.x에서 4.0으로 옮기기](https://yaki.kr/korail-mobile-api/migration-4.0/)
- [검증 범위](https://yaki.kr/korail-mobile-api/status/) · [변경 이력](https://github.com/yakisoba0728/korail-mobile-api/blob/v4.0.0/CHANGELOG.md) · [개발과 검증](https://yaki.kr/korail-mobile-api/releasing/)

유지한 기능의 실서버 응답은 2026년 10월 25일, **3.0.0에서 로그인·DynaPath·NetFunnel을 모두 끈 조건**으로 확인했습니다. 4.0.0 코드는 합성 응답과 네트워크 차단을 이용해 검사합니다. 이 둘은 검증 대상이 다르며 모든 날짜·입력의 성공을 보장하지 않습니다.

버그나 문서 개선은 [이슈](https://github.com/yakisoba0728/korail-mobile-api/issues)와 Pull Request로 참여해 주세요. 제보할 때는 원문 응답과 단말 검증값 대신 사용 버전·입력 조건·오류 코드를 정리해 주세요.

## 개발

[개발과 검증](https://yaki.kr/korail-mobile-api/releasing/)에 로컬 검사와 문서 미리보기 명령이 있습니다. [동작 규칙](https://github.com/yakisoba0728/korail-mobile-api/blob/v4.0.0/checks/BEHAVIOR.md), [오프라인 검사 기준](https://github.com/yakisoba0728/korail-mobile-api/blob/v4.0.0/checks/ACCEPTANCE.md), [에이전트 작업 가이드](https://github.com/yakisoba0728/korail-mobile-api/blob/v4.0.0/AGENTS.md)도 함께 확인하세요. 테스트에서는 실제 네트워크를 차단합니다.

## 라이선스와 서비스 이용

소스는 [Apache License 2.0](https://github.com/yakisoba0728/korail-mobile-api/blob/v4.0.0/LICENSE)으로 제공합니다. 이 프로젝트는 KORAIL의 공식 서비스나 제휴 프로젝트가 아닙니다. 서버 응답 여부가 공식 이용 허가를 뜻하지 않으며, 소스 라이선스가 서버 데이터나 서비스 이용 권한을 부여하지는 않습니다. 자세한 내용은 [프로젝트와 데이터 이용](https://yaki.kr/korail-mobile-api/legal/)을 참고하세요.
