`datetime`

Defines the BSDatetime class for timezone-aware date and time objects.

This module provides the BSDatetime object, a subclass of datetime.datetime, which seamlessly integrates BSDate and BSTime functionality. It is designed to be a full-featured, timezone-aware datetime object for the Bikram Sambat calendar system.

Examples

from bikram_sambat import datetime, timedelta, tz

# Create a datetime
dt = datetime(2081, 1, 1, 10, 30, 45)

# Get the current datetime
now = datetime.now()
now_aware = datetime.now(tz.nepal)

# Convert from Gregorian
from datetime import datetime as ad_datetime
ad_dt = ad_datetime(2024, 4, 13, 10, 30, 45)
bs_dt = datetime.fromgregorian(ad_dt)

# Convert to Gregorian
ad_dt_new = bs_dt.togregorian()

# Arithmetic
dt2 = dt + timedelta(days=10, hours=5)
diff = dt2 - dt

# Timezones
dt_utc = now_aware.astimezone(tz.utc)

# Formatting
print(dt.strftime("%Y-%m-%d %H:%M:%S"))
# >> 2081-01-01 10:30:45

print(dt_aware.strftime("%A, %B %d, %Y %I:%M:%S %p %Z"))
# >> Saturday, Baishakh 01, 2081 10:00:00 AM Asia/Kathmandu

print(dt_aware.strftime("%G, %N %D, %K %i:%l:%s %P"))
# >> शनिबार, वैशाख ०१, २०८१ १०:००:०० पूर्वाह्न

class bikram_sambat.bs_datetime.BSDatetime(year: int, month: int, day: int, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, tzinfo: tzinfo | None = None, *, fold: int = 0)[source]

Bases: datetime

A timezone-aware Bikram Sambat (BS) datetime object.

BSDatetime is a subclass of the standard datetime.datetime and is designed to be a full replacement for it when working with BS dates. It combines the features of BSDate and BSTime, providing a complete object that handles both date and time components in the BS calendar.

Key features include: - Date components (.year, .month, .day) are in Bikram Sambat. - Full support for timezone-aware operations, including pytz localization. - BS-specific formatting and parsing via strftime() and fromstrftime(). - Correct arithmetic with timedelta objects. - Compatibility with frameworks like Django that expect a datetime object.

Parameters:

year (int) – The Bikram Sambat year.
month (int) – The Bikram Sambat month (1-12).
day (int) – The Bikram Sambat day.
hour (int) – The hour (0-23). Defaults to 0.
minute (int) – The minute (0-59). Defaults to 0.
second (int) – The second (0-59). Defaults to 0.
microsecond (int) – The microsecond (0-999999). Defaults to 0.
tzinfo (_dt.tzinfo, optional) – A pytz or datetime.tzinfo object. Defaults to None (creating a naive datetime).
fold (int) – Used to disambiguate wall times during a repeated hour (e.g., during a DST transition). 0 or 1. Defaults to 0.

Raises:

InvalidTypeError – If arguments have an incorrect type.
DateOutOfRangeError – If the BS date is outside the supported calendar range.
InvalidDateError – If the BS date is invalid (e.g., day 32).

Example

>>> from bikram_sambat import datetime, tz, timedelta
>>> import pytz

>>> # Create a naive BS datetime
>>> dt_naive = datetime(2081, 4, 15, 10, 30, 0)
>>> print(dt_naive)
2081-04-15T10:30:00

>>> # Create a timezone-aware BS datetime in Nepal
>>> dt_aware = datetime(2081, 4, 15, 10, 30, 0, tzinfo=tz.nepal)
>>> print(dt_aware)
2081-04-15T10:30:00+05:45

>>> # Convert to a different timezone
>>> us_eastern = pytz.timezone('America/New_York')
>>> dt_us = dt_aware.astimezone(us_eastern)
>>> print(dt_us.strftime('%Y-%m-%d %H:%M:%S %Z%z'))
2081-04-15 00:45:00 EDT-0400

property year: int

property month: int

property day: int

date() → BSDate[source]

Returns a BSDate object representing the date part of the datetime.

Example

>>> dt = datetime(2081, 4, 15, 10, 30)
>>> dt.date()
bikram_sambat.date.BSDate(2081, 4, 15)

isoformat(sep: str = 'T', timespec: str = 'auto') → str[source]

Returns the datetime in BS ISO 8601 format.

The date part will be the BS date. The format is YYYY-MM-DDTHH:MM:SS.ffffff. If the object is timezone-aware, the UTC offset is also appended.

Parameters:

sep (str) – The separator between the date and time. Defaults to ‘T’.
timespec (str) – Specifies the precision of the time part. Can be ‘auto’, ‘hours’, ‘minutes’, ‘seconds’, ‘milliseconds’, or ‘microseconds’. Defaults to ‘auto’.

Example

>>> dt = datetime(2081, 4, 15, 10, 30, 5, 123456, tzinfo=tz.nepal)
>>> dt.isoformat()
'2081-04-15T10:30:05.123456+0545'

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

Formats the datetime using a format string with BS-specific directives.

This method supports a rich set of directives for both date and time, including Nepali numerals and names.

Parameters:: format (str) – The strftime-style format string.
Returns:: The formatted datetime string.
Return type:: str

Example

>>> dt = datetime(2081, 4, 15, 22, 10, tzinfo=tz.nepal)
>>> dt.strftime('%Y %B %d, %I:%M %p %Z')
'2081 Shrawan 15, 10:10 PM Asia/Kathmandu'
>>> dt.strftime('%K %N %D, %i:%l %P')
'२०८१ श्रावण १५, १०:१० अपराह्न'

ctime() → str[source]

Returns a string representation like ‘Sun Bai 15 15:30:45 2082 +0545’.

This is equivalent to strftime(“%c”).

classmethod now(tz: tzinfo | None = None) → BSDatetime[source]

Creates a BSDatetime instance for the current local date and time.

If tz is provided, the datetime will be aware of that timezone. Otherwise, it will be a naive datetime based on the system’s locale.

Parameters:: tz (_dt.tzinfo, optional) – A timezone object.

Example

>>> # Get current Nepal time
>>> nepal_now = datetime.now(tz.nepal)
>>> print(nepal_now.strftime('%Y-%m-%d %H:%M:%S %Z'))

classmethod utcnow() → BSDatetime[source]

Creates a BSDatetime instance for the current UTC date and time.

The returned object is timezone-aware with its tzinfo set to tz.utc.

Example

>>> utc_now = datetime.utcnow()
>>> print(utc_now.tzinfo)
UTC

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

Creates a BSDatetime from a BS ISO 8601 formatted string.

Parses strings like ‘2081-04-15T10:30:00+05:45’ or ‘2081-04-15’.

Example

>>> dt = datetime.fromisoformat('2081-04-15T22:10:00+05:45')
>>> dt.year, dt.hour, dt.tzname()
(2081, 22, 'Asia/Kathmandu')

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

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

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

Example

>>> date_str = "2081 Shrawan 15, 10:10 PM"
>>> format_str = "%Y %B %d, %I:%M %p"
>>> datetime.fromstrftime(date_str, format_str)
bikram_sambat.datetime.BSDatetime(2081, 4, 15, 22, 10)

classmethod combine(date: BSDate, time: time, tzinfo: bool | tzinfo = True) → BSDatetime[source]

Creates a new BSDatetime by combining a BSDate and a datetime.time.

Parameters:

date (BSDate) – The date part.
time (_dt.time) – The time part.
tzinfo (Union[bool, _dt.tzinfo]) – If True (default), use time.tzinfo. If a tzinfo object, use it. If False, the result is naive.

Example

>>> from bikram_sambat import date
>>> import datetime as pydt
>>> d = date(2081, 4, 15)
>>> t = pydt.time(10, 30, tzinfo=tz.nepal)
>>> datetime.combine(d, t)
bikram_sambat.datetime.BSDatetime(2081, 4, 15, 10, 30, tzinfo=<DstTzInfo 'Asia/Kathmandu' NPT+5:45:00 STD>)

replace(year: int | None = None, month: int | None = None, day: int | None = None, hour: int | None = None, minute: int | None = None, second: int | None = None, microsecond: int | None = None, tzinfo: bool | tzinfo | None = True, *, fold: int | None = None) → BSDatetime[source]: Returns a new BSDatetime with specified components replaced.

astimezone(tz: tzinfo | None = None) → BSDatetime[source]

Converts the datetime to a different timezone.

If the instance is naive, it is treated as system local time. The tz argument can be any datetime.tzinfo or pytz timezone object.

Parameters:: tz (_dt.tzinfo, optional) – The target timezone. If None, converts to the system’s local timezone.
Returns:: A new, timezone-aware BSDatetime instance.
Return type:: BSDatetime

Example

>>> dt_nepal = datetime(2081, 4, 15, 10, 30, tzinfo=tz.nepal)
>>> dt_utc = dt_nepal.astimezone(tz.utc)
>>> print(dt_utc)
2081-04-15T04:45:00+00:00

weekday() → int[source]: Return the day of the week represented by the date. Monday == 0 … Sunday == 6

isoweekday() → int[source]: Return the day of the week represented by the date. Monday == 1 … Sunday == 7

bs_date_toordinal() → int[source]

classmethod from_datetime(greg_dt: datetime) → BSDatetime[source]

Creates a BSDatetime from a standard datetime.datetime (Gregorian) object.

This is the primary way to convert a Gregorian datetime to a BS datetime. Timezone information is preserved.

Parameters:: greg_dt (_dt.datetime) – The Gregorian datetime object to convert.
Returns:: The equivalent BSDatetime object.
Return type:: BSDatetime

to_datetime() → datetime[source]

Converts the BSDatetime object to a standard datetime.datetime object.

This is the primary way to convert a BS datetime to a Gregorian datetime. Timezone information is preserved.

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

togregorian() → datetime[source]: Alias for to_datetime(). Converts to a standard datetime.datetime object.

classmethod fromgregorian(greg_dt: datetime) → BSDatetime[source]: Alias for from_datetime(). Creates a BSDatetime from a datetime.datetime.

dst(): Return self.tzinfo.dst(self).

fold

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[, tz] -> tz’s local time from POSIX timestamp.

hour

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

max = datetime.datetime(9999, 12, 31, 23, 59, 59, 999999)

microsecond

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

minute

resolution = datetime.timedelta(microseconds=1)

second

classmethod strptime(): string, format -> new datetime parsed from a string (like time.strptime()).

time(): Return time object with same time but with tzinfo=None.

timestamp(): Return POSIX timestamp as float.

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

timetz(): Return time object with same time and tzinfo.

classmethod today(): Current date or datetime: same as self.__class__.fromtimestamp(time.time()).

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

tzinfo

tzname(): Return self.tzinfo.tzname(self).

classmethod utcfromtimestamp(): Construct a naive UTC datetime from a POSIX timestamp.

utcoffset(): Return self.tzinfo.utcoffset(self).

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

datetime

`datetime`