Data models, locale, and formatting

Immutable calendar models, the locale holder, digit-script helpers, and the text-field date formatter.

Calendar models

class SimpleDate(year, month, day_of_month=1)

Bases: object

Represents a simple date with year, month, and day of the month.

Ordered chronologically: comparisons and sorting follow (year, month, day_of_month), so sorted(), min(), max(), and </> work as expected.

Parameters:

• year (int)

• month (int)

• day_of_month (int)

year

The year.

Type:

int

month

The month (1-12).

Type:

int

day_of_month

The day of the month (1-32). Defaults to 1.

Type:

int

index_in(years)

Returns the position of a SimpleDate within a given years range.

Parameters:

years (range)

Return type:

int

class SimpleTime(hour, minute, second, nanosecond)

Bases: object

Represents a 24-hour format time of day (hour, minute, second, nanosecond). Strictly adjusted to the Asia/Kathmandu time zone.

Parameters:

• hour (int)

• minute (int)

• second (int)

• nanosecond (int)

hour

Hour of the day (0-23).

Type:

int

minute

Minute of the hour (0-59).

Type:

int

second

Second of the minute (0-59).

Type:

int

nanosecond

Nanosecond of the second (0-999,999,999).

Type:

int

class NepaliMonthCalendar(year, month, total_days_in_month, first_day_of_month, last_day_of_month)

Bases: object

Represents a calendar month in the Nepali calendar system.

This data class provides information about a specific month in a Nepali calendar year, including the total number of days, the day of the week for the first and last days of the month, and the number of days from the start of the week to the first day of the month.

Parameters:

• year (int)

• month (int)

• total_days_in_month (int)

• first_day_of_month (int)

• last_day_of_month (int)

year

The Nepali year.

Type:

int

month

The Nepali month (1-12).

Type:

int

total_days_in_month

The total number of days in the month (1-32).

Type:

int

first_day_of_month

The day of the week (1-7, where 1 is Sunday) for the first day of the month.

Type:

int

last_day_of_month

The day of the week (1-7, where 1 is Sunday) for the last day of the month.

Type:

int

days_from_start_of_week_to_first_of_month

The number of days from the start of the week (Sunday) to the first day of the month.

Type:

int

index_in(years)

Returns the position of a NepaliMonthCalendar within a given years range.

Parameters:

years (range)

Return type:

int

to_month_calendar()

Reads this Bikram Sambat month as a calendar-tagged MonthCalendar.

Return type:

MonthCalendar

class CustomCalendar(year, month, day_of_month, era, first_day_of_month, last_day_of_month, total_days_in_month, day_of_week_in_month=-1, day_of_week=-1, day_of_year=-1, week_of_month=-1, week_of_year=-1)

Bases: object

Represents a date in a custom calendar system with detailed information.

This data class holds information about a specific date, including its year, month, day, era (AD or BS), and various other properties related to the day and week within the month and year.

Parameters:

• year (int)

• month (int)

• day_of_month (int)

• era (int)

• first_day_of_month (int)

• last_day_of_month (int)

• total_days_in_month (int)

• day_of_week_in_month (int)

• day_of_week (int)

• day_of_year (int)

• week_of_month (int)

• week_of_year (int)

year

The year in the custom calendar.

Type:

int

month

The month in the custom calendar (1-12).

Type:

int

day_of_month

The day of the month (1-32).

Type:

int

era

The era of the calendar (1 for AD, 2 for BS).

Type:

int

first_day_of_month

The day of the week (1-7) for the first day of the month.

Type:

int

last_day_of_month

The day of the week (1-7) for the last day of the month.

Type:

int

total_days_in_month

The total number of days in the month.

Type:

int

day_of_week_in_month

The number of times the day of the week occurs in the month (e.g., 5 for the fifth Friday of the month). Defaults to -1 if not applicable.

Type:

int

day_of_week

The day of the week (1-7, e.g., 1 for Sunday). Defaults to -1 if not applicable.

Type:

int

day_of_year

The day of the year (1-366). Defaults to -1 if not applicable.

Type:

int

week_of_month

The week of the month (1-5). Defaults to -1 if not applicable.

Type:

int

week_of_year

The week of the year (1-53). Defaults to -1 if not applicable.

Type:

int

property calendar_system: CalendarSystem

The CalendarSystem this calendar is expressed in, or BIKRAM_SAMBAT when era holds an unrecognised value.

to_simple_date()

Converts this CustomCalendar object to a SimpleDate object.

Return type:

SimpleDate

to_nepali_month_calendar()

Converts this CustomCalendar object to a NepaliMonthCalendar object.

Return type:

NepaliMonthCalendar

class CustomDateTime(custom_calendar, simple_time)

Bases: object

A data holder representing a CustomCalendar and SimpleTime.

Combines a CustomCalendar instance (representing the calendar) and a SimpleTime instance (representing the time).

Parameters:

• custom_calendar (CustomCalendar)

• simple_time (SimpleTime)

custom_calendar

The custom calendar represented by CustomCalendar.

Type:

CustomCalendar

simple_time

The corresponding time of day represented by SimpleTime.

Type:

SimpleTime

Calendar systems

The two calendar systems this library speaks.

Mirrors dev.shivathapaa.nepalidatepickerkmp.data.CalendarSystem.

class CalendarSystem(value)

Bases: Enum

A calendar system, identified by the era a CustomCalendar carries.

This is the named form of the era integer on CustomCalendar and MonthCalendar (1 = AD, 2 = BS), so the two representations never disagree: era is the single mapping.

A calendar carries the system it was read in, so NepaliDateConverter.get_english_calendar(...) answers GREGORIAN and get_nepali_calendar(...) answers BIKRAM_SAMBAT.

BIKRAM_SAMBAT = 2

Bikram Sambat, the official calendar of Nepal. era 2.

GREGORIAN = 1

Gregorian, referred to as the English or AD calendar throughout this library. era 1.

property era: int

The era value a CustomCalendar in this system carries.

opposite()

The other system. With two systems this is the toggle target.

Return type:

CalendarSystem

classmethod from_era(era)

The system carrying era, or None when era is neither 1 nor 2.

Returns None rather than raising because era reaches this from parsed and restored values that callers are expected to fall back on, not to crash over.

Parameters:

era (int)

Return type:

CalendarSystem | None

A month’s grid geometry, tagged with the calendar system it is expressed in.

Mirrors dev.shivathapaa.nepalidatepickerkmp.data.MonthCalendar.

class MonthCalendar(calendar_system, year, month, total_days_in_month, first_day_of_month, last_day_of_month)

Bases: object

One month of either calendar, carrying the system it belongs to.

NepaliMonthCalendar describes a Bikram Sambat month only. This says the same things about a month of either calendar, so a caller laying out a grid does not have to know which system produced it.

Parameters:

• calendar_system (CalendarSystem)

• year (int)

• month (int)

• total_days_in_month (int)

• first_day_of_month (int)

• last_day_of_month (int)

calendar_system

The system year and month are expressed in.

Type:

CalendarSystem

year

The year in calendar_system.

Type:

int

month

The month (1-12). 1 is Baisakh in Bikram Sambat, January in Gregorian.

Type:

int

total_days_in_month

The number of days in the month (28-32, depending on the calendar).

Type:

int

first_day_of_month

The day of the week (1-7, where 1 is Sunday) the month starts on.

Type:

int

last_day_of_month

The day of the week (1-7, where 1 is Sunday) the month ends on.

Type:

int

property days_from_start_of_week_to_first_of_month: int

Leading blank cells before day 1 when the grid starts on Sunday.

index_in(years)

The position of this month within years, counting 12 months per year.

years must be a range in the same calendar_system.

Parameters:

years (range)

Return type:

int

to_nepali_month_calendar()

Narrow this month to the Bikram Sambat-only NepaliMonthCalendar.

The year and month are copied verbatim, so calling this on a CalendarSystem.GREGORIAN month produces a NepaliMonthCalendar holding Gregorian numbers. Convert the month to Bikram Sambat first when that matters.

Return type:

NepaliMonthCalendar

Locale

class NameFormat(value)

Bases: Enum

class NepaliDateFormatStyle(value)

Bases: Enum

class NepaliWeekdayName(short: str, medium: str, full: str)

Bases: object

Parameters:

• short (str)

• medium (str)

• full (str)

class NepaliMonthName(short: str, full: str)

Bases: object

Parameters:

• short (str)

• full (str)

class NepaliCalendarUtilsLang(value)

Bases: Enum

class NepaliDateLocale(language=NepaliCalendarUtilsLang.ENGLISH, date_format=NepaliDateFormatStyle.LONG, week_day_name=NameFormat.FULL, month_name=NameFormat.FULL, digit_script=None)

Bases: object

Locale settings for Nepali date display and formatting.

Parameters:

• language (NepaliCalendarUtilsLang)

• date_format (NepaliDateFormatStyle)

• week_day_name (NameFormat)

• month_name (NameFormat)

• digit_script (DigitScript | None)

language

Language for date-related text. Defaults to English.

Type:

nepali_calendar_utils.data.nepali_date_locale.NepaliCalendarUtilsLang

date_format

Style of date formatting. Defaults to LONG.

Type:

nepali_calendar_utils.data.nepali_date_locale.NepaliDateFormatStyle

week_day_name

Format for weekday names. Defaults to FULL.

Type:

nepali_calendar_utils.data.nepali_date_locale.NameFormat

month_name

Format for month names. Defaults to FULL.

Type:

nepali_calendar_utils.data.nepali_date_locale.NameFormat

digit_script

Explicit numeral script for digits. None (the default) means “follow the language”. Set this to render Nepali month names with Latin digits, or English month names with Devanagari digits.

Type:

nepali_calendar_utils.data.digit_script.DigitScript | None

property resolved_digit_script: DigitScript

Concrete digit script to render numerals with.

Returns digit_script when set explicitly, otherwise the language’s default (Devanagari for Nepali, Latin for English).

Digit scripts

Numeral-script utilities, decoupled from language.

Mirrors dev.shivathapaa.nepalidatepickerkmp.data.DigitScript from the Kotlin core. A DigitScript holds the ten code points for digits 0-9 in a given script, so any locale that shares the Devanagari digits (Nepali, Hindi, Marathi, Maithili, Bhojpuri, Newari) can reuse the same rendering.

class DigitScript(value)

Bases: Enum

Numeral script used when rendering digits in localized dates / times.

Each member’s value is the ten code points for digits 0..9 in that script. Use localize() to convert Latin-digit text to the chosen script, and to_latin_digits() to go the other way.

LATIN = ('0', '1', '2', '3', '4', '5', '6', '7', '8', '9')

ASCII 0123456789. Default for NepaliCalendarUtilsLang.ENGLISH.

DEVANAGARI = ('०', '१', '२', '३', '४', '५', '६', '७', '८', '९')

Devanagari ०१२३४५६७८९ (U+0966..U+096F). Default for NEPALI.

localize(text)

Map every ASCII digit in text to this script’s numeral, leaving all other characters untouched. LATIN is a no-op that returns the original string.

Parameters:

text (str)

Return type:

str

default_digit_script(lang)

Default DigitScript for a given NepaliCalendarUtilsLang.

Pass an explicit digit_script to NepaliDateLocale to override (e.g. show Nepali month names with Latin digits).

Return type:

DigitScript

latin_digit_or_none(char)

Reverse lookup for a single character.

If char is a digit in any supported non-Latin script (Devanagari today), return the matching ASCII '0'..'9'. If it is already an ASCII digit, return it unchanged. Otherwise return None.

Parameters:

char (str)

Return type:

str | None

to_latin_digits(text)

Inverse of DigitScript.localize().

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

Parameters:

text (str)

Return type:

str

Date formatter

Parse and format SimpleDate for short numeric text-field input.

Mirrors dev.shivathapaa.nepalidatepickerkmp.data.NepaliDateFormatter.

Use this when you have a raw YYYY/MM/DD-style string and need a SimpleDate (or vice versa). For locale-aware long-form output (“Asar 21, 2082”), use NepaliDateConverter.format_nepali_date(...) instead.

Supported patterns are limited on purpose - a free-form formatter DSL is out of scope; the constrained surface keeps masking and validation predictable.

class DatePattern(value)

Bases: Enum

Supported text-field input/output patterns.

Each member’s value is (literal, delimiter, year_first).

YYYY_SLASH_MM_SLASH_DD = ('YYYY/MM/DD', '/', True)

YYYY/MM/DD - e.g. 2082/02/14.

YYYY_DASH_MM_DASH_DD = ('YYYY-MM-DD', '-', True)

YYYY-MM-DD - ISO-like, e.g. 2082-02-14.

DD_SLASH_MM_SLASH_YYYY = ('DD/MM/YYYY', '/', False)

DD/MM/YYYY - day-first, e.g. 14/02/2082.

DD_DASH_MM_DASH_YYYY = ('DD-MM-YYYY', '-', False)

DD-MM-YYYY - day-first dashed, e.g. 14-02-2082.

property length: int

Total visible character count when the field is full (always 10).

property digit_count: int

Number of ASCII digit characters expected (always 8).

class NepaliDateFormatter

Bases: object

Formatter/parser primitive for short numeric date strings.

Pattern

Alias so callers can write NepaliDateFormatter.Pattern.YYYY_SLASH_MM_SLASH_DD.

alias of DatePattern

static format(date, pattern, script=DigitScript.LATIN)

Format date as a pattern.literal-shaped string with digits in script.

No range or selectable-date checks - pass any SimpleDate; the result will reflect it.

Parameters:

• date (SimpleDate)

• pattern (DatePattern)

• script (DigitScript)

Return type:

str

static parse(text, pattern)

Parse text as pattern. Accepts Latin and Devanagari digits.

Returns None when the length is wrong, a token is not numeric, a delimiter does not match, month is not in 1..12, or day is not in 1..32 (32 is allowed because some Bikram Sambat months have 32 days; tighter validation against the actual month length is the caller’s job).

Parameters:

• text (str)

• pattern (DatePattern)

Return type:

SimpleDate | None

Time formatter

Parse and format SimpleTime as the library’s canonical time-of-day wire string.

Mirrors dev.shivathapaa.nepalidatepickerkmp.data.NepaliTimeFormatter.

HH:mm:ss with an optional nine-digit fractional part. This is the shape a SimpleTime takes on the wire everywhere the sibling Kotlin library is published, so a payload written here reads on a Kotlin, Android, Swift or JavaScript client without any of them depending on kotlinx-serialization.

Times are always read as Asia/Kathmandu, the zone every SimpleTime in this library is anchored to. No zone offset is written or accepted.

For display output (12-hour clocks, Devanagari digits, locale-aware wording) use NepaliDateConverter.get_formatted_time_in_english, get_formatted_time_in_nepali, or NepaliDateConverter.format_time_by_unicode_pattern. This formatter is for persistence and transport, and is fixed to Latin digits and 24-hour form on purpose.

class NepaliTimeFormatter

Bases: object

Formatter and parser for the canonical time-of-day wire string.

static format(time)

Format time as HH:mm:ss, appending .nnnnnnnnn only when SimpleTime.nanosecond is non-zero, so whole-second payloads stay compact.

Examples: "09:30:00", "23:59:59.123456789", "00:00:00.000000007".

No range check, pass any SimpleTime and the result reflects it. A value outside the ranges parse() accepts will not round-trip.

Parameters:

time (SimpleTime)

Return type:

str

static parse(text)

Parse text as HH:mm:ss or HH:mm:ss.nnnnnnnnn, returning None when it is not a time this formatter would have produced.

Returns None when:

• the clock part does not hold exactly three :-separated fields,

• any field or the fractional part is not decimal digits,

• hour is outside 0..23, or minute or second is outside 0..59,

• the fractional part is outside 0..999999999.

The fractional part is read as a plain count of nanoseconds, so ".7" means seven nanoseconds, not seven tenths of a second. Round-tripping through format() returns the zero-padded nine-digit form.

Field widths are not enforced, so "9:30:00" parses as 09:30:00. Any Unicode decimal digit is accepted, so Devanagari input such as "०९:३०:००" reads the same as its Latin form, and the two may be mixed. format() always writes Latin digits. Leading and trailing whitespace is not trimmed, call str.strip() first when the input may carry any.

Parameters:

text (str)

Return type:

SimpleTime | None