comci 0.1.0__tar.gz

comci-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: comci
+Version: 0.1.0
+Summary: Comci.net 시간표 API 비공식 클라이언트
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+
+# Comci.net 시간표 API 클라이언트
+
+컴시간(comci.net) 비공식 API를 사용하여 학교 검색 및 시간표 조회를 할 수 있는 Python 모듈입니다.
+
+## 설치
+
+```bash
+pip install -r requirements.txt
+```
+
+## 사용법
+
+### 1. 학교 검색 (지역, 학교명, 학교코드)
+
+```python
+from comci import search_schools
+
+# "신송" 검색
+schools = search_schools("신송")
+for s in schools:
+    print(s["region"], s["school_name"], s["school_code"])
+# 인천 신송중학교 49654
+# 인천 신송고등학교 51825
+```
+
+### 2. 특정 학년/반 시간표 조회
+
+```python
+from comci import get_timetable
+
+# 1학년 1반 시간표 (정리.md 반환 구조)
+timetable = get_timetable(49654, grade=1, class_num=1)
+# {"월": [...], "화": [...], "수": [...], "목": [...], "금": [...]}
+```
+
+### 3. 전체 학년/반 시간표 조회
+
+```python
+# 학년, 반 미지정 시 전체
+timetable = get_timetable(49654)
+# {"1학년 1반": {...}, "1학년 2반": {...}, ...}
+```
+
+### 4. 검색 후 바로 시간표 조회
+
+```python
+from comci import search_and_get_timetable
+
+timetable = search_and_get_timetable("신송", school_index=0, grade=1, class_num=1)
+```
+
+## 프로젝트 구조
+
+```
+comci/
+├── __init__.py      # 패키지 진입점
+├── config.py        # API URL, 상수
+├── school_search.py # 학교 검색
+├── timetable.py     # 시간표 API 및 파싱
+└── client.py        # 통합 클라이언트
+```
+
+## 예시 실행
+
+```bash
+python example_usage.py
+```
+
+## 시간표 데이터 구조
+
+각 요일별 리스트는 교시(1~8) 순서이며, 각 항목은:
+
+```python
+{
+    "period": 1,        # 교시
+    "time": "08:40",    # 시간
+    "subject": "국어",  # 과목
+    "teacher": "김선생", # 교사
+    "room": "101",      # 강의실
+    "changed": False    # 변경 수업 여부
+}
+```

comci-0.1.0/README.md

@@ -0,0 +1,82 @@
+# Comci.net 시간표 API 클라이언트
+
+컴시간(comci.net) 비공식 API를 사용하여 학교 검색 및 시간표 조회를 할 수 있는 Python 모듈입니다.
+
+## 설치
+
+```bash
+pip install -r requirements.txt
+```
+
+## 사용법
+
+### 1. 학교 검색 (지역, 학교명, 학교코드)
+
+```python
+from comci import search_schools
+
+# "신송" 검색
+schools = search_schools("신송")
+for s in schools:
+    print(s["region"], s["school_name"], s["school_code"])
+# 인천 신송중학교 49654
+# 인천 신송고등학교 51825
+```
+
+### 2. 특정 학년/반 시간표 조회
+
+```python
+from comci import get_timetable
+
+# 1학년 1반 시간표 (정리.md 반환 구조)
+timetable = get_timetable(49654, grade=1, class_num=1)
+# {"월": [...], "화": [...], "수": [...], "목": [...], "금": [...]}
+```
+
+### 3. 전체 학년/반 시간표 조회
+
+```python
+# 학년, 반 미지정 시 전체
+timetable = get_timetable(49654)
+# {"1학년 1반": {...}, "1학년 2반": {...}, ...}
+```
+
+### 4. 검색 후 바로 시간표 조회
+
+```python
+from comci import search_and_get_timetable
+
+timetable = search_and_get_timetable("신송", school_index=0, grade=1, class_num=1)
+```
+
+## 프로젝트 구조
+
+```
+comci/
+├── __init__.py      # 패키지 진입점
+├── config.py        # API URL, 상수
+├── school_search.py # 학교 검색
+├── timetable.py     # 시간표 API 및 파싱
+└── client.py        # 통합 클라이언트
+```
+
+## 예시 실행
+
+```bash
+python example_usage.py
+```
+
+## 시간표 데이터 구조
+
+각 요일별 리스트는 교시(1~8) 순서이며, 각 항목은:
+
+```python
+{
+    "period": 1,        # 교시
+    "time": "08:40",    # 시간
+    "subject": "국어",  # 과목
+    "teacher": "김선생", # 교사
+    "room": "101",      # 강의실
+    "changed": False    # 변경 수업 여부
+}
+```

comci-0.1.0/comci/__init__.py

@@ -0,0 +1,16 @@
+"""
+Comci.net 시간표 API 클라이언트
+"""
+
+from .client import get_timetable, search_and_get_schools, search_and_get_timetable
+from .school_search import search_schools
+from .timetable import fetch_timetable_raw, parse_timetable
+
+__all__ = [
+    "search_schools",
+    "search_and_get_schools",
+    "fetch_timetable_raw",
+    "parse_timetable",
+    "get_timetable",
+    "search_and_get_timetable",
+]

comci-0.1.0/comci/client.py

@@ -0,0 +1,69 @@
+"""
+Comci.net API 통합 클라이언트
+"""
+
+from typing import Any, Dict, List, Optional
+
+from .school_search import search_schools
+from .timetable import fetch_timetable_raw, parse_timetable
+
+
+def search_and_get_schools(query: str) -> List[Dict[str, Any]]:
+    """
+    검색어로 학교 검색
+    
+    Returns:
+        [{"region": "인천", "school_name": "신송중학교", "school_code": 49654}, ...]
+    """
+    return search_schools(query)
+
+
+def get_timetable(
+    school_code: int,
+    grade: Optional[int] = None,
+    class_num: Optional[int] = None,
+    date_index: int = 1,
+) -> Dict[str, Any]:
+    """
+    학교 시간표 조회 (정리.md 기준)
+
+    Args:
+        school_code: 학교코드
+        grade: 학년 (1-based). None이면 전체
+        class_num: 반 (1-based). None이면 전체
+        date_index: 날짜 인덱스 (r)
+
+    Returns:
+        - grade, class_num 지정 시: {"월": [...], "화": [...], "수": [...], "목": [...], "금": [...]}
+        - 미지정 시: {"1학년 1반": {"월": [...], ...}, "1학년 2반": {...}, ...}
+    """
+    raw = fetch_timetable_raw(school_code, date_index)
+    parsed = parse_timetable(raw, grade=grade, class_num=class_num)
+    if grade is not None and class_num is not None and parsed:
+        return next(iter(parsed.values()))
+    return parsed
+
+
+def search_and_get_timetable(
+    query: str,
+    school_index: int = 0,
+    grade: Optional[int] = None,
+    class_num: Optional[int] = None,
+) -> Dict[str, Any]:
+    """
+    검색 → 학교 선택 → 시간표 조회를 한 번에 수행
+    
+    Args:
+        query: 검색어
+        school_index: 검색 결과 중 선택할 학교 인덱스 (0=첫 번째)
+        grade: 학년 (None=전체)
+        class_num: 반 (None=전체)
+    
+    Returns:
+        시간표 데이터
+    """
+    schools = search_schools(query)
+    if not schools:
+        return {}
+    school = schools[school_index]
+    return get_timetable(school["school_code"], grade=grade, class_num=class_num)

comci-0.1.0/comci/config.py

@@ -0,0 +1,34 @@
+"""
+Comci.net API 설정
+"""
+
+# API 기본 URL
+BASE_URL = "http://comci.net:4082/36179"
+
+# 학교 검색 API 파라미터 prefix
+SEARCH_PREFIX = "17384l"
+
+# 시간표 API 고정 키
+TIMETABLE_KEY = "73629"
+TIMETABLE_CACHE = "0"
+
+# 기본 날짜 인덱스 (r 파라미터)
+DEFAULT_DATE_INDEX = 1
+
+# 요청 헤더 (정리.md 기준)
+DEFAULT_HEADERS = {
+    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
+    "Accept": "application/json,text/plain,*/*",
+    "Accept-Language": "ko-KR,ko;q=0.9",
+    "Referer": "http://comci.net:4082/st",
+    "x-requested-with": "XMLHttpRequest",
+}
+
+# 인코딩
+SEARCH_ENCODING = "euc-kr"
+
+# 요일 매핑
+DAYS_OF_WEEK = ["월", "화", "수", "목", "금"]
+
+# 빈 수업 판단 기준
+EMPTY_CLASS_THRESHOLD = 100

comci-0.1.0/comci/school_search.py

@@ -0,0 +1,58 @@
+"""
+학교 검색 API 모듈
+"""
+
+import json
+import urllib.parse
+from typing import Any, Dict, List
+
+import requests
+
+from .config import BASE_URL, SEARCH_PREFIX, SEARCH_ENCODING, DEFAULT_HEADERS
+
+
+def encode_search_query(query: str) -> str:
+    """검색어를 EUC-KR 인코딩 후 퍼센트 인코딩"""
+    return urllib.parse.quote(query, encoding=SEARCH_ENCODING, safe="")
+
+
+def search_schools(query: str) -> List[Dict[str, Any]]:
+    """
+    학교 검색 API 호출
+    
+    Args:
+        query: 검색어 (예: "신송", "신")
+    
+    Returns:
+        검색 결과 리스트. 각 항목: {region, school_name, school_code}
+        알림 메시지(없으면 추가 검색하세요)는 제외됨
+    """
+    encoded = encode_search_query(query)
+    url = f"{BASE_URL}?{SEARCH_PREFIX}{encoded}"
+    
+    response = requests.get(url, headers=DEFAULT_HEADERS, timeout=10)
+    response.raise_for_status()
+    # API 응답 인코딩 (JSON은 UTF-8)
+    if response.encoding in (None, "ISO-8859-1", "ascii"):
+        response.encoding = "utf-8"
+    
+    # API가 여러 JSON 객체를 연속 반환할 수 있음 - 첫 번째만 파싱
+    data, _ = json.JSONDecoder().raw_decode(response.text)
+    raw_results = data.get("학교검색", [])
+    if not raw_results and data:
+        # 단일 키인 경우 해당 값 사용
+        vals = list(data.values())
+        if vals and isinstance(vals[0], list):
+            raw_results = vals[0]
+    
+    results = []
+    for item in raw_results:
+        # [0, "알림", "없으면 추가 검색하세요", 0] 형태의 알림 제외
+        if len(item) >= 4 and item[1] != "알림" and item[3] != 0:
+            results.append({
+                "region": item[1],
+                "school_name": item[2],
+                "school_code": item[3],
+            })
+    
+    return results

comci-0.1.0/comci/timetable.py

@@ -0,0 +1,251 @@
+"""
+시간표 API 및 파싱 모듈
+"""
+
+import base64
+import json
+from typing import Any, Dict, List, Optional
+
+import requests
+
+from .config import (
+    BASE_URL,
+    TIMETABLE_KEY,
+    TIMETABLE_CACHE,
+    DEFAULT_DATE_INDEX,
+    DEFAULT_HEADERS,
+    DAYS_OF_WEEK,
+    EMPTY_CLASS_THRESHOLD,
+)
+
+
+def build_timetable_param(school_code: int, date_index: int = DEFAULT_DATE_INDEX) -> str:
+    """시간표 API용 Base64 파라미터 생성"""
+    raw = f"{TIMETABLE_KEY}_{school_code}_{TIMETABLE_CACHE}_{date_index}"
+    return base64.b64encode(raw.encode("utf-8")).decode("utf-8")
+
+
+def fetch_timetable_raw(school_code: int, date_index: int = DEFAULT_DATE_INDEX) -> Dict[str, Any]:
+    """
+    학교 시간표 원본 JSON 조회
+    
+    Args:
+        school_code: 학교코드 (검색 API에서 획득)
+        date_index: 날짜 인덱스 (r 파라미터)
+    
+    Returns:
+        API 응답 JSON 전체
+    """
+    param = build_timetable_param(school_code, date_index)
+    url = f"{BASE_URL}?{param}"
+    
+    response = requests.get(url, headers=DEFAULT_HEADERS, timeout=10)
+    response.raise_for_status()
+    if response.encoding in (None, "ISO-8859-1", "ascii"):
+        response.encoding = "utf-8"
+
+    # API가 여러 JSON 객체를 연속 반환할 수 있음 - 자료481 포함된 객체 찾기
+    text = response.text.strip()
+    decoder = json.JSONDecoder()
+    idx = 0
+    while idx < len(text):
+        try:
+            data, end = decoder.raw_decode(text[idx:])
+            if isinstance(data, dict) and (
+                "자료481" in data or any("481" in str(k) for k in data.keys())
+            ):
+                return data
+            idx += end
+        except json.JSONDecodeError:
+            break
+    data, _ = json.JSONDecoder().raw_decode(text)
+    return data
+
+
+def _get_code(data: Any, grade: int, class_num: int, day: int, period: int) -> int:
+    """
+    자료481/자료147에서 코드 추출
+    실제 구조: [numGrades, grade0, grade1, ...], grade_i=[numClasses, class0, ...],
+    class_j=[5, day0, day1, ...], day_k=[numPeriods, code1, code2, ...]
+    """
+    if not data or not isinstance(data, list):
+        return 0
+    # grade: 0-based, 인덱스 0은 numGrades이므로 grade+1
+    if grade + 1 >= len(data):
+        return 0
+    grade_data = data[grade + 1]
+    if not isinstance(grade_data, list) or class_num + 1 >= len(grade_data):
+        return 0
+    class_data = grade_data[class_num + 1]
+    if not isinstance(class_data, list) or day >= len(class_data):
+        return 0
+    day_data = class_data[day]  # day 1-based (1=월) -> 인덱스 1
+    if not isinstance(day_data, list) or period >= len(day_data):
+        return 0
+    # day_data[0] = num periods, 실제 코드는 [1]부터 (period 1-based)
+    val = day_data[period] if period < len(day_data) else 0
+    return int(val) if val else 0
+
+
+def _get_room(data: Any, grade: int, class_num: int, day: int, period: int) -> str:
+    """자료245에서 강의실 문자열 추출 (자료481과 동일 구조)"""
+    if not data or not isinstance(data, list):
+        return ""
+    if grade + 1 >= len(data):
+        return ""
+    grade_data = data[grade + 1]
+    if not isinstance(grade_data, list) or class_num + 1 >= len(grade_data):
+        return ""
+    class_data = grade_data[class_num + 1]
+    if not isinstance(class_data, list) or day >= len(class_data):
+        return ""
+    day_data = class_data[day]  # day 1-based
+    if not isinstance(day_data, list) or period >= len(day_data):
+        return ""
+    val = day_data[period]  # period 1-based
+    return str(val) if val else ""
+
+
+def _parse_single_class(
+    data: Dict[str, Any],
+    grade: int,
+    class_num: int,
+) -> Dict[str, List[Dict[str, Any]]]:
+    """
+    특정 학년/반의 시간표 파싱
+    grade, class_num은 0-based 인덱스
+    """
+    split_val = data.get("분리", 100)
+    period_times = data.get("일과시간", [])
+    room_data = _get_data_key(data, "245")
+    base_data = _get_data_key(data, "481")
+    changed_data = _get_data_key(data, "147")
+    subject_data = _get_data_key(data, "492")
+    teacher_data = _get_data_key(data, "446")
+    
+    timetable_by_day: Dict[str, List[Dict[str, Any]]] = {
+        day: [] for day in DAYS_OF_WEEK
+    }
+    
+    for period in range(1, 9):  # 1~8교시
+        row = []
+        for day in range(1, 6):  # 1~5 (월~금)
+            base = _get_code(base_data, grade, class_num, day, period)
+            changed = _get_code(changed_data, grade, class_num, day, period)
+            code = changed if changed > 0 else base
+            
+            if not code or code <= EMPTY_CLASS_THRESHOLD:
+                row.append(None)
+                continue
+            
+            # 정리.md: 분리=100 → teacher=floor(code/분리), subject=code%분리
+            # 분리=1000 → 공식 반대 (mTh/mSb 로직)
+            if split_val == 100:
+                teacher_idx = code // split_val
+                subject_idx = code % split_val
+            else:
+                teacher_idx = code % split_val
+                subject_idx = code // split_val
+
+            subject = subject_data[subject_idx] if subject_idx < len(subject_data) else "미정"
+            teacher = teacher_data[teacher_idx] if teacher_idx < len(teacher_data) else "미정"
+            
+            room_raw = _get_room(room_data, grade, class_num, day, period)
+            parts = str(room_raw).split("_", 1)
+            room = parts[1] if len(parts) > 1 else (parts[0] if parts else "")
+            
+            time_str = period_times[period - 1] if period <= len(period_times) else ""
+            
+            row.append({
+                "period": period,
+                "time": time_str,
+                "day": day,
+                "subject": subject,
+                "teacher": teacher,
+                "room": room,
+                "changed": base != changed,
+            })
+        
+        for idx, day_name in enumerate(DAYS_OF_WEEK):
+            timetable_by_day[day_name].append(row[idx])
+    
+    return timetable_by_day
+
+
+def _get_nested(data: List, *indices: int):
+    """중첩 리스트/딕셔너리 안전 접근"""
+    obj = data
+    for idx in indices:
+        if obj is None or (isinstance(obj, list) and idx >= len(obj)):
+            return 0
+        if isinstance(obj, list):
+            obj = obj[idx]
+        elif isinstance(obj, dict):
+            obj = obj.get(idx, 0)
+    return obj if obj is not None else 0
+
+
+def _get_data_key(data: Dict, suffix: str):
+    """키 인코딩 이슈 대응 - suffix로 키 찾기"""
+    key = "자료" + suffix
+    if key in data:
+        return data[key]
+    for k in data.keys():
+        if suffix in str(k):
+            return data[k]
+    return []
+
+
+def parse_timetable(
+    data: Dict[str, Any],
+    grade: Optional[int] = None,
+    class_num: Optional[int] = None,
+) -> Dict[str, Any]:
+    """
+    시간표 JSON 파싱
+    
+    Args:
+        data: fetch_timetable_raw() 반환값
+        grade: 학년 (1-based, 1=1학년). None이면 전체
+        class_num: 반 (1-based, 1=1반). None이면 전체
+    
+    Returns:
+        - grade, class_num 둘 다 지정: 해당 학년/반만
+          {"1학년 1반": {"월": [...], "화": [...], ...}}
+        - 둘 다 None: 전체 학년/반
+          {"1학년 1반": {...}, "1학년 2반": {...}, ...}
+    """
+    base_data = _get_data_key(data, "481")
+    if not base_data or not isinstance(base_data, list):
+        return {}
+    
+    num_grades = base_data[0] if isinstance(base_data[0], (int, float)) else len(base_data) - 1
+    result = {}
+    
+    if grade is not None and class_num is not None:
+        g_idx = grade - 1
+        c_idx = class_num - 1
+        if g_idx < num_grades and g_idx + 1 < len(base_data):
+            grade_data = base_data[g_idx + 1]
+            num_classes = grade_data[0] if isinstance(grade_data, list) and grade_data else 0
+            if c_idx < num_classes:
+                key = f"{grade}학년 {class_num}반"
+                result[key] = _parse_single_class(data, g_idx, c_idx)
+        return result
+    
+    # 전체 학년/반
+    for g_idx in range(num_grades):
+        if g_idx + 1 >= len(base_data):
+            continue
+        grade_data = base_data[g_idx + 1]
+        if not isinstance(grade_data, list):
+            continue
+        num_classes = grade_data[0] if isinstance(grade_data[0], (int, float)) else len(grade_data) - 1
+        for c_idx in range(num_classes):
+            key = f"{g_idx + 1}학년 {c_idx + 1}반"
+            try:
+                result[key] = _parse_single_class(data, g_idx, c_idx)
+            except (IndexError, KeyError, TypeError):
+                continue
+    
+    return result

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

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: comci
+Version: 0.1.0
+Summary: Comci.net 시간표 API 비공식 클라이언트
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+
+# Comci.net 시간표 API 클라이언트
+
+컴시간(comci.net) 비공식 API를 사용하여 학교 검색 및 시간표 조회를 할 수 있는 Python 모듈입니다.
+
+## 설치
+
+```bash
+pip install -r requirements.txt
+```
+
+## 사용법
+
+### 1. 학교 검색 (지역, 학교명, 학교코드)
+
+```python
+from comci import search_schools
+
+# "신송" 검색
+schools = search_schools("신송")
+for s in schools:
+    print(s["region"], s["school_name"], s["school_code"])
+# 인천 신송중학교 49654
+# 인천 신송고등학교 51825
+```
+
+### 2. 특정 학년/반 시간표 조회
+
+```python
+from comci import get_timetable
+
+# 1학년 1반 시간표 (정리.md 반환 구조)
+timetable = get_timetable(49654, grade=1, class_num=1)
+# {"월": [...], "화": [...], "수": [...], "목": [...], "금": [...]}
+```
+
+### 3. 전체 학년/반 시간표 조회
+
+```python
+# 학년, 반 미지정 시 전체
+timetable = get_timetable(49654)
+# {"1학년 1반": {...}, "1학년 2반": {...}, ...}
+```
+
+### 4. 검색 후 바로 시간표 조회
+
+```python
+from comci import search_and_get_timetable
+
+timetable = search_and_get_timetable("신송", school_index=0, grade=1, class_num=1)
+```
+
+## 프로젝트 구조
+
+```
+comci/
+├── __init__.py      # 패키지 진입점
+├── config.py        # API URL, 상수
+├── school_search.py # 학교 검색
+├── timetable.py     # 시간표 API 및 파싱
+└── client.py        # 통합 클라이언트
+```
+
+## 예시 실행
+
+```bash
+python example_usage.py
+```
+
+## 시간표 데이터 구조
+
+각 요일별 리스트는 교시(1~8) 순서이며, 각 항목은:
+
+```python
+{
+    "period": 1,        # 교시
+    "time": "08:40",    # 시간
+    "subject": "국어",  # 과목
+    "teacher": "김선생", # 교사
+    "room": "101",      # 강의실
+    "changed": False    # 변경 수업 여부
+}
+```

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

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+comci/__init__.py
+comci/client.py
+comci/config.py
+comci/school_search.py
+comci/timetable.py
+comci.egg-info/PKG-INFO
+comci.egg-info/SOURCES.txt
+comci.egg-info/dependency_links.txt
+comci.egg-info/requires.txt
+comci.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+requests>=2.28.0

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

@@ -0,0 +1 @@
+comci

comci-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "comci"
+version = "0.1.0"
+description = "Comci.net 시간표 API 비공식 클라이언트"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["requests>=2.28.0"]
+
+[tool.setuptools]
+packages = ["comci"]
+

comci-0.1.0/setup.cfg

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