# π³π΅ django-nepkit
{{ 112000 | nepali_currency }}
{{ 123 | nepali_words }}
{{ "123" | nepali_unicode }}
``` --- ## π Technical Design This library is engineered for performance, data integrity, and local compliance. ### 1. The "Source of Truth" Strategy We avoid on-the-fly `AD to BS` conversion during database queries because it is computationally expensive and prone to logical drift (due to lunar calendar offsets). - **Storage**: All BS dates are stored as `VARCHAR(10)` in `YYYY-MM-DD` format. - **Sorting**: Because `YYYY` is at the start, string based database sorting (ascending/descending) accurately matches chronological order. - **Indexability**: Standard B-Tree indexes work perfectly on these fields without requiring custom database functions. - **Timezone Safety**: Dates are stored without time components, making them immune to server side timezone shifts during saving. ### 2. Python Object Mapping While data is stored as strings, it is automatically hydrated into rich Python objects. - **`nepali-datetime` Integration**: Values are cast to `nepalidate` or `nepalidatetime` objects when retrieved from the database. - **Validation**: Fields use specialized validators (e.g., `validate_nepali_phone_number`) that leverage official regional patterns. ### 3. Frontend Architecture - **Automatic Initialization**: The library includes a lightweight JS observer that automatically initializes the datepicker for any field with the `.nepkit-datepicker` class. - **Theme Support**: The datepicker dynamically adapts its skin based on the Django Admin's dark/light mode state. --- ## β FAQ **Q: How do I handle Null or Optional dates?** Just like standard Django fields, pass `null=True, blank=True` to any `django-nepkit` field. The library handles empty strings and `None` values gracefully. **Q: Can I change the database storage format?** No. The `YYYY-MM-DD` format is hardcoded to ensure database level sorting and indexing work consistently. However, you can change the **display** format via global settings or template filters. **Q: Can I use Devanagari output?** Yes. Pass `ne=True` to fields, forms, or serializers. **Q: Can I display the datepicker in English?** Yes. By default, if you pass `en=True` (or if `DEFAULT_LANGUAGE` is set to `"en"`), the datepicker will display month and day names in English instead of Devanagari script. ```python birth_date = NepaliDateField(en=True) # English month/day names in picker ``` **Q: Is the location data up to date?** Yes. Province, District, and Municipality data is sourced from the `nepali` Python package, which is regularly updated to reflect administrative changes in Nepal. **Q: Does it work with standard Django Forms?** Yes. `NepaliDateField` uses a specialized `NepaliDateFormField` that automatically handles input parsing and error reporting. **Q: How do I migrate existing English (AD) dates to BS?** We recommend staying on standard `DateField` for AD data. If you must convert to BS, use our [Migration Script](docs/migration_guide.py) to perform a bulk data transformation safely. **Q: Why use VARCHAR instead of a native DateField?** Native `DateField` in most SQL engines is locked to the Gregorian calendar. Using `VARCHAR` allows us to treat the BS date as the primary data point, avoiding the "off-by-one" conversion errors common when syncing two disparate calendars. --- ## π€ Community We welcome contributions and feedback from the community. 1. **Clone**: `git clone https://github.com/S4NKALP/django-nepkit` 2. **Setup**: `uv sync` 3. **Test**: `uv run pytest` --- ## π Credits This library is built on top of excellent open source projects: - **[nepali](https://github.com/opensource-nepal/py-nepali)** by [@opensource-nepal](https://github.com/opensource-nepal) - Provides the core `nepalidate`, `nepalidatetime` objects and regional location data (Provinces, Districts, Municipalities). - **[Nepali Datepicker](https://nepalidatepicker.sajanmaharjan.com.np/)** by [Sajan Maharjan](https://github.com/sajanm/nepali-date-picker) - Powers the beautiful BS date picker widget in the Django Admin. --- MIT License. Designed for the local Django ecosystem.