Nepali Date Python - Changelog

List of Changes of all versions of Nepali Date Python

[1.0.2] - 2026-08-10

Fixed

• BS Date Off-By-One Near Midnight in Nepal
  • The current Nepali date (NepaliDate(), or any real datetime passed into the constructor) was derived straight from the input's UTC calendar date
  • Since Nepal Standard Time is UTC+05:45, the calendar day rolled over 5 hours 45 minutes late — the BS date showed one day behind actual Nepal time between local midnight and 5:45 AM
  • Added a NEPAL_UTC_OFFSET_MS constant; set_english_date() now shifts the input instant by Nepal's UTC+05:45 offset before deriving year/month/day, so results are correct at any moment regardless of the server's own timezone
• get_hours() / get_minutes() / get_seconds() / get_day() Now Nepal Local Time
  • Previously read the raw stored datetime's fields directly, which reflect UTC (or whatever timezone the caller supplied), not Nepal Standard Time
  • All four now apply the explicit NEPAL_UTC_OFFSET_MS shift before reading the value, so they always reflect UTC+05:45 regardless of the input's own timezone
• start_of_day() / end_of_day() Now Anchor to Nepal Midnight
  • Previously used datetime.replace() on the raw stored fields, which could reconstruct the instance via the Gregorian-to-BS constructor path and roll the result onto the following BS day now that day derivation is Nepal-offset-aware
  • Now clones the instance and computes the true UTC instant corresponding to 00:00:00.000 / 23:59:59.999 Nepal local time directly, without re-deriving the BS day, so the day never shifts

Migration Notes

• ⚠️ get_hours(), get_minutes(), get_seconds(), get_day(), and start_of_day()/end_of_day() now report Nepal Standard Time (UTC+05:45) instead of the stored datetime's raw fields. get_english_date() for start_of_day()/end_of_day() now returns the true Gregorian instant matching Nepal midnight (18:15/18:14:59.999 UTC on the previous/same Gregorian day) rather than 00:00:00/23:59:59.999 UTC — update any code that string-compares or serializes these directly.
• BS dates derived from the current moment (NepaliDate(), or any datetime within roughly 5 hours 45 minutes of a UTC day boundary) may now report a different, correct day, since day derivation is Nepal-timezone-aware rather than pure UTC.

---

[1.0.1] - 2026-07-26

Added

• New Time-of-Day Getters
  • Added get_hours(), get_minutes(), get_seconds(), and get_milliseconds() to read the time component of a NepaliDate
  • Added get_time() to return the Unix epoch timestamp in milliseconds
• Out-of-Range Date Validation
  • Date-index lookup now raises ValueError("Date is out of the supported range") for dates outside the supported BS range instead of failing with an unrelated error

Fixed

• get_day() Weekday Indexing
  • get_day() was Monday-indexed (0=Monday) via Python's native datetime.weekday()
  • Now remapped to Sunday-indexed (0=Sunday .. 6=Saturday) to match the WEEK_EN/WEEK_NP constants and the indexing used by the NodeJS and PHP ports
• Unix Timestamp Construction
  • Constructing a NepaliDate from an integer Unix timestamp (milliseconds) now interprets it in UTC instead of the host's local timezone, giving consistent results across machines
• maximum() Method
  • Corrected the day offset used to compute the maximum supported date
  • Previously returned a date one day past the actual last supported day

Changed

• Comprehensive Test Suite
  • Replaced the basic test suite with dedicated pytest modules covering constants, date conversion, and the full supported date range
• CI Test Matrix
  • Added Python 3.13 to the test matrix and dropped Python 3.8

Migration Notes

• ⚠️ Minor breaking change: code relying on get_day()'s previous Monday-indexed return value must adjust — the value now follows the Sunday-indexed convention (0=Sunday) shared with WEEK_EN/WEEK_NP and the other language ports.
• Constructing a NepaliDate from a raw Unix timestamp integer may now resolve to a different local date for timestamps near midnight, since the timestamp is interpreted in UTC rather than local time.

---

[1.0.0] - 2026-03-17

Added

• Initial Release
  • Complete Nepali Date library for Python
  • Ported from TypeScript implementation with Python-specific optimizations
  • Core date conversion between BS (Bikram Sambat) and AD (Anno Domini)
  • Date arithmetic operations (add/subtract days, months, years)
  • Date comparison and validation
  • Formatting and parsing utilities
  • Nepali calendar utilities

Features

Date Conversion

• Convert between Nepali (BS) and English (AD) dates
• Accurate conversion algorithm for years 2000 BS to 2100 BS
• Support for historical and future date conversions

Date Manipulation

• Add or subtract days, months, and years
• Get start/end of day, week, month, year
• Navigate between dates with intuitive methods
• Handle edge cases and month overflow correctly

Date Formatting

• Format dates in various Nepali and English formats
• Custom format strings support
• Localized month and day names in Nepali

Date Validation

• Validate Nepali dates
• Check for leap years in Nepali calendar
• Verify date ranges and boundaries

Utilities

• Get days in month for any Nepali year/month
• Check if date is in the past or future
• Calculate difference between dates
• Clone and compare date objects

Installation

pip install nepali-date

Basic Usage

from nepali_date import NepaliDate

# Create a Nepali date
nepali_date = NepaliDate(2081, 5, 15)  # 2081 Bhadra 15

# Convert to AD
ad_date = nepali_date.to_ad()
print(ad_date)  # 2024-08-31

# Create from AD date
from datetime import date
nepali_from_ad = NepaliDate.from_ad(date(2024, 8, 31))
print(nepali_from_ad)  # 2081-05-15

# Date arithmetic
tomorrow = nepali_date.add_days(1)
next_month = nepali_date.add_months(1)
next_year = nepali_date.add_years(1)

# Formatting
formatted = nepali_date.format("%Y-%m-%d")  # 2081-05-15
nepali_formatted = nepali_date.format_nepali()  # २०८१-०५-१५

# Validation
is_valid = NepaliDate.is_valid_date(2081, 5, 15)  # True
days_in_month = NepaliDate.days_in_month(2081, 5)  # 31