Conversion and calendar model

NepaliDateConverter is the facade application code should use. NepaliCalendarModel is the underlying locale-aware engine, and NepaliCalendarDefaults holds the supported year ranges and boundary calendars.

NepaliDateConverter

class NepaliDateConverter[source]

Bases: object

A utility class for handling Nepali date conversions, formatting, and related operations.

property today_nepali_calendar: CustomCalendar

Returns today’s date in the Nepali calendar as a CustomCalendar.

property today_english_calendar: CustomCalendar

Returns today’s date in the English calendar as a CustomCalendar.

property today_nepali_simple_date: SimpleDate

Returns today’s date in the Nepali calendar as a SimpleDate.

property today_english_simple_date: SimpleDate

Returns today’s date in the English calendar as a SimpleDate.

property current_time: SimpleTime

Returns the current time in Asia/Kathmandu timezone as a SimpleTime object.

static convert_english_to_nepali(english_yyyy, english_mm, english_dd)[source]

Converts an English date to a Nepali date.

Parameters:

  • english_yyyy (int) – Year in English calendar.

  • english_mm (int) – Month in English calendar (1-12).

  • english_dd (int) – Day in English calendar (1-31).

Returns:

Corresponding Nepali date.

Return type:

CustomCalendar

static convert_nepali_to_english(nepali_yyyy, nepali_mm, nepali_dd)[source]

Converts a Nepali date to an English date.

Parameters:

  • nepali_yyyy (int) – Year in Nepali calendar.

  • nepali_mm (int) – Month in Nepali calendar (1-12).

  • nepali_dd (int) – Day in Nepali calendar (1-32).

Returns:

Corresponding English date.

Return type:

CustomCalendar

static get_nepali_calendar(nepali_yyyy, nepali_mm, nepali_dd)[source]

Gets the Nepali calendar representation for a specific Nepali date.

Parameters:

  • nepali_yyyy (int) – Year in Nepali calendar.

  • nepali_mm (int) – Month in Nepali calendar (1-based index).

  • nepali_dd (int) – Day of the month (1-based index).

Returns:

Detailed Nepali calendar information.

Return type:

CustomCalendar

static get_nepali_calendar_after_addition_or_subtraction(year, month, day_of_month, days_to_adjust)[source]

Adjusts a given Nepali date by adding or subtracting days.

Parameters:

  • year (int) – Nepali year.

  • month (int) – Nepali month (1-12).

  • day_of_month (int) – Nepali day of the month (1-32).

  • days_to_adjust (int) – Number of days to adjust (positive or negative).

Returns:

Adjusted Nepali date.

Return type:

CustomCalendar

static get_nepali_month_calendar(nepali_year, nepali_month)[source]

Gets the details of a Nepali month.

Parameters:

  • nepali_year (int) – Nepali year.

  • nepali_month (int) – Nepali month (1-12).

Returns:

Details of the specified Nepali month.

Return type:

NepaliMonthCalendar

static get_english_month_calendar(english_year, english_month)[source]

Gets the details of an English month, the Gregorian counterpart of get_nepali_month_calendar.

Parameters:

  • english_year (int) – English year, within NepaliCalendarDefaults.EnglishYearRange.

  • english_month (int) – English month (1-12).

Returns:

Details of the specified English month, tagged as Gregorian.

Return type:

MonthCalendar

static get_english_calendars_in_month(english_year, english_month)[source]

Every day of an English month as a CustomCalendar, in day order.

Parameters:

  • english_year (int) – English year, within NepaliCalendarDefaults.EnglishYearRange.

  • english_month (int) – English month (1-12).

Returns:

One entry per day of the month.

Return type:

list[CustomCalendar]

static get_nepali_calendars_in_english_month(english_year, english_month)[source]

The Bikram Sambat equivalent of every day of an English month, in day order, with None for days before NepaliCalendarDefaults.minConvertibleEnglishDate.

Converts the whole month in one pass, so prefer this over calling convert_english_to_nepali in a loop when mapping a full English month to Bikram Sambat.

Parameters:

  • english_year (int) – English year, within NepaliCalendarDefaults.EnglishYearRange.

  • english_month (int) – English month (1-12).

Returns:

One entry per day, None where the day has no equivalent.

Return type:

list[CustomCalendar | None]

static get_english_calendars_in_nepali_month(nepali_year, nepali_month)[source]

The English equivalent of every day of a Nepali month, in day order.

Converts the whole month in one pass, so prefer this over calling convert_nepali_to_english in a loop when rendering a Nepali month that also shows English dates.

Parameters:

  • nepali_year (int) – Nepali year, within NepaliCalendarDefaults.NepaliYearRange.

  • nepali_month (int) – Nepali month (1-12).

Returns:

One entry per day of the Nepali month.

Return type:

list[CustomCalendar]

static get_english_calendar(english_yyyy, english_mm, english_dd)[source]

Gets the English calendar representation of an English date.

Unlike convert_nepali_to_english, which starts from a Bikram Sambat date, this reads the Gregorian date directly and needs no conversion anchor, so it answers for any year. The derived fields (day of week, day of year, week of month and week of year) follow the same definitions the Bikram Sambat calendars use.

Parameters:

  • english_yyyy (int) – English year.

  • english_mm (int) – English month (1 for January, 12 for December).

  • english_dd (int) – Day of the month.

Returns:

The English calendar for that date.

Return type:

CustomCalendar

Raises:

ValueError – If the month or day is not a real day of that month.

static is_english_date_convertible(english_yyyy, english_mm, english_dd)[source]

Reports whether an English date has a Bikram Sambat equivalent in the supported table.

NepaliCalendarDefaults.EnglishYearRange alone is not a sufficient check: the calendars start mid-year relative to each other, so 1913-01-01 through 1913-04-12 sit inside the year range yet cannot be converted.

Parameters:

  • english_yyyy (int) – English year.

  • english_mm (int) – English month (1-12).

  • english_dd (int) – Day of the month.

Returns:

True when convert_english_to_nepali accepts the date.

Return type:

bool

static get_total_days_in_nepali_month(year, month)[source]

Gets the total days in a Nepali month.

Parameters:

  • year (int) – Nepali year.

  • month (int) – Nepali month (1-12).

Returns:

Total days in the month.

Return type:

int

static get_total_days_in_english_month(year, month)[source]

Gets the total days in an English month.

Parameters:

  • year (int) – English year.

  • month (int) – English month (1-12).

Returns:

Total days in the month.

Return type:

int

static get_nepali_days_in_between(start_date, end_date)[source]

Calculates the total number of days between two SimpleDate objects in the Nepali calendar.

The end date is not included in the count. Add 1 to the returned value to include the end date.

Parameters:

  • start_date (SimpleDate) – The starting date in the Nepali calendar.

  • end_date (SimpleDate) – The ending date in the Nepali calendar.

Returns:

The number of days between the two dates.

  • Throws an exception if the year is not in the range defined by NepaliDatePickerDefaults.NepaliYearRange.

  • Returns -1 if either date is invalid.

Return type:

int

Raises:

ValueError – If the year of either date is out of the allowed Nepali year range.

class date[source]

Bases: object

date(year, month, day) –> date object

ctime()

Return ctime() style string.

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 fromisoformat()

str -> Construct a date from a string in ISO 8601 format.

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.

isoformat()

Return string in ISO 8601 format, YYYY-MM-DD.

isoweekday()

Return the day of the week represented by the date. Monday == 1 … Sunday == 7

replace()

Return date with new specified fields.

strftime()

format -> strftime() style string.

timetuple()

Return time tuple, compatible with time.localtime().

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.

weekday()

Return the day of the week represented by the date. Monday == 0 … Sunday == 6

static get_english_days_in_between(start_date, end_date)[source]

Calculates the total number of days between two SimpleDate objects in the English calendar.

The end date is not included in the count. Add 1 to the returned value to include the end date.

Parameters:
Returns:

The number of days between the two dates.

Return type:

int

static format_nepali_date(year, month, day_of_month, day_of_week, locale)[source]

Formats a Nepali date based on user preferences.(Without date validation)

Parameters:

  • year (int) – Year of the date.

  • month (int) – Month of the date.

  • day_of_month (int) – Day of the month.

  • day_of_week (int) – Day of the week.

  • locale (NepaliDateLocale) – User preferences for formatting.

Returns:

Formatted date string.

Return type:

str

static format_nepali_date_from_calendar(custom_calendar, locale)[source]

Overload to format a Nepali date from a CustomCalendar object.

Formats a Nepali date based on user preferences. (With date validation)

Parameters:
Returns:

Formatted date string.

Return type:

str

static format_english_date(year, month, day_of_month, day_of_week, locale)[source]

Formats an English date based on the specified user preferences.

Parameters:

  • year (int) – Year of the date.

  • month (int) – Month of the date.

  • day_of_month (int) – Day of the month.

  • day_of_week (int) – Day of the week.

  • locale (NepaliDateLocale) – Locale specifying language, format preferences.

Returns:

Formatted date string.

Return type:

str

static format_english_date_from_calendar(custom_calendar, locale)[source]

Formats an English date based on user preferences using a CustomCalendar object.

Parameters:

  • custom_calendar (CustomCalendar) – Calendar object with date details.

  • locale (NepaliDateLocale) – Locale specifying language, format preferences.

Returns:

Formatted date string.

Return type:

str

static get_weekday_name(day_of_week, format=NameFormat.FULL, language=NepaliCalendarUtilsLang.ENGLISH)[source]

Retrieves the name of a weekday in the specified format and language.

Parameters:

  • day_of_week (int) – Day of the week (1-7).

  • format (str) – Format of the name (SHORT, MEDIUM, FULL).

  • language (NepaliDatePickerLang) – Language for the weekday name.

Returns:

Weekday name.

Return type:

str

Raises:

ValueError – If day_of_week is not between 1 and 7.

static get_month_name(month, format=NameFormat.FULL, language=NepaliCalendarUtilsLang.ENGLISH)[source]

Retrieves the name of a Nepali month in the specified format and language.

Parameters:

  • month (int) – Month of the year (1-12).

  • format (str) – Format of the name (SHORT, FULL).

  • language (NepaliDatePickerLang) – Language for the month name.

Returns:

Month name.

Return type:

str

Raises:

ValueError – If month is not between 1 and 12.

static get_english_month_name(month, format=NameFormat.FULL, language=NepaliCalendarUtilsLang.ENGLISH)[source]

Retrieves the name of an English month in the specified format.

Parameters:

  • month (int) – Month of the year (1-12).

  • format (str) – Format of the name (SHORT, FULL).

  • language (NepaliDatePickerLang) – Language for the month name.

Returns:

Month name.

Return type:

str

Raises:

ValueError – If month is not between 1 and 12.

static get_formatted_time_in_english(simple_time, use_12_hour_format=True)[source]

Formats a SimpleTime object into a time string in English.

Parameters:

  • simple_time (SimpleTime) – The time object to format.

  • use_12_hour_format (bool) – Use 12-hour format if True, 24-hour otherwise.

Returns:

Formatted time string.

Return type:

str

static get_formatted_time_in_nepali(simple_time, use_12_hour_format=True)[source]

Formats a SimpleTime object into a Nepali time string.

Parameters:

  • simple_time (SimpleTime) – The time object to format.

  • use_12_hour_format (bool) – Use 12-hour format if True, 24-hour otherwise.

Returns:

Formatted time string in Nepali.

Return type:

str

static format_nepali_datetime_to_iso(nepali_date, simple_time=None)[source]

Converts a Nepali (Bikram Sambat) date and time to ISO 8601 UTC format.

The Nepali date (Bikram Sambat) is first converted to the equivalent Gregorian (English) date, and then the time is appended to produce a complete timestamp in UTC.

Parameters:

  • nepali_date (SimpleDate) – The date in the Nepali Bikram Sambat calendar.

  • simple_time (SimpleTime, optional) – The time of day. Defaults to the current time.

Returns:

A string in ISO 8601 format representing the UTC date and time.

The result is in the format YYYY-MM-DDTHH:mm:ssZ (Zulu time).

Return type:

str

Example

nepali_date = SimpleDate(2081, 5, 24) # Bikram Sambat date time = SimpleTime(14, 30, 15, 0) iso_format = NepaliDateConverter.format_nepali_date_time_to_iso_format(nepali_date, time) print(iso_format) # Outputs: “2024-09-09T09:00:15Z”

static format_english_date_nepali_time_to_iso(english_date, simple_time=None)[source]

Converts an English (Gregorian) date and time to ISO 8601 UTC format.

Parameters:

  • english_date (SimpleDate) – The date in the Gregorian calendar (English date).

  • simple_time (SimpleTime, optional) – The time of day. Defaults to the current time.

Returns:

A string in ISO 8601 format representing the UTC date and time.

The result is in the format YYYY-MM-DDTHH:mm:ssZ (Zulu time).

Return type:

str

Example

english_date = SimpleDate(2024, 9, 9) time = SimpleTime(14, 30, 15, 0) iso_format = NepaliDateConverter.format_english_date_nepali_time_to_iso_format(english_date, time) print(iso_format) # Outputs: “2024-09-09T09:00:15Z”

static get_nepali_date_time_from_iso_format(iso_date_time)[source]

Converts ISO UTC format to CustomDateTime which represents the Nepali CustomCalendar and Nepali SimpleTime.

Parameters:

iso_date_time (str) –

The ISO format string. Accepted examples:

  • ”2020-08-30T18:43:00Z”

  • ”2020-08-30T18:43:00.503Z”

  • ”2020-08-30T18:43:00.123456Z”

  • ”2020-08-30T18:40:00+03:00”

  • ”2020-08-30T18:40:00+03:30:20”

  • ”2011-11-04”

  • ”2011-11-04 00:05:23.283”

  • ”2011-11-04 00:05:23.283+00:00”

  • ”2011-11-04T00:05:23+04:00”

Returns:

CustomDateTime representing the Nepali calendar and time.

Raises:

ValueError – If the input string cannot be parsed or date boundaries are exceeded.

Return type:

CustomDateTime

Example:

custom_nepali_dt = get_nepali_date_time_from_iso_format("2024-09-09T09:00:15Z")
print(custom_nepali_dt)
static get_english_date_nepali_time_from_iso_format(iso_date_time)[source]

Converts ISO UTC format to CustomDateTime which represents the English CustomCalendar and Nepali SimpleTime.

Parameters:

iso_date_time (str) –

The ISO format string. Accepted examples:

  • ”2020-08-30T18:43:00Z”

  • ”2020-08-30T18:43:00.503Z”

  • ”2020-08-30T18:43:00.123456Z”

  • ”2020-08-30T18:40:00+03:00”

  • ”2020-08-30T18:40:00+03:30:20”

  • ”2011-11-04”

  • ”2011-11-04 00:05:23.283”

  • ”2011-11-04 00:05:23.283+00:00”

  • ”2011-11-04T00:05:23+04:00”

Returns:

CustomDateTime representing the English calendar and Nepali time.

Return type:

CustomDateTime

The result is a Gregorian date and a Nepal-time clock reading, neither of which needs the Bikram Sambat conversion table, so any year parses. Use get_nepali_date_time_from_iso_format for the Bikram Sambat reading, which is limited to NepaliCalendarDefaults.EnglishYearRange.

Raises:

ValueError – If the input string cannot be parsed.

Parameters:

iso_date_time (str)

Return type:

CustomDateTime

Example:

custom_english_dt = get_english_date_nepali_time_from_iso_format("2024-09-09T09:00:15Z")
print(custom_english_dt)
static format_time_by_unicode_pattern(unicode_pattern, time, language=NepaliCalendarUtilsLang.ENGLISH)[source]

Formats a time based on the specified Unicode pattern and language preferences.

Parameters:

  • time (SimpleTime) – An object that holds the time details (hour, minute, second, nanosecond).

  • unicode_pattern (str) – A string specifying the pattern to use for formatting the date and time. The pattern supports various placeholders like “HH”, “hh”, “mm”, “ss”, “SSS”, “a”, etc.

  • language (NepaliDatePickerLang) – Specifies the language for formatting the date and time, including number localization and period labels (AM/PM).

Returns:

A string representing the formatted time according to the provided Unicode pattern and language preferences.

Return type:

str

Supported Unicode pattern placeholders:

  • HH: Hour in 24-hour format (00–23), zero-padded (e.g., “08” or “०८”)

  • H: Hour in 24-hour format, no padding (e.g., “8” or “८”)

  • hh: Hour in 12-hour format (01–12), zero-padded (e.g., “01” or “०१”)

  • h: Hour in 12-hour format, no padding (e.g., “1” or “१”)

  • mm: Minutes, two-digit (e.g., “05” or “०५”)

  • m: Minutes, no padding (e.g., “5” or “५”)

  • ss: Seconds, two-digit (e.g., “09” or “०९”)

  • s: Seconds, no padding (e.g., “9” or “९”)

  • SSSS: Four-digit nanosecond precision (e.g., “1234” or “१२३४”)

  • SSS: Millisecond precision (e.g., “123” or “१२३”)

  • SS: Two-digit fractional seconds (e.g., “12” or “१२”)

  • S: One-digit fractional second (e.g., “1” or “१”)

  • a: Lowercase AM/PM or localized period (e.g., “am” or “बिहान”)

  • A: Uppercase AM/PM or localized period (e.g., “AM” or “साँझ”)

Example

>>> time = SimpleTime(hour=15, minute=30, second=45, nanosecond=123000000)
>>> formatted_time = format_time_by_unicode_pattern(
...     time=time,
...     unicode_pattern="hh:mm:ss.SSS A",
...     language=language
... )
>>> # formatted_time: "03:30:45.123 PM"
static format_english_date_by_unicode_pattern(unicode_pattern, calendar, language=NepaliCalendarUtilsLang.ENGLISH)[source]

Formats an English date based on the specified Unicode pattern and language preferences.

Parameters:

  • unicode_pattern (str) – A string specifying the pattern to use for formatting the date and time. The pattern supports various placeholders like “yyyy”, “MM”, “dd”, “D”, “w”, “E”, etc.

  • calendar (CustomCalendar) – A custom calendar object representing the date.

  • language (NepaliDatePickerLang) – Specifies the language for formatting, including number and text localization.

Returns:

A string representing the formatted date according to the provided Unicode pattern and language preferences.

Return type:

str

Supported Unicode pattern placeholders:

  • yyyy: Four-digit year (e.g., “2025” or “२०२५”)

  • yy: Two-digit year (e.g., “25” or “२५”)

  • MMMM: Full month name (e.g., “January” or “जनवरी”)

  • MMM: Abbreviated month name (e.g., “Jan” or “जन”)

  • MM: Two-digit month (e.g., “01” or “०१”)

  • M: Month number, no padding (e.g., “1” or “१”)

  • dd: Two-digit day of the month (e.g., “04” or “०४”)

  • d: Day of the month, no padding (e.g., “4” or “४”)

  • D: Day of the year (1–366) (e.g., “123” or “१२३”)

  • w: Week of the year (e.g., “23” or “२३”)

  • EEEE: Full weekday name (e.g., “Monday” or “सोमबार”)

  • E: Medium weekday name (e.g., “Mon” or “सोम”)

  • EEEEE: Short weekday name, if defined (e.g., “M” or “स”)

  • ee: Two-digit day of the week (e.g., “02” or “०२”)

  • e: Day of the week, no padding (e.g., “2” or “२”)

Example

>>> calendar = CustomCalendar(year=2025, month=5, day_of_month=14, day_of_week=3, ...)
>>> formatted_date = format_english_date_by_unicode_pattern(
...     "yyyy-MM-dd EEEE",
...     calendar,
...     language=NepaliDatePickerLang.ENGLISH
... )
>>> # formatted_date: "2025-05-14 Tuesday"
static format_nepali_date_by_unicode_pattern(unicode_pattern, calendar, language=NepaliCalendarUtilsLang.NEPALI)[source]

Formats a Nepali date based on the specified Unicode pattern and language preferences.

Parameters:

  • unicode_pattern (str) – A string specifying the pattern to use for formatting the date and time. The pattern supports various placeholders like “yyyy”, “MM”, “dd”, “D”, “E”, “ee”, etc.

  • calendar (CustomCalendar) – A custom calendar object representing the Nepali date.

  • language (NepaliDatePickerLang, optional) – Language preference for formatting. Defaults to NepaliDatePickerLang.NEPALI, which uses Nepali names for months and weekdays.

Returns:

A string representing the formatted date and time according to the specified Unicode pattern and language.

Return type:

str

Supported Unicode pattern placeholders:

  • yyyy: Four-digit year (e.g., “2025” or “२०२५”)

  • yy: Two-digit year (e.g., “25” or “२५”)

  • MMMM: Full month name (e.g., “Baisakh” or “बैशाख”)

  • MMM: Abbreviated month name (e.g., “Bai” or “बै”)

  • MM: Two-digit month (e.g., “01” or “०१”)

  • M: Month number, no padding (e.g., “1” or “१”)

  • dd: Two-digit day of the month (e.g., “04” or “०४”)

  • d: Day of the month, no padding (e.g., “4” or “४”)

  • D: Day of the year (1–366) (e.g., “123” or “१२३”)

  • w: Week of the year (e.g., “23” or “२३”)

  • EEEE: Full weekday name (e.g., “Monday” or “सोमबार”)

  • E: Medium weekday name (e.g., “Mon” or “सोम”)

  • EEEEE: Short weekday name, if defined (e.g., “M” or “स”)

  • ee: Two-digit day of the week (e.g., “02” or “०२”)

  • e: Day of the week, no padding (e.g., “2” or “२”)

Example

>>> calendar = CustomCalendar(year=2025, month=5, day_of_month=14, day_of_week=3, ...)
>>> formatted_date = format_nepali_date_by_unicode_pattern(
...     "yyyy-MM-dd EEEE",
...     calendar,
...     language=NepaliDatePickerLang.ENGLISH
... )
>>> # formatted_date: "2025-05-14 Tuesday"
static format_english_date_time_by_unicode_pattern(unicode_pattern, calendar, time=None, language=NepaliCalendarUtilsLang.ENGLISH)[source]

Formats an English date and time based on the specified Unicode pattern and language preferences.

Parameters:

  • unicode_pattern (str) – A string specifying the pattern to use for formatting the date and time. The pattern supports placeholders like “yyyy”, “MM”, “dd”, “hh”, “mm”, “ss”, etc.

  • calendar (CustomCalendar) – A custom calendar object representing the date.

  • time (SimpleTime, optional) – Time information (hour, minute, second, nanosecond). If omitted, the formatted string includes only the date.

  • language (NepaliDatePickerLang, optional) – Language preference for formatting. Defaults to NepaliDatePickerLang.ENGLISH, which uses English month and weekday names.

Returns:

A string representing the formatted date and time based on the Unicode pattern and language.

Return type:

str

Supported Unicode pattern placeholders:
Date:

  • yyyy: Four-digit year (e.g., “2025” or “२०२५”)

  • yy: Two-digit year (e.g., “25” or “२५”)

  • MMMM: Full month name (e.g., “January” or “जनवरी”)

  • MMM: Abbreviated month name (e.g., “Jan” or “जन”)

  • MM: Two-digit month (e.g., “01” or “०१”)

  • M: Month number, no padding (e.g., “1” or “१”)

  • dd: Two-digit day of the month (e.g., “04” or “०४”)

  • d: Day of the month, no padding (e.g., “4” or “४”)

  • D: Day of the year (1–366) (e.g., “123” or “१२३”)

  • w: Week of the year (e.g., “23” or “२३”)

  • EEEE: Full weekday name (e.g., “Monday” or “सोमबार”)

  • E: Medium weekday name (e.g., “Mon” or “सोम”)

  • EEEEE: Short weekday name, if defined (e.g., “M” or “स”)

  • ee: Two-digit day of week (e.g., “02” or “०२”)

  • e: Day of week, no padding (e.g., “2” or “२”)

Time:

  • HH: Hour in 24-hour format (00–23) (e.g., “08” or “०८”)

  • H: Hour in 24-hour format, no padding (e.g., “8” or “८”)

  • hh: Hour in 12-hour format (01–12) (e.g., “01” or “०१”)

  • h: Hour in 12-hour format, no padding (e.g., “1” or “१”)

  • mm: Minutes, two-digit (e.g., “05” or “०५”)

  • m: Minutes, no padding (e.g., “5” or “५”)

  • ss: Seconds, two-digit (e.g., “09” or “०९”)

  • s: Seconds, no padding (e.g., “9” or “९”)

  • SSSS: Nanosecond precision (four digits, e.g., “1234” or “१२३४”)

  • SSS: Milliseconds (e.g., “123” or “१२३”)

  • SS: Two-digit fractional seconds (e.g., “12” or “१२”)

  • S: One-digit fractional second (e.g., “1” or “१”)

Period:

  • a: Lowercase AM/PM or localized form (e.g., “am” or “बिहान”)

  • A: Uppercase AM/PM or localized form (e.g., “AM” or “साँझ”)

Example

>>> calendar = CustomCalendar(year=2025, month=5, day_of_month=14, day_of_week=3, ...)

>>> time = SimpleTime(hour=15, minute=30, second=45, nanosecond=123)
>>> formatted = format_english_date_time_by_unicode_pattern(
...     "yyyy-MM-dd EEEE hh:mm:ss a",
...     calendar,
...     time
... )
>>> # formatted: "2025-05-14 Tuesday 03:30:45 PM"
static format_nepali_date_time_by_unicode_pattern(unicode_pattern, calendar, time=None, language=NepaliCalendarUtilsLang.NEPALI)[source]

Formats a Nepali date and optional time using a Unicode-like pattern and language preferences.

Parameters:

  • calendar (CustomCalendar) – A Nepali calendar date to format.

  • time (SimpleTime, optional) – Optional time with hour, minute, second, and nanosecond. If not provided, only the date is included in the output.

  • unicode_pattern (str) – A formatting pattern string using placeholders like “yyyy”, “MM”, “dd”, “hh”, “mm”, etc.

  • language (NepaliDatePickerLang, optional) – Language used to localize names like months and weekdays. Defaults to NepaliDatePickerLang.NEPALI.

Returns:

A formatted date/time string based on the provided pattern and localization.

Return type:

str

Supported placeholders in unicode_pattern:

Date:

  • yyyy: Four-digit year (e.g., “2025” or “२०२५”)

  • yy: Two-digit year (e.g., “25” or “२५”)

  • MMMM: Full month name (e.g., “Baisakh” or “बैशाख”)

  • MMM: Abbreviated month name (e.g., “Bai” or “बै”)

  • MM: Two-digit month (e.g., “01” or “०१”)

  • M: Month without padding (e.g., “1” or “१”)

  • dd: Two-digit day of month (e.g., “04” or “०४”)

  • d: Day without padding (e.g., “4” or “४”)

  • D: Day of year (1–366) (e.g., “123” or “१२३”)

  • w: Week of year (e.g., “23” or “२३”)

Weekdays:

  • EEEE: Full weekday name (e.g., “Monday” or “सोमबार”)

  • E: Medium weekday name (e.g., “Mon” or “सो”)

  • EEEEE: Shortest weekday (e.g., “M” or “स”)

  • ee: Two-digit day of week (e.g., “02” or “०२”)

  • e: Day of week without padding (e.g., “2” or “२”)

Time:

  • HH: 24-hour format, two digits (e.g., “08” or “०८”)

  • H: 24-hour format, no padding (e.g., “8” or “८”)

  • hh: 12-hour format, two digits (e.g., “01” or “०१”)

  • h: 12-hour format, no padding (e.g., “1” or “१”)

  • mm: Minutes, two digits (e.g., “05” or “०५”)

  • m: Minutes, no padding (e.g., “5” or “५”)

  • ss: Seconds, two digits (e.g., “09” or “०९”)

  • s: Seconds, no padding (e.g., “9” or “९”)

Fractions:

  • SSSS: Nanosecond precision (4 digits, e.g., “1234” or “१२३४”)

  • SSS: Millisecond precision (e.g., “123” or “१२३”)

  • SS: Hundredths (e.g., “12” or “१२”)

  • S: Tenths (e.g., “1” or “१”)

Periods:

  • a: Lowercase period (e.g., “am” or “बिहान”)

  • A: Uppercase period (e.g., “AM” or “साँझ”)

Example

>>> calendar = CustomCalendar(year=2025, month=5, day_of_month=14, day_of_week=3)
>>> time = SimpleTime(hour=15, minute=30, second=45, nanosecond=123_000_000)
>>> format_nepali_datetime_by_unicode_pattern(
...     calendar,
...     time,
...     "yyyy-MM-dd EEEE hh:mm:ss.SSS a",
...     language=NepaliDatePickerLang.ENGLISH
... )
'2025-05-14 Tuesday 03:30:45.123 PM'
static compare_calendar_dates(date_to_compare_from, date_to_compare_to)[source]

Compares two CustomCalendar instances to determine their chronological order.

Returns:

  • A negative integer if date_to_compare_from is before date_to_compare_to.

  • Zero if they are equal.

  • A positive integer if date_to_compare_from is after date_to_compare_to.

Parameters:

  • date_to_compare_from (CustomCalendar) – The first date in the comparison.

  • date_to_compare_to (CustomCalendar) – The second date, which date_to_compare_from is compared to.

Returns:

A negative integer, zero, or a positive integer as described above.

Return type:

int

static compare_simple_dates(simple_date, year, month, day_of_month)[source]

Compares a SimpleDate instance with a date represented by the given year, month, and day_of_month.

Returns:

  • A negative integer if the simple_date is before the given date.

  • Zero if they are equal.

  • A positive integer if the simple_date is after the given date.

Parameters:

  • simple_date (SimpleDate) – The SimpleDate instance to compare.

  • year (int) – The year of the date to compare with.

  • month (int) – The month of the date to compare with.

  • day_of_month (int) – The day of the month of the date to compare with.

Returns:

A negative integer, zero, or a positive integer as described above.

Return type:

int

static replace_delimiter(text, new_delimiter, old_delimiter=None)[source]

Replaces delimiters in a string with a new delimiter.

Parameters:

  • text (str) – The input string with delimiters to replace.

  • new_delimiter (str) – The new delimiter to use in the string.

  • old_delimiter – The old delimiter to replace. If None, replace all non-alphanumeric delimiters.

Returns:

The string with replaced delimiters.

Return type:

str

static localize_number(number, lang)[source]

Localizes a number string based on the provided locale.

Parameters:
Returns:

Localized number.

Return type:

str

static convert_to_nepali_number(english_string)[source]

Converts an English number string to Nepali digits.

Parameters:

english_string (str) – English number string.

Returns:

Nepali number string.

Return type:

str

static convert_to_english_number(nepali_string)[source]

Converts a Nepali number string to English digits.

Parameters:

nepali_string (str) – Nepali number string.

Returns:

English number string.

Return type:

str

static localize_digits(text, script)[source]

Localizes Latin digits in a string to the given digit script.

Non-digit characters and digits already outside ASCII 0-9 are kept verbatim. For DigitScript.LATIN this is a no-op.

Example

localize_digits(“2082/02/14”, DigitScript.DEVANAGARI) # “२०८२/०२/१४”

Parameters:
Return type:

str

static to_latin_digits(text)[source]

Inverse of localize_digits. Converts digits in any supported non-Latin script back to ASCII 0-9. Non-digit characters pass through unchanged.

Example

to_latin_digits(“२०८२/०२/१४”) # “2082/02/14”

Parameters:

text (str)

Return type:

str

static before_date_selectable(simple_date, include_date=False)[source]

Returns a NepaliSelectableDates that allows selection of dates before the given date.

Parameters:

  • simple_date (SimpleDate) – The date before which selection is allowed.

  • include_date (bool) – Whether to include the given date itself.

Return type:

NepaliSelectableDates

static after_date_selectable(simple_date, include_date=False)[source]

Returns a NepaliSelectableDates that allows selection of dates after the given date.

Parameters:

  • simple_date (SimpleDate) – The date after which selection is allowed.

  • include_date (bool) – Whether to include the given date itself.

Return type:

NepaliSelectableDates

static date_range_selectable(min_date, max_date, include_min_date=False, include_max_date=False)[source]

Returns a NepaliSelectableDates representing a selectable date range.

min_date should be less than or equal to max_date.

Parameters:

  • min_date (SimpleDate) – The minimum selectable date.

  • max_date (SimpleDate) – The maximum selectable date.

  • include_min_date (bool) – Whether min_date is included in the range.

  • include_max_date (bool) – Whether max_date is included in the range.

Return type:

NepaliSelectableDates

static working_days_between(start_date, end_date, provider, weekend=None)[source]

Number of working days in the half-open range [start_date, end_date), skipping weekend days and the dates provider closes. provider may be a NepaliCalendarPolicy, which carries its own weekly off days. See nepali_calendar_utils.event.working_days_between.

static next_working_day(from_date, provider, weekend=None)[source]

First working day at or after from_date. provider may be a NepaliCalendarPolicy, which carries its own weekly off days. See nepali_calendar_utils.event.next_working_day.

static add_working_days(from_date, days, provider, weekend=None)[source]

The date that is days working days from from_date (Excel WORKDAY semantics). provider may be a NepaliCalendarPolicy, which carries its own weekly off days. See nepali_calendar_utils.event.add_working_days.

NepaliCalendarModel

NepaliCalendarDefaults