Samaya helps you seamlessly convert dates between the Gregorian (AD) and Nepali (BS) calendars, and effortlessly fetch the current time wrapped beautifully inside the Nepal timezone context.

Core Features

  • Convert Dates: Switch intelligently between Gregorian (AD) and Nepali (BS) calendar systems.
  • Timezone Aware: Fetch the exact current date and time formatted in both AD and BS under Nepal's localized timezone.
  • Extremely Lightweight: Maintains a minimal footprint. The only external dependency is pytz.
  • Wide Range Support: Built-in calculation maps spanning from BS years 2000 completely through 2099.

Installation

You can seamlessly install the package via PyPI:

bash 
pip install samaya

For contributors, installing the development mode is straightforward:

bash 
git clone https://github.com/bhaveshadhikari/samaya.git
cd samaya
pip install -e .

Quick Start

Basic Conversions

python 
from samaya import ad_to_bs, bs_to_ad

# Converting from AD to BS
bs_date = ad_to_bs('2025-10-02')
print(bs_date)  # Output: 2082-6-17

# Converting from BS back to AD
ad_date = bs_to_ad('2082-06-17')
print(ad_date)  # Output: 2025-10-2

Retrieving Current Time

python 
from samaya import datetime_now

# Grab the timezone aware localized timestamps
dt = datetime_now()

print(dt.ad_date)   # 2025-10-02
print(dt.bs_date)   # 2082-06-17
print(dt.time)      # Localized time (e.g., 14:30:15)
print(dt.weekday)   # Day of the week (e.g., Thursday)

API Documentation

ad_to_bs(ad_date: str) -> str

Converts a conventionally formatted Gregorian date string into a Nepali date representation.

  • ad_date — Target Gregorian date formatted as 'YYYY-MM-DD'.
  • Returns — Computed Nepali representation formatted as 'YYYY-MM-DD'.

bs_to_ad(bs_date: str) -> str

Transforms a given Nepali date string back into standard Gregorian format.

  • bs_date — Target Nepali date formatted as 'YYYY-MM-DD'.
  • Returns — Synchronized Gregorian representation formatted as 'YYYY-MM-DD'.

datetime_now() -> DateTimeInfo

Retrieves a composite data class containing current timezone sensitive formats. Returns a DateTimeInfo object with the following properties:

  • ad_date: Current Gregorian date.
  • bs_date: Current calculated Nepali date.
  • time: Localized current time encoded as HH:MM:SS.
  • weekday: English localized day of the week.

Find the complete source code on GitHub or checkout the latest releases on PyPI.