korean-holidays 0.1.0

Korean public holidays calculator — lunar calendar auto-conversion, substitute holidays

korean-holidays

Korean public holidays calculator with automatic lunar calendar conversion

한국 공휴일 자동 계산 라이브러리. 음력 명절(설날/추석/부처님오신날) 자동 변환 + 대체휴일 규칙 적용. 하드코딩 없이 아무 연도든 계산 가능합니다.

Features

• 자동 음력 변환 — 설날, 추석, 부처님오신날을 매년 자동 계산
• 대체휴일 자동 적용 — 2021년 확대 시행 규칙 반영
• 아무 연도든 계산 — 하드코딩 없이 get_holidays(2030) 가능
• 거래일 계산 — is_trading_day(), count_trading_days()
• 캐시 내장 — 같은 연도 반복 호출 시 재계산 없음
• Zero config — API 키 불필요, 네트워크 불필요

Installation

pip install korean-holidays

Quick Start

from datetime import date
from korean_holidays import get_holidays, is_holiday, is_trading_day, count_trading_days

# 2026년 공휴일 전체
holidays = get_holidays(2026)
for d, name in sorted(holidays.items()):
    print(f"{d} {name}")

# 특정 날짜 확인
print(is_holiday(date(2026, 2, 17)))      # True (설날)
print(is_holiday(date(2026, 5, 25)))      # True (부처님오신날 대체휴일)
print(is_trading_day(date(2026, 4, 6)))   # True (월요일 평일)

# 연간 거래일 수
days = count_trading_days(date(2026, 1, 1), date(2026, 12, 31))
print(f"2026년 거래일: {days}일")

# 2030년도 가능 (하드코딩 아님)
holidays_2030 = get_holidays(2030)

API Reference

Function	Description
get_holidays(year)	해당 연도 공휴일 {date: name} 반환
is_holiday(date)	공휴일 여부
get_holiday_name(date)	공휴일명 (아니면 None)
is_trading_day(date)	주식시장 거래일 여부 (주말+공휴일 제외)
get_trading_days(start, end)	거래일 리스트
count_trading_days(start, end)	거래일 수

Supported Holidays

고정 공휴일: 신정, 삼일절, 근로자의날, 어린이날, 현충일, 광복절, 개천절, 한글날, 크리스마스

음력 공휴일 (자동 계산): 설날 연휴(3일), 추석 연휴(3일), 부처님오신날

대체휴일 (자동 적용):

• 설날/추석: 일요일 겹침 시 연휴 다음 첫 평일
• 어린이날: 토/일 겹침 시 (2014년~)
• 삼일절/광복절/개천절/한글날: 토/일 겹침 시 (2021년~)
• 부처님오신날: 토/일 겹침 시 (2023년~)

Disclaimer

공휴일 계산은 현행 법령 기반이며, 법 개정 시 업데이트가 필요할 수 있습니다. 임시 공휴일(선거일 등)은 포함되지 않습니다.

License

MIT License. See LICENSE.