한국 공휴일 패키지 (kr_holidays)
캘린더 등에 활용하기 편한 평일, 주말, 공휴일, 대체공휴일 정보를 제공하는 Python 패키지입니다.
✨ 주요 기능
- 🗓️ 한국 공휴일 정보: 법정공휴일, 대체공휴일 완벽 지원
- 📅 다양한 날짜 형식: 문자열, date 객체 모두 지원
- ⚡ 빠른 조회: 메모리 캐싱으로 최적화된 성능
- 🔧 편리한 API: 간단한 함수부터 고급 클래스까지
- 📊 업무일 계산: 근무일 수 계산, 영업일 더하기 등
🔧 설치
최신 버전 설치
# pip 사용
pip install kr_holidays
# uv 사용 (권장)
uv add kr_holidays
특정 버전 설치
# pip 사용
pip install kr_holidays==1.0.0
# uv 사용
uv add kr_holidays==1.0.0
🚀 빠른 시작
기본 사용법
from kr_holidays import is_holiday, get_holidays, is_working_day
# 공휴일 확인
print(is_holiday('2024-01-01')) # True (신정)
print(is_holiday('2024-05-06')) # True (어린이날 대체공휴일)
print(is_holiday('2024-01-02')) # False
# 주말/근무일 확인
print(is_working_day('2024-01-02')) # True (화요일, 공휴일 아님)
# 연도별 공휴일 조회
holidays_2024 = get_holidays(2024)
print(f"2024년 공휴일: {len(holidays_2024)}개")
고급 사용법
from kr_holidays import KoreanHolidays
kh = KoreanHolidays()
# 다음 공휴일 찾기
next_holiday = kh.get_next_holiday('2024-01-02')
print(f"다음 공휴일: {next_holiday}")
# 근무일 계산
working_days = kh.count_working_days('2024-01-01', '2024-01-31')
print(f"1월 근무일: {working_days}일")
# 근무일 더하기 (공휴일/주말 제외)
target_date = kh.add_working_days('2024-01-01', 10) # 1/1부터 10 근무일 후
print(f"신정부터 10 근무일 후: {target_date}")
# 공휴일 이름 조회
holiday_name = kh.get_holiday_name('2024-05-06')
print(f"5월 6일: {holiday_name}") # 어린이날 대체공휴일
월별 조회
# 특정 월의 공휴일만
may_holidays = kh.get_holidays_in_month(2024, 5)
print("5월 공휴일:", may_holidays)
# 특정 월의 근무일만
may_workdays = kh.get_working_days_in_month(2024, 5)
print(f"5월 근무일: {len(may_workdays)}일")
📋 지원 데이터
포함된 공휴일
- 법정공휴일: 신정, 삼일절, 어린이날, 현충일, 광복절, 개천절, 한글날, 성탄절
- 음력 공휴일: 설날 연휴 (3일), 부처님오신날, 추석 연휴 (3일)
- 대체공휴일: 공휴일이 주말과 겹칠 때 평일로 대체
- 임시공휴일: 정부에서 지정하는 특별 공휴일
지원 연도
- 2000년 ~ 2050년 (확장 가능)
- 공공데이터포털 API 기준 정확한 데이터
🛠️ 시스템 요구사항
- Python: 3.8, 3.9, 3.10, 3.11, 3.12
- 의존성: 없음 (외부 라이브러리 불필요)
- 운영체제: Windows, macOS, Linux 모두 지원
📚 API 문서
편의 함수 (권장)
# 날짜 확인
is_holiday(date) # 공휴일 여부
is_weekend(date) # 주말 여부
is_working_day(date) # 근무일 여부
# 데이터 조회
get_holidays(year) # 연도별 공휴일 목록
get_holiday_name(date) # 공휴일 이름
get_next_holiday(date) # 다음 공휴일
# 근무일 계산
count_working_days(start, end) # 기간 내 근무일 수
add_working_days(start, days) # 근무일 더하기
KoreanHolidays 클래스
kh = KoreanHolidays()
# 모든 편의 함수 + 추가 기능
kh.get_holidays_in_month(year, month) # 월별 공휴일
kh.get_working_days_in_month(year, month) # 월별 근무일
kh.get_year_summary(year) # 연도 요약 정보
🔄 버전 호환성
| 버전 | Python 지원 | 주요 변경사항 |
|---|---|---|
| 1.0.0 | 3.8 ~ 3.12 | 초기 릴리스 |
📝 변경 로그
v1.0.0 (2024-09-01)
- 🎉 초기 릴리스
- ✅ 기본 공휴일 조회 기능
- ✅ 대체공휴일 지원
- ✅ 근무일 계산 기능
⚠️ 알려진 이슈
- Python 3.7 이하 버전은 지원하지 않습니다 (EOL)
- 2000년 이전 연도 데이터 | 2050년 이후 연도 데이터는 현재 미지원 (추후 확장 예정입니다!)
🤝 기여하기
버그 리포트나 기능 제안은 언제나 환영합니다!
- 이슈 제출: GitHub Issues
- 기능 제안: GitHub Discussions
📄 라이센스
MIT License - 자유롭게 사용하세요!
🙏 감사 인사
이 패키지는 공공데이터포털의 공휴일 정보를 활용하여 개발되었습니다.
Metadata
Release files for kr_holidays 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kr_holidays-1.0.0.tar.gz | 179.6 kB | Without provenance | Details for kr_holidays-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kr_holidays-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for kr_holidays-1.0.0-py3-none-any.whl |
Total release size: 385.7 kB
Release files / kr_holidays-1.0.0.tar.gz
| Download URL | kr_holidays-1.0.0.tar.gz |
|---|---|
| Size | 179.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
296a56cc75cc0637cf8a7772b2b5c5630e7a52de945254aa83c71b2c41263315
|
|
BLAKE2b-256 checksum How to use checksums |
36045594325cacbe567f5e6d59eb42770709b8abd62bbf4e394aa8c38de4aa50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.17
|
Release files / kr_holidays-1.0.0-py3-none-any.whl
| Download URL | kr_holidays-1.0.0-py3-none-any.whl |
|---|---|
| Size | 206.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ef16eadcc46f7759f9c5571c660c61e85aad91bb4ef284b61aad45efff449d19
|
|
BLAKE2b-256 checksum How to use checksums |
0b9e3c496ca1af26ce407efca0abd9fa00b10490af4b2e3e51116494ac51eb2e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.17
|
Security for kr_holidays 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.