`date`

Defines the BSDate class for representing dates in the Bikram Sambat calendar.

This module provides the BSDate object, a subclass of the standard datetime.date. It is designed to be a drop-in replacement, allowing for intuitive date manipulation, formatting, and arithmetic, all within the context of the Bikram Sambat calendar system.

Examples

from bikram_sambat import date, timedelta

# Create a date
d = date(2081, 1, 1)

# Get today's date
today = date.today()

# Convert from Gregorian
from datetime import date as ad_date
ad = ad_date(2024, 4, 13)
bs = date.fromgregorian(ad)

# Convert to Gregorian
ad_new = bs.togregorian()

# Arithmetic
d2 = d + timedelta(days=10)
diff = d2 - d

# Formatting
print(d.strftime("%Y-%m-%d"))
# >> 2081-01-01

print(d.strftime("%A, %B %d, %Y"))
# >> Saturday, Baishakh 01, 2081

print(d.strftime("%G, %N %D, %K"))
# >> शनिबार, वैशाख ०१, २०८१

class bikram_sambat.bs_date.BSDate(year: int, month: int, day: int)[source]

Bases: date

An immutable date object representing a date in the Bikram Sambat (BS) calendar.

BSDate is a subclass of datetime.date and supports all of its methods. However, key attributes and methods are overridden to reflect the BS calendar:

Attributes like .year, .month, and .day return the BS date components.
Methods like weekday() and strftime() operate according to the BS calendar.
Arithmetic operations (+, -) work correctly for BS dates.

It provides a seamless way to work with Nepali dates while maintaining compatibility with the standard Python datetime ecosystem.

Parameters:

year (int) – The Bikram Sambat year.
month (int) – The Bikram Sambat month (1-12).
day (int) – The Bikram Sambat day.

year

The BS year.

Type:: int

month

The BS month.

Type:: int

day

The BS day.

Type:: int

Raises:

InvalidTypeError – If year, month, or day are not integers.
DateOutOfRangeError – If the year is outside the supported range (1901-2199).
InvalidDateError – If the month is invalid or the day does not exist for the given month and year.

Example

>>> from bikram_sambat import date, timedelta
>>> import datetime

>>> # Create a BSDate instance
>>> bs_date = date(2081, 4, 15)
>>> print(bs_date)
2081-04-15

>>> # Access properties
>>> print(f"Year: {bs_date.year}, Month: {bs_date.month}")
Year: 2081, Month: 4

>>> # Perform date arithmetic
>>> new_bs_date = bs_date + timedelta(days=10)
>>> print(new_bs_date)
2081-04-25

>>> # Calculate the difference between two dates
>>> diff = date(2082, 1, 1) - date(2081, 1, 1)
>>> print(f"Days in year 2081: {diff.days}")
Days in year 2081: 366

>>> # Convert to a standard Gregorian date
>>> greg_date = bs_date.togregorian()
>>> print(greg_date)
2024-07-30

property year: int: Returns the BS year as an integer.

property month: int: Returns the BS month as an integer (1-12).

property day: int: Returns the BS day as an integer.

isoformat() → str[source]: Returns the date in ISO 8601 format, ‘YYYY-MM-DD’.

classmethod today() → BSDate[source]

Returns the current local BSDate.

Example

>>> today_bs = BSDate.today()
>>> print(f"Today's BS date is {today_bs}")

classmethod fromisoformat(date_string: str) → BSDate[source]

Creates a BSDate from an ISO 8601 formatted string (‘YYYY-MM-DD’).

Example

>>> date.fromisoformat('2081-04-15')
bikram_sambat.date.BSDate(2081, 4, 15)

classmethod fromgregorian(greg_date_input: date) → BSDate[source]

Creates a BSDate from a standard datetime.date (Gregorian) object.

This is the primary way to convert from a Gregorian date to a BS date.

Parameters:: greg_date_input (_dt.date) – The Gregorian date to convert.
Returns:: The equivalent BSDate object.
Return type:: BSDate

Example

>>> import datetime
>>> greg_date = datetime.date(2024, 7, 15)
>>> bs_date = date.fromgregorian(greg_date)
>>> print(bs_date)
2081-03-31

togregorian() → date[source]

Converts the BSDate object to a standard datetime.date (Gregorian) object.

This is the primary way to convert from a BS date to a Gregorian date.

Returns:: The equivalent Gregorian date object.
Return type:: _dt.date

Example

>>> bs_date = date(2081, 3, 31)
>>> greg_date = bs_date.togregorian()
>>> print(greg_date)
2024-07-15

replace(year: SupportsIndex = -1, month: SupportsIndex = -1, day: SupportsIndex = -1) → BSDate[source]

Returns a new BSDate with one or more components replaced.

Example

>>> d = date(2081, 4, 15)
>>> d.replace(day=1)
bikram_sambat.date.BSDate(2081, 4, 1)

weekday() → int[source]: Returns the day of the week as an integer (Sunday=0, Saturday=6).

isoweekday() → int[source]: Returns the day of the week as an integer (Sunday=1, Saturday=7).

ctime() → str[source]: Return ctime() style string.

bs_toordinal() → int[source]

classmethod fromisocalendar()

int, int, int -> Construct a date from the ISO year, week number and weekday.

This is the inverse of the date.isocalendar() function

classmethod fromordinal(): int -> date corresponding to a proleptic Gregorian ordinal.

classmethod fromtimestamp(timestamp, /)

Create a date from a POSIX timestamp.

The timestamp is a number, e.g. created via time.time(), that is interpreted as local time.

isocalendar(): Return a named tuple containing ISO year, week number, and weekday.

max = datetime.date(9999, 12, 31)

min = datetime.date(1, 1, 1)

resolution = datetime.timedelta(days=1)

timetuple(): Return time tuple, compatible with time.localtime().

toordinal(): Return proleptic Gregorian ordinal. January 1 of year 1 is day 1.

classmethod bs_fromordinal(ordinal: int) → BSDate[source]

strftime(format: str) → str[source]

Formats the date according to a format string with BS-specific directives.

This method supports all standard strftime directives for dates, plus custom directives for Nepali numerals and names.

Parameters:: format (str) – The strftime-style format string.
Returns:: The formatted date string.
Return type:: str
Raises:: ValueError – If the format string contains an unsupported directive.

Example

>>> d = date(2081, 4, 15)
>>> # English formatting
>>> d.strftime("%A, %B %d, %Y")
'Tuesday, Shrawan 15, 2081'
>>> # Nepali formatting
>>> d.strftime("%G, %N %D, %K")
'मंगलवार, श्रावण १५, २०८१'

classmethod fromstrftime(date_string: str, format: str) → BSDate[source]

Parses a string into a BSDate object according to a format.

This is the reverse of strftime. It can parse strings containing both English and Nepali names and numerals.

Parameters:

date_string (str) – The string to parse.
format (str) – The format that the date_string follows.

Returns:

A new BSDate instance.

Return type:

BSDate

Example

>>> date_str = "मंगलवार, श्रावण १५, २०८१"
>>> format_str = "%G, %N %D, %K"
>>> date.fromstrftime(date_str, format_str)
bikram_sambat.date.BSDate(2081, 4, 15)

date

`date`