nepali-toolkits 1.0.0

Production-ready utilities for Nepali: BS calendar & holidays, script tools, gazetteer, units, treks.

Nepali Toolkit

Production-ready utilities for working with Nepali language and data:

Features

Bikram Sambat (BS) Calendar

• AD ↔ BS conversion with strict validation
• Flexible formatting tokens (YYYY, MMM, DD, etc.)
• English/Nepali month names, optional Nepali digits (०१२…)
• Timezone-aware today_bs() and now() (default Asia/Kathmandu)

BS Holidays

• List holidays by year/month/tags (e.g., public, festival, school)
• Free-text search (name_en / name_ne / BS / AD)
• next_holiday() and list_holiday_between() helpers
• Data-driven JSON sets; supports merging multiple years

Script Utilities

• Roman ↔ Devanagari transliteration (digits + diacritics)
• Data-backed alphabets (vowels/consonants) with examples
• Barakhari generation (क, का, कि, …) for any base consonant
• Clean import surface: roman_to_dev, dev_to_roman, vowel_alphabet, consonant_alphabet

Gazetteer

• Provinces, zones, districts, and a unified places file (with famous flag & tags)
• Filter by province/zone/district/tags; ranked text search; nearby (Haversine)
• Single query_places() API plus ergonomic wrappers (list_places, nearby_places, list_famous_places)

Units

• Area / Volume / Mass conversions via a single convert(value, from, to) API
• Friendly aliases (e.g., "sq m", "m²", "liter", "L", "kg")
• Category safety (prevents cross-category mistakes)

Treks

• Curated trekking routes with region/province/district metadata
• Filter by difficulty, days, altitude, tags, permits, seasons
• Text search, nearby-by-start, and lightweight suggestions

Design Principles

• Pure Python, JSON datasets, predictable APIs
• i18n-first (EN/NE), developer ergonomics, strong validation
• Modular structure with clean __init__ exports for friendly imports

Requires Python ≥ 3.9

---

Installation

pip install nepali-toolkit

Quick Start

# quick_start.py
from nepali_toolkit.holiday import list_holiday, next_holiday, list_holiday_between
from nepali_toolkit.script.transliterate import roman_to_dev, dev_to_roman
from nepali_toolkit.script.alphabet import vowel_alphabet, consonant_alphabet
from nepali_toolkit.script.barakhari import Barakhari
from nepali_toolkit.gazetteer import (
    list_provinces, get_zone, list_districts, list_places, nearby_places, search, suggest
)
from nepali_toolkit.unit import convert
from nepali_toolkit.trek import list_treks, search_treks, nearby_treks
from nepali_toolkit.bs import to_bs, to_ad, today_bs, now
from nepali_toolkit.scripts.barakhari import table

print("=== BS Calendar ===")

print("\n=== AD → BS ===")
bs_obj = to_bs("1999-10-01")
print("Raw BS (ISO):", str(bs_obj))
print("EN label:    ", to_bs("1999-10-01", fmt="YYYY MMM D", lang="en"))
print("NE label:    ", to_bs("1999-10-01", fmt="YYYY MMMM DD", lang="ne", ne_digits=True))




print("\n=== BS → AD ===")
ad_obj = to_ad("2056-06-14")
print("Raw AD (ISO):", ad_obj.isoformat())
print("EN label:    ", to_ad("2056-06-14", fmt="YYYY MMM D", lang="en"))
print("NE label:    ", to_ad("2056-06-14", fmt="YYYY MMMM DD", lang="ne", ne_digits=True))


print("\n=== TODAY (BS) ===")
bs_obj = today_bs()
print("Raw BS (ISO)      :", str(bs_obj))
print("EN (space style)  :", today_bs(fmt="YYYY MMM D", lang="en"))
print("NE (full+digits)  :", today_bs(fmt="YYYY MMMM DD", lang="ne", ne_digits=True))


print("\n=== NOW (BS + AD) ===")
bs_now, dt_now = now()
print("Now BS (ISO)      :", str(bs_now))
print("Now AD (ISO)      :", dt_now.isoformat())


bs_now_en, dt_now_en = now(fmt="YYYY MMM D", lang="en")
print("Now BS (EN)       :", bs_now_en)


bs_now_ne, dt_now_ne = now(fmt="YYYY MMMM DD", lang="ne", ne_digits=True)
print("Now BS (NE)       :", bs_now_ne)

print("\n=== Holidays ===")
print("Current year public (top 5):", list_holiday(tags=["public"], limit=5))
print("Festival in Ashwin:", list_holiday(tags=["festival"], month=6))
print("Search 'Dashain':", list_holiday(query="Dashain", limit=3))
print("Next from 2082-06-10:", next_holiday("2082-06-10", limit=3, inclusive=True))
print("Between 2082-05-01..2082-06-30:", list_holiday_between("2082-05-01", "2082-06-30", tags=["festival"]))

print("\n=== Script: Transliterate ===")
print("roman → dev:", roman_to_dev("santosh kandel"))
print("dev → roman:", dev_to_roman("नेपाल २०२५"))

print("\n=== Script: Alphabet ===")
print("Vowels (dev):", vowel_alphabet(out="dev")[:6])
print("Consonants (roman):", consonant_alphabet(out="roman")[:8])
print("Vowels with examples:", vowel_alphabet(out="pair", example=True)[:3])

print("Barakhari:", table(out="dev"))

print("Specific Base:", table(["ka", "kha"], out="dev"))

print("\n=== Gazetteer ===")
print("Provinces:", list_provinces()[:2])
print("Bagmati zone:", get_zone("Bagmati"))
print("Districts in Bagmati:", list_districts(zone="Bagmati")[:5])
print("Places (heritage in P3):", list_places(province="P3", tags_any=["heritage"])[:3])
print("Nearby heritage (KTM ±30km):", nearby_places(27.7172, 85.3240, radius_km=30, tags_any=["heritage"])[:3])
print("Search 'kathmandu':", search("kathmandu", kinds=["district","place","famous"])[:3])
print("Suggest 'ka':", suggest("ka", kinds=["district","place"], limit=5))

print("\n=== Units ===")
print("1 bigha → m2:", convert(1, "bigha", "m2"))
print("5000 sq ft → aana:", convert(5000, "sq ft", "aana"))

print("\n=== Treks ===")
print("All treks (sample):", list_treks()[:2])
print("Search 'everest':", search_treks("everest", limit=3))
print("Nearby treks from KTM (≤120km):", nearby_treks(27.7172, 85.3240, radius_km=120)[:3])