hapilibur 0.2.0__py3-none-any.whl

hapilibur/__init__.py

@@ -0,0 +1,25 @@
+"""hapilibur — dataset & bantu hitung hari libur nasional dan cuti bersama Indonesia.
+
+Sumber: SKB 3 Menteri (Hari Libur Nasional & Cuti Bersama) dan Imsakiyah Bimas Islam Kemenag.
+"""
+
+from .core import (  # noqa: F401
+    CUTI_FILE,
+    LIBUR_FILE,
+    available_cities,
+    between,
+    check,
+    check_detail,
+    cuti,
+    holiday_range,
+    imsak,
+    imsak_cities_available,
+    is_holiday,
+    is_libur,
+    libur,
+    month,
+    to_csv,
+    upcoming,
+)
+
+__version__ = "0.2.0"

hapilibur/__main__.py

@@ -0,0 +1,151 @@
+"""CLI hapilibur: cek hari libur, cuti bersama, dan jadwal imsakiyah dari terminal."""
+from __future__ import annotations
+
+import argparse
+import datetime
+import json
+import sys
+
+from . import __version__, core
+
+
+def _emit(entries: list[dict] | dict, as_json: bool, as_csv: bool) -> None:
+    if as_json:
+        print(json.dumps(entries, ensure_ascii=False, indent=2))
+        return
+    if as_csv:
+        items = entries if isinstance(entries, list) else [entries]
+        print(core.to_csv([e for e in items if e.get("date")]), end="")
+        return
+    if isinstance(entries, dict):
+        print(f"{entries.get('date')}  {entries.get('name')}")
+        return
+    for entry in entries:
+        print(f"{entry['date']}  {entry['name']}")
+
+
+def _fmt_date(value: str, as_json: bool) -> None:
+    detail = core.check_detail(value)
+    if as_json:
+        print(json.dumps(detail or {"date": value, "is_holiday": False}, ensure_ascii=False, indent=2))
+        return
+    print(f"{value}: {detail['name'] if detail else 'Bukan hari libur nasional / cuti bersama'}")
+
+
+def _print_holidays(entries: list[dict], year: int | None, as_json: bool, as_csv: bool) -> None:
+    if not entries:
+        label = f"tahun {year}" if year else "rentang tersebut"
+        if as_json:
+            print("[]")
+        elif not as_csv:
+            print(f"Tidak ada data untuk {label}.")
+        else:
+            print("tanggal,nama")
+        return
+    _emit(entries, as_json, as_csv)
+
+
+def _print_imsak(payload: dict, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return
+    print(f"{payload['title']} ({payload['timezone']})")
+    print(f"{'Hari':<5}{'Tanggal':<12}{'Imsak':<7}{'Subuh':<7}{'Zuhur':<7}{'Ashar':<7}{'Magrib':<7}{'Isya':<7}")
+    for item in payload["schedule"]:
+        print(
+            f"{item['day']:<5}{item['date']:<12}{item['imsak']:<7}{item['subuh']:<7}"
+            f"{item['zuhur']:<7}{item['ashar']:<7}{item['magrib']:<7}{item['isya']:<7}"
+        )
+
+
+def _add_output_flags(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="keluarkan sebagai JSON")
+    parser.add_argument("--csv", action="store_true", help="keluarkan sebagai CSV")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="hapilibur",
+        description="Cek hari libur nasional, cuti bersama, dan jadwal imsakiyah Indonesia.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="cek apakah suatu tanggal hari libur")
+    p_check.add_argument("tanggal", help="tanggal dalam format YYYY-MM-DD, misal 2026-08-17")
+    p_check.add_argument("--json", action="store_true", help="keluarkan sebagai JSON")
+
+    p_tahun = sub.add_parser("tahun", help="daftar hari libur nasional satu tahun")
+    p_tahun.add_argument("tahun", nargs="?", type=int, help="tahun (default: tahun berjalan)")
+    _add_output_flags(p_tahun)
+
+    p_cuti = sub.add_parser("cuti", help="daftar cuti bersama satu tahun")
+    p_cuti.add_argument("tahun", nargs="?", type=int, help="tahun (default: tahun berjalan)")
+    _add_output_flags(p_cuti)
+
+    p_bulan = sub.add_parser("bulan", help="daftar tanggal libur satu bulan")
+    p_bulan.add_argument("tahun", type=int, help="tahun, misal 2026")
+    p_bulan.add_argument("bulan", type=int, help="bulan 1-12, misal 3")
+    p_bulan.add_argument("--tanpa-cuti", action="store_true", help="kecualikan cuti bersama")
+    _add_output_flags(p_bulan)
+
+    p_selang = sub.add_parser("selang", help="daftar tanggal libur dalam rentang tanggal", aliases=["range"])
+    p_selang.add_argument("dari", help="tanggal awal YYYY-MM-DD")
+    p_selang.add_argument("sampai", help="tanggal akhir YYYY-MM-DD")
+    _add_output_flags(p_selang)
+
+    p_next = sub.add_parser("upcoming", help="hari libur berikutnya", aliases=["next"])
+    p_next.add_argument("tanggal", nargs="?", help="awal pencarian (default: hari ini)")
+    p_next.add_argument("-n", "--count", type=int, default=1, help="jumlah hari libur (default: 1)")
+    p_next.add_argument("--json", action="store_true", help="keluarkan sebagai JSON")
+
+    p_imsak = sub.add_parser("imsak", help="jadwal imsakiyah sebuah kota")
+    p_imsak.add_argument("kota", help="nama kota, misal jakarta atau surabaya")
+    p_imsak.add_argument("tahun", nargs="?", type=int, help="tahun (default: tahun berjalan)")
+    p_imsak.add_argument("--json", action="store_true", help="keluarkan sebagai JSON")
+
+    sub.add_parser("kota", help="daftar kota yang tersedia")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+
+    try:
+        if args.command == "check":
+            _fmt_date(args.tanggal, as_json=args.json)
+        elif args.command == "tahun":
+            year = args.tahun or datetime.date.today().year
+            _print_holidays(core.libur(year), year, args.json, args.csv)
+        elif args.command == "cuti":
+            year = args.tahun or datetime.date.today().year
+            _print_holidays(core.cuti(year), year, args.json, args.csv)
+        elif args.command == "bulan":
+            entries = core.month(args.tahun, args.bulan, include_cuti=not args.tanpa_cuti)
+            _print_holidays(entries, args.tahun, args.json, args.csv)
+        elif args.command in ("selang", "range"):
+            _print_holidays(core.between(args.dari, args.sampai), None, args.json, args.csv)
+        elif args.command in ("upcoming", "next"):
+            result = core.upcoming(args.tanggal, n=args.count)
+            if args.json:
+                print(json.dumps(result, ensure_ascii=False, indent=2))
+            elif args.count == 1:
+                assert isinstance(result, dict)
+                print(f"{result['date']}  {result['name']}")
+            else:
+                assert isinstance(result, list)
+                for item in result:
+                    print(f"{item['date']}  {item['name']}")
+        elif args.command == "imsak":
+            _print_imsak(core.imsak(args.kota, args.tahun), as_json=args.json)
+        elif args.command == "kota":
+            print(", ".join(core.available_cities()))
+    except ValueError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hapilibur/core.py

@@ -0,0 +1,279 @@
+"""Fungsi inti hapilibur: cek hari libur nasional, cuti bersama, dan imsakiyah.
+
+Semua data diambil dari file JSON yang dibundel dalam package
+(lihat folder ``hapilibur/data``) — data bisa dipakai lintas bahasa.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import functools
+import json
+from importlib.resources import files
+
+LIBUR_FILE = "libur-nasional.json"
+CUTI_FILE = "cuti-bersama.json"
+
+__all__ = [
+    "LIBUR_FILE",
+    "CUTI_FILE",
+    "available_cities",
+    "between",
+    "check",
+    "check_detail",
+    "cuti",
+    "holiday_range",
+    "imsak",
+    "imsak_cities_available",
+    "is_holiday",
+    "is_libur",
+    "libur",
+    "month",
+    "to_csv",
+    "upcoming",
+]
+
+_DATE_FMT = "%Y-%m-%d"
+
+
+@functools.lru_cache(maxsize=64)
+def _load(name: str) -> dict:
+    try:
+        data = files("hapilibur").joinpath("data").joinpath(name).read_text(encoding="utf-8")
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(f"File data '{name}' tidak ditemukan di package hapilibur.") from exc
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"File data '{name}' rusak (JSON tidak valid): {exc}") from exc
+
+
+def _parse_date(value: str | _dt.date | _dt.datetime) -> _dt.date:
+    if isinstance(value, _dt.datetime):
+        return value.date()
+    if isinstance(value, _dt.date):
+        return value
+    if not isinstance(value, str):
+        raise TypeError(f"Tanggal harus str/YYYY-MM-DD, date, atau datetime — dapat {type(value).__name__}")
+    text = value.strip()
+    try:
+        return _dt.datetime.strptime(text, _DATE_FMT).date()
+    except ValueError as exc:
+        raise ValueError(f"Tanggal '{value}' tidak valid — gunakan format YYYY-MM-DD (contoh: 2026-08-17).") from exc
+
+
+def _year_entries(name: str, year: int) -> list[dict]:
+    """Ambil daftar {date, name} untuk satu tahun dari file JSON dataset."""
+    if not isinstance(year, int) or year < 1 or year > 9999:
+        raise ValueError(f"Tahun '{year}' tidak valid — harus bilangan 1-9999.")
+    payload = _load(name)
+    return list(payload.get("years", {}).get(str(year), {}).get("holidays", []))
+
+
+def _dates(name: str, year: int) -> dict[_dt.date, str]:
+    return {_parse_date(entry["date"]): entry["name"] for entry in _year_entries(name, year)}
+
+
+def _all_dates(year: int | None = None, include_cuti: bool = True) -> dict[_dt.date, str]:
+    """Gabungan hari libur nasional + (opsional) cuti bersama."""
+    year = year or _dt.date.today().year
+    merged: dict[_dt.date, str] = {}
+    merged.update(_dates(LIBUR_FILE, year))
+    if include_cuti:
+        for d, name in _dates(CUTI_FILE, year).items():
+            if d in merged:
+                merged[d] = f"{merged[d]} • {name}"
+            else:
+                merged[d] = name
+    return merged
+
+
+def _kinds(year: int) -> dict[_dt.date, set[str]]:
+    """Petakan tanggal -> {'libur_nasional', 'cuti_bersama'}."""
+    kinds: dict[_dt.date, set[str]] = {}
+    for entry in _year_entries(LIBUR_FILE, year):
+        kinds.setdefault(_parse_date(entry["date"]), set()).add("libur_nasional")
+    for entry in _year_entries(CUTI_FILE, year):
+        kinds.setdefault(_parse_date(entry["date"]), set()).add("cuti_bersama")
+    return kinds
+
+
+def libur(year: int | None = None) -> list[dict]:
+    """Daftar hari libur nasional (lengkap dengan tanggal) dalam satu tahun.
+
+    >>> libur(2026)[0]  # doctest: +SKIP
+    {'date': '2026-01-01', 'name': 'Tahun Baru 2026 Masehi'}
+    """
+    year = year or _dt.date.today().year
+    return list(_year_entries(LIBUR_FILE, year))
+
+
+def cuti(year: int | None = None) -> list[dict]:
+    """Daftar cuti bersama nasional dalam satu tahun."""
+    year = year or _dt.date.today().year
+    return list(_year_entries(CUTI_FILE, year))
+
+
+def month(year: int, month_number: int, include_cuti: bool = True) -> list[dict]:
+    """Daftar tanggal libur (nasional + cuti bersama) dalam satu bulan sebuah tahun.
+
+    ``month_number`` 1-12 (Januari-Desember).
+
+    >>> month(2026, 3)[:1]  # doctest: +SKIP
+    [{'date': '2026-03-18', 'name': 'Cuti Bersama Hari Suci Nyepi'}]
+    """
+    if not 1 <= month_number <= 12:
+        raise ValueError("month_number harus 1-12")
+    return [
+        {"date": date.isoformat(), "name": name}
+        for date, name in sorted(_all_dates(year, include_cuti=include_cuti).items())
+        if date.year == year and date.month == month_number
+    ]
+
+
+def between(
+    start: str | _dt.date | _dt.datetime,
+    end: str | _dt.date | _dt.datetime,
+    include_cuti: bool = True,
+) -> list[dict]:
+    """Daftar tanggal libur (nasional + cuti bersama) dalam rentang tanggal inklusif.
+
+    >>> len(between("2026-08-01", "2026-08-31"))  # doctest: +SKIP
+    1
+    """
+    start_date = _parse_date(start)
+    end_date = _parse_date(end)
+    if end_date < start_date:
+        start_date, end_date = end_date, start_date
+    result: list[dict] = []
+    for year in range(start_date.year, end_date.year + 1):
+        for date, name in sorted(_all_dates(year, include_cuti=include_cuti).items()):
+            if start_date <= date <= end_date:
+                result.append({"date": date.isoformat(), "name": name})
+    return result
+
+
+def holiday_range(
+    start: str | _dt.date | _dt.datetime, end: str | _dt.date | _dt.datetime
+) -> list[dict]:
+    """Alias bahasa Inggris dari :func:`between`."""
+    return between(start, end)
+
+
+def is_libur(value: str | _dt.date | _dt.datetime, include_cuti: bool = True) -> bool:
+    """True bila ``value`` adalah hari libur (nasional + opsional cuti bersama).
+
+    .. versionchanged:: 0.2.0
+        Parameter ``include_cuti`` kini benar-benar dihormati
+        (sebelumnya selalu True).
+    """
+    tanggal = _parse_date(value)
+    if include_cuti:
+        return tanggal in _all_dates(tanggal.year, include_cuti=True)
+    return tanggal in _dates(LIBUR_FILE, tanggal.year)
+
+
+def is_holiday(value: str | _dt.date | _dt.datetime) -> bool:
+    """Alias bahasa Inggris dari :func:`is_libur` (termasuk cuti bersama)."""
+    return is_libur(value, include_cuti=True)
+
+
+def check(value: str | _dt.date | _dt.datetime) -> str | None:
+    """Nama hari libur untuk tanggal tertentu, atau ``None`` bila bukan."""
+    tanggal = _parse_date(value)
+    return _all_dates(tanggal.year).get(tanggal)
+
+
+def check_detail(value: str | _dt.date | _dt.datetime) -> dict | None:
+    """Detail hari libur: ``{date, name, jenis[]}`` atau ``None``.
+
+    ``jenis`` berisi kombinasi ``libur_nasional`` / ``cuti_bersama``.
+    Baru di 0.2.0.
+    """
+    tanggal = _parse_date(value)
+    name = _all_dates(tanggal.year).get(tanggal)
+    if name is None:
+        return None
+    kinds = sorted(_kinds(tanggal.year).get(tanggal, set()))
+    return {"date": tanggal.isoformat(), "name": name, "jenis": kinds}
+
+
+def upcoming(value: str | _dt.date | _dt.datetime | None = None, n: int = 1) -> dict | list[dict]:
+    """Satu atau beberapa hari libur berikutnya (>= tanggal yang diberikan).
+
+    ``n=1`` mengembalikan dict; ``n>1`` mengembalikan list dict ber-urutan tanggal.
+    Bila tidak ada data, ``n=1`` mengembalikan ``{"date": None, "name": None}``
+    dan ``n>1`` mengembalikan list kosong.
+    """
+    if n < 1:
+        raise ValueError("n harus >= 1")
+    start = _parse_date(value) if value else _dt.date.today()
+    found: list[dict] = []
+    for year in range(start.year, start.year + 5):
+        if len(found) >= n:
+            break
+        for date, name in sorted(_all_dates(year).items()):
+            if date < start:
+                continue
+            found.append({"date": date.isoformat(), "name": name})
+            if len(found) >= n:
+                break
+    if n == 1:
+        return found[0] if found else {"date": None, "name": None}
+    return found
+
+
+def to_csv(entries: list[dict], jenis_default: str = "libur") -> str:
+    """Ubah daftar ``{date, name}`` menjadi string CSV ``tanggal,nama``.
+
+    Baru di 0.2.0 — untuk CLI ``--csv`` dan analisis cepat.
+    """
+    lines = ["tanggal,nama"]
+    for entry in entries:
+        name = str(entry.get("name", "")).replace('"', '""')
+        lines.append(f"{entry.get('date', '')},\"{name}\"")
+    return "\n".join(lines) + ("\n" if entries else "")
+
+
+def imsak(city: str, year: int | None = None) -> dict:
+    """Jadwal imsakiyah (imsak, subuh, zuhur, ashar, magrib, isya) untuk sebuah kota.
+
+    ``city`` tidak case-sensitive dan boleh tanpa spasi, contoh: ``"jakarta"``, ``"Surabaya"``.
+    """
+    year = year or _dt.date.today().year
+    if not isinstance(year, int) or year < 1 or year > 9999:
+        raise ValueError(f"Tahun '{year}' tidak valid — harus bilangan 1-9999.")
+    slug = "".join(ch for ch in city.strip().lower() if ch.isalnum())
+    if not slug:
+        raise ValueError("Nama kota tidak boleh kosong.")
+    try:
+        return _load(f"{slug}-{year}.json")
+    except FileNotFoundError as exc:
+        raise ValueError(
+            f"Belum ada jadwal imsakiyah untuk kota {city!r} tahun {year}. "
+            f"Kota tersedia: {', '.join(available_cities())}."
+        ) from exc
+
+
+def available_cities() -> list[str]:
+    """Daftar kota yang tersedia pada data imsakiyah."""
+    excluded = {LIBUR_FILE[:-5], CUTI_FILE[:-5]}
+    cities = set()
+    try:
+        members = list(files("hapilibur").joinpath("data").iterdir())
+    except FileNotFoundError:
+        return []
+    for member in members:
+        if member.suffix != ".json":
+            continue
+        stem = member.stem
+        if stem in excluded:
+            continue
+        city, sep, year = stem.rpartition("-")
+        if sep and city and year.isdigit():
+            cities.add(city.title())
+    return sorted(cities)
+
+
+def imsak_cities_available() -> list[str]:
+    """Alias dari :func:`available_cities`."""
+    return available_cities()

hapilibur/data/cuti-bersama.json

@@ -0,0 +1,29 @@
+{
+  "schema_version": "1.0",
+  "title": "Cuti Bersama Indonesia",
+  "country": "Indonesia",
+  "country_code": "ID",
+  "updated_at": "2026-09-12T00:00:00Z",
+  "sources": [
+    {
+      "name": "SKB 3 Menteri (Menag, Menaker, MenPAN-RB) Nomor 1497, 2, 5 Tahun 2025",
+      "title": "Hari Libur Nasional dan Cuti Bersama Tahun 2026",
+      "url": "https://www.kemenkopmk.go.id/sites/default/files/pengumuman/2025-09/SKB%20Libur%20Nasional%20dan%20Cuti%20Bersama%20Tahun%202026.pdf"
+    }
+  ],
+  "years": {
+    "2026": {
+      "count": 8,
+      "holidays": [
+        { "date": "2026-02-16", "name": "Cuti Bersama Tahun Baru Imlek 2577 Kongzili" },
+        { "date": "2026-03-18", "name": "Cuti Bersama Hari Suci Nyepi" },
+        { "date": "2026-03-20", "name": "Cuti Bersama Hari Raya Idul Fitri 1447 H" },
+        { "date": "2026-03-23", "name": "Cuti Bersama Hari Raya Idul Fitri 1447 H" },
+        { "date": "2026-03-24", "name": "Cuti Bersama Hari Raya Idul Fitri 1447 H" },
+        { "date": "2026-05-15", "name": "Cuti Bersama Kenaikan Yesus Kristus" },
+        { "date": "2026-05-28", "name": "Cuti Bersama Hari Raya Idul Adha 1447 H" },
+        { "date": "2026-12-24", "name": "Cuti Bersama Kelahiran Yesus Kristus" }
+      ]
+    }
+  }
+}