django-nepkit 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

django_nepkit/widgets.py

@@ -1,72 +1,141 @@
 from django import forms
-from django.urls import reverse_lazy
+from django.urls import reverse, NoReverseMatch
+from nepali.datetime import nepalidate
+from django_nepkit.utils import BS_DATE_FORMAT
+
+from django_nepkit.conf import nepkit_settings
 
 
 def _append_css_class(attrs, class_name: str):
-    """
-    Django-idiomatic helper to append a CSS class without clobbering existing ones.
-    """
+    """Helper to add a CSS class safely."""
     existing = (attrs.get("class") or "").strip()
     attrs["class"] = (f"{existing} {class_name}").strip() if existing else class_name
     return attrs
 
 
-class ChainedSelectWidget(forms.Select):
-    class Media:
-        js = ("django_nepkit/js/address-chaining.js",)
+class NepaliWidgetMixin:
+    def __init__(self, *args, **kwargs):
+        default_lang = nepkit_settings.DEFAULT_LANGUAGE
+        self.ne = kwargs.pop("ne", default_lang == "ne")
 
+        self.en = kwargs.pop("en", not self.ne)
+        self.htmx = kwargs.pop("htmx", False)
+
+        attrs = kwargs.get("attrs", {}) or {}
+
+        # Language settings
+        if self.ne:
+            attrs["data-ne"] = "true"
+        if self.en:
+            attrs["data-en"] = "true"
+
+        # Pass the date format to JavaScript
+        attrs["data-format"] = BS_DATE_FORMAT
+
+        self._configure_attrs(attrs)
 
-class ProvinceSelectWidget(ChainedSelectWidget):
-    def __init__(self, *args, **kwargs):
-        attrs = kwargs.get("attrs", {})
-        _append_css_class(attrs, "nepkit-province-select")
         kwargs["attrs"] = attrs
         super().__init__(*args, **kwargs)
 
+    def _configure_attrs(self, attrs):
+        """Override in subclasses or use class attributes."""
+        css_class = getattr(self, "css_class", None)
+        if css_class:
+            _append_css_class(attrs, css_class)
+
+    def get_context(self, name, value, attrs):
+        context = super().get_context(name, value, attrs)
+        widget_attrs = context.get("widget", {}).get("attrs", {})
+
+        # Handle URLs for data fetching
+        url_name = getattr(self, "_url_name", None)
+        if url_name:
+            try:
+                widget_attrs["data-url"] = reverse(url_name)
+            except NoReverseMatch:
+                pass
+
+        # Handle HTMX dynamic updates
+        if self.htmx:
+            hx_url_name = getattr(self, "_hx_url_name", None)
+            if hx_url_name:
+                try:
+                    widget_attrs["hx-get"] = reverse(hx_url_name)
+                    widget_attrs["hx-target"] = getattr(self, "_hx_target", "")
+                    widget_attrs["hx-trigger"] = "change"
+                except NoReverseMatch:
+                    pass
+
+        return context
+
+
+class ChainedSelectWidget(forms.Select):
+    class Media:
+        js = (
+            "django_nepkit/js/nepal-data.js",
+            "django_nepkit/js/address-chaining.js",
+        )
+
+
+class ProvinceSelectWidget(NepaliWidgetMixin, ChainedSelectWidget):
+    css_class = "nepkit-province-select"
 
-class DistrictSelectWidget(ChainedSelectWidget):
     def __init__(self, *args, **kwargs):
-        attrs = kwargs.get("attrs", {})
-        _append_css_class(attrs, "nepkit-district-select")
-        attrs["data-url"] = reverse_lazy("django_nepkit:district-list")
-        kwargs["attrs"] = attrs
         super().__init__(*args, **kwargs)
+        if self.htmx:
+            self._hx_url_name = "django_nepkit:district-list"
+            self._hx_target = ".nepkit-district-select"
+
 
+class DistrictSelectWidget(NepaliWidgetMixin, ChainedSelectWidget):
+    css_class = "nepkit-district-select"
+    _url_name = "django_nepkit:district-list"
 
-class MunicipalitySelectWidget(ChainedSelectWidget):
     def __init__(self, *args, **kwargs):
-        attrs = kwargs.get("attrs", {})
-        _append_css_class(attrs, "nepkit-municipality-select")
-        attrs["data-url"] = reverse_lazy("django_nepkit:municipality-list")
-        kwargs["attrs"] = attrs
         super().__init__(*args, **kwargs)
+        if self.htmx:
+            self._hx_url_name = "django_nepkit:municipality-list"
+            self._hx_target = ".nepkit-municipality-select"
+
 
+class MunicipalitySelectWidget(NepaliWidgetMixin, ChainedSelectWidget):
+    css_class = "nepkit-municipality-select"
+    _url_name = "django_nepkit:municipality-list"
 
-class NepaliDatePickerWidget(forms.TextInput):
+
+class NepaliDatePickerWidget(NepaliWidgetMixin, forms.TextInput):
     input_type = "text"
 
     class Media:
         css = {
             "all": (
-                "https://unpkg.com/nepali-date-picker@2.0.2/dist/nepaliDatePicker.min.css",
+                "https://nepalidatepicker.sajanmaharjan.com.np/v5/nepali.datepicker/css/nepali.datepicker.v5.0.6.min.css",
             )
         }
         js = (
             "https://code.jquery.com/jquery-3.5.1.slim.min.js",
-            "https://unpkg.com/nepali-date-picker@2.0.2/dist/nepaliDatePicker.min.js",
+            "https://nepalidatepicker.sajanmaharjan.com.np/v5/nepali.datepicker/js/nepali.datepicker.v5.0.6.min.js",
             "django_nepkit/js/nepali-datepicker-init.js",
         )
 
-    def __init__(self, *args, **kwargs):
-        attrs = kwargs.get("attrs", {})
-        # Ensure we don't have vDateField class which triggers Django admin calendar
+    def _configure_attrs(self, attrs):
         classes = attrs.get("class", "")
         if "vDateField" in classes:
             classes = classes.replace("vDateField", "")
+        attrs["class"] = classes
 
-        attrs["class"] = (classes or "").strip()
         _append_css_class(attrs, "nepkit-datepicker")
         attrs["autocomplete"] = "off"
-        attrs["placeholder"] = "YYYY-MM-DD"
-        kwargs["attrs"] = attrs
-        super().__init__(*args, **kwargs)
+        attrs["placeholder"] = (
+            BS_DATE_FORMAT.replace("%Y", "YYYY").replace("%m", "MM").replace("%d", "DD")
+        )
+
+    def format_value(self, value):
+        if value is None:
+            return None
+
+        if self.ne and isinstance(value, nepalidate):
+            if hasattr(value, "strftime_ne"):
+                return value.strftime_ne(BS_DATE_FORMAT)
+
+        return super().format_value(value)

django_nepkit-0.2.1.dist-info/METADATA

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: django-nepkit
+Version: 0.2.1
+Summary: Django Nepali date, time, phone, and address fields with helpers.
+Home-page: https://github.com/S4NKALP/django-nepkit
+Author: Sankalp Tharu
+Author-email: Sankalp Tharu <sankalptharu50028@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/S4NKALP/django-nepkit
+Keywords: django,django-fields,django-forms,nepal,nepali,nepali-date,bikram-sambat,nepali-calendar,timezone,asia-kathmandu,phone-number,address,province,district,municipality
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.2
+Requires-Dist: django-filter>=25.2
+Requires-Dist: djangorestframework>=3.16.1
+Requires-Dist: nepali>=1.2.0
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == "drf"
+Requires-Dist: django-filter>=23.1; extra == "drf"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 🇳🇵 django-nepkit
+
+<div align="center">
+
+[![PyPI version](https://badge.fury.io/py/django-nepkit.svg)](https://badge.fury.io/py/django-nepkit)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-nepkit.svg)](https://pypi.org/project/django-nepkit/)
+[![Django Versions](https://img.shields.io/badge/Django-3.2%20%7C%204.2%20%7C%205.0%20%7C%206.0-blue.svg)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**A toolkit for handling BS dates, regional locations, and validation in the local context.**
+
+</div>
+
+Building software for local requirements comes with unique challenges, from handling BS dates to managing the regional administrative hierarchy. `django-nepkit` provides solutions for these requirements directly within the Django ecosystem.
+
+![Showcase](docs/showcase.gif)
+
+---
+
+## 🎯 Features
+
+- **📅 BS Date Support**: Model fields for `nepalidate` and `nepalidatetime` objects.
+- **🗺️ Regional Locations**: Pre-defined Provinces, Districts, and Municipalities.
+- **📱 Phone Validation**: Patterns for local mobile and landline numbers.
+- **💰 Currency Formatting**: `NepaliCurrencyField` with automatic Lakhs/Crores comma placement.
+- **🔤 Numbers to Words**: Convert digits into Nepali text representation.
+- **🔌 Admin Integration**: Automatic setup for datepickers and localized list displays.
+- **🚀 API Support**: DRF Serializers and Filtering backends for BS searching and ordering.
+- **⚡ Location Chaining**: Address linking via client side JS or server driven HTMX.
+- **🔍 Address Normalization**: Utility to extract structured locations from raw strings.
+
+---
+
+## 🛠 Setup
+
+Installation:
+
+```bash
+pip install django-nepkit
+```
+
+### 1. Basic Configuration
+
+Add it to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_nepkit",
+]
+```
+
+### 2. Global Control
+
+Configure behavior in your `settings.py`:
+
+```python
+NEPKIT = {
+    "DEFAULT_LANGUAGE": "en",           # "en" or "ne"
+    "ADMIN_DATEPICKER": True,           # Toggle the datepicker
+    "TIME_FORMAT": 12,                  # 12 or 24 hour display
+    "DATE_INPUT_FORMATS": ["%Y-%m-%d", "%d/%m/%Y", "%d-%m-%Y"], # Input formats
+}
+```
+
+---
+
+## 🚀 Core Usage
+
+### 1. Model Implementation
+
+Fields store `YYYY-MM-DD` strings for database stability while providing BS objects in Python.
+
+```python
+from django_nepkit import NepaliDateField, NepaliPhoneNumberField
+
+class Profile(models.Model):
+    name = models.CharField(max_length=100)
+    birth_date = NepaliDateField() # BS Date support
+    phone = NepaliPhoneNumberField() # Local pattern validation
+```
+
+### 2. Admin Integration
+
+Use `NepaliModelAdmin` for automatic formatting and datepicker support.
+
+```python
+from django_nepkit import NepaliModelAdmin, NepaliDateFilter
+
+@admin.register(Profile)
+class ProfileAdmin(NepaliModelAdmin):
+    list_display = ("name", "birth_date", "phone")
+    list_filter = (("birth_date", NepaliDateFilter),)
+```
+
+---
+
+## 🗺️ Address Management
+
+Manage the **Province → District → Municipality** hierarchy.
+
+### Client-Side Chaining (Standard)
+
+Cascading selects in the Django Admin without extra configuration.
+
+```python
+from django_nepkit import ProvinceField, DistrictField, MunicipalityField
+
+class Address(models.Model):
+    province = ProvinceField()
+    district = DistrictField()
+    municipality = MunicipalityField()
+
+### Address Normalization
+
+Standardize raw strings into structured location data (Province, District, Municipality).
+
+```python
+from django_nepkit.utils import normalize_address
+
+# Supports English or Nepali input
+result = normalize_address("House 123, Bharatpur, Chitwan")
+# Returns: {'province': 'Bagmati Province', 'district': 'Chitawan', 'municipality': 'Bharatpur Metropolitan City'}
+
+result_ne = normalize_address("विराटनगर, कोशी")
+# Returns: {'province': 'कोशी प्रदेश', 'district': 'मोरङ', 'municipality': 'विराटनगर महानगरपालिका'}
+```
+```
+
+### Server Side Chaining (HTMX)
+
+Enable `htmx=True` for a server driven experience.
+
+> [!IMPORTANT]
+> **HTMX Setup:**
+> Include the required URLs in your main `urls.py`:
+>
+> ```python
+> path("nepkit/", include("django_nepkit.urls")),
+> ```
+
+---
+
+## 🔌 API & DRF Support
+
+Search and ordering work natively. BS year/month filtering is supported.
+
+```python
+from django_nepkit.filters import NepaliDateYearFilter
+
+class ProfileFilter(filters.FilterSet):
+    # Filter by BS Year (e.g., /api/profiles/?year=2081)
+    year = NepaliDateYearFilter(field_name="birth_date")
+```
+
+---
+
+## 💰 Formatting & Helpers
+
+### 1. Currency & Numbers
+Use `NepaliCurrencyField` for automatic formatting in the admin and templates.
+
+```python
+from django_nepkit import NepaliCurrencyField
+
+class Transaction(models.Model):
+    amount = NepaliCurrencyField() # Defaults to 19 digits, 2 decimals
+```
+
+### 2. Template Filters
+Load the tags to use localized formatting in your templates.
+
+```html
+{% load nepali %}
+
+<!-- Comma formatting: Rs. 1,12,000.00 -->
+<p>{{ 112000 | nepali_currency }}</p>
+
+<!-- Numbers to Words: एक सय तेईस -->
+<p>{{ 123 | nepali_words }}</p>
+
+<!-- English to Nepali Digits: १२३ -->
+<p>{{ "123" | nepali_unicode }}</p>
+```
+
+---
+
+## 🕒 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.

django_nepkit-0.2.1.dist-info/RECORD

@@ -0,0 +1,37 @@
+django_nepkit/__init__.py,sha256=20cQUKdAjNtQYkAJU0g4OSJa90Ru3M9reNfV0ZgG3vc,1164
+django_nepkit/admin.py,sha256=xqQHybYb9T4_NYvCqDV3VYt0tbwWQDc8dwTOrkBmj0Q,12714
+django_nepkit/conf.py,sha256=urr8gwBj2YZgL2Po_C7339YafoQ_PMOWb1MEh-vPdfs,981
+django_nepkit/constants.py,sha256=cVq-ZFkDCBwETU2IDEtAMz2H-oLzSw8TtncRm954Jlg,3507
+django_nepkit/filters.py,sha256=dw5Yej9cLI-cZxlVHSaNUHq63hnnzhkjqmgLPTvbpd8,3939
+django_nepkit/forms.py,sha256=yrRE1gzkxGyqrAl0ETcOWnNsTyhPxlS_nlq4ex5a3UY,1675
+django_nepkit/lang_utils.py,sha256=OY0EdWCHL3pVz4rLijCPv1qs8DMVK8ypL4sv8Dw4w3w,1264
+django_nepkit/models.py,sha256=_u1Y0_q9liReodkDHl-kt8D9b_HxP_GwJo2koLRNBWg,8406
+django_nepkit/serializers.py,sha256=P8dTLOLEaGpc2OuetGXh9LZnbwF1l4VBWQU7y5hwWPA,6487
+django_nepkit/urls.py,sha256=mPF_xEaOqNrInggBhUbwwMq-FTR7rJ0CfT0fQPx41t8,297
+django_nepkit/utils.py,sha256=md3VpScslatEqtaIHo1_kbwvmlVPO45G_Qoikd_oFsE,9106
+django_nepkit/validators.py,sha256=HGd4PwXY7vLh8j2r2pnAHM-rfwVWCa4UDfuW79JYxJ8,407
+django_nepkit/views.py,sha256=u0Hv343omi51pPF0jOLbwBn9cFkDK-Svt9aXtDrHCxM,3864
+django_nepkit/widgets.py,sha256=36Q5kkEn4FuFw--CiAOBrp2mzYSaknCmoLpTFFEDgYU,4588
+django_nepkit/static/django_nepkit/css/admin-nepali-datepicker.css,sha256=g9ago3O0UfoNwRD02AmWSdxiHmXxkQ7mpi94Nn1rO3E,834
+django_nepkit/static/django_nepkit/js/address-chaining.js,sha256=-_eSgL38nc2XUvKv-Ns7cOQyTxra_roRb0z1R0sBKN0,6503
+django_nepkit/static/django_nepkit/js/admin-jquery-bridge.js,sha256=6iqIuSqgYssKtt61WSjye3GBpYHh3AKKYUtGL6Uh3S8,319
+django_nepkit/static/django_nepkit/js/nepal-data.js,sha256=llFe3CAloAoUU505dnNpKgS9Qhqp0-hmZdLbkBDZkz4,168476
+django_nepkit/static/django_nepkit/js/nepali-datepicker-init.js,sha256=b1X15_AAyw5DzHHArGjpF9BFA4RM5IVw9CgzAmPAf40,4356
+django_nepkit-0.2.1.dist-info/licenses/LICENSE,sha256=76985cvIL0AXuhZd5L2C9tbdxKMZX7IOejjvZI8kXMo,1070
+example/manage.py,sha256=wZWUpuXgYEHBxZR-sysETawIaMhr83HQglQTeZdadpQ,752
+example/demo/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+example/demo/admin.py,sha256=pNlA7_GlDpNQRIb7VoTEO1fa0JD-EwLA6VK72aQR504,1635
+example/demo/apps.py,sha256=sXxYSi4dEGg-HDkM7C-TfLv26KbSUj-8HTeFS86pW8w,83
+example/demo/models.py,sha256=zZhoFfYK3zCEapOvVgxbs2bS-OKD3kuFUFvrRDaL_-Y,1854
+example/demo/serializers.py,sha256=V07_sXGPPicCJc1RMecd0jQFvldFPaHpjJuSArj5M7U,1034
+example/demo/tests.py,sha256=qWDvA9ZhVCQ1rPbkoFify7o_fDirXMUdYMxF12q3WIM,26
+example/demo/urls.py,sha256=0zB7KRRTE7HHDnTbE5yibpH9eyJhBekNguj_nuY_gcE,786
+example/demo/views.py,sha256=ow6hQwnhTD1KjEkM4R7qRcuHcnJJ4pOXsU-JRH0Ocn4,4380
+example/example_project/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+example/example_project/settings.py,sha256=nq5lGLEY1cl99XhfS60BpIVfhVFzUhHb_qfNPm5TqSY,2334
+example/example_project/urls.py,sha256=AK8SdvMN2K0QvdzhMr5BUMzl0SrEUhVmMP-3uLEqnU4,217
+example/example_project/wsgi.py,sha256=OK4x37NxQNVNWV4ynLqWP546tR4eALIFn7pyHc8XDNw,176
+django_nepkit-0.2.1.dist-info/METADATA,sha256=4FIFav_TWnqaPd-AY5Zsp3lZ0uI1b0ZFZIishqIrsqM,11008
+django_nepkit-0.2.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+django_nepkit-0.2.1.dist-info/top_level.txt,sha256=Rs68WqPeyCvsWQStPNLl6vu10wCIfrFrc7xhkRcFzss,22
+django_nepkit-0.2.1.dist-info/RECORD,,

example/demo/admin.py

@@ -1,42 +1,66 @@
 from django.contrib import admin
 
-from django_nepkit import NepaliModelAdmin
+from django_nepkit import (
+    NepaliModelAdmin,
+    NepaliAdminMixin,
+    NepaliDateFilter,
+    NepaliMonthFilter,
+)
 
-from .models import Person
+from .models import Person, Citizen, AuditedPerson, Transaction
 
 
+# Example 1: Basic setup
 @admin.register(Person)
 class PersonAdmin(NepaliModelAdmin):
     list_display = (
         "name",
-        "display_birth_date",
+        "birth_date",
+        "birth_date_ne",
         "phone_number",
         "province",
+        "province_ne",
         "district",
+        "district_ne",
         "municipality",
-        "display_created_at",
-        "display_updated_at",
+        "municipality_ne",
+        "created_at",
+        "updated_at",
+    )
+    # Added Year and Month filters
+    list_filter = (
+        ("birth_date", NepaliDateFilter),
+        ("birth_date", NepaliMonthFilter),
+        "province",
     )
-    list_filter = ("birth_date", "province", "district")
     search_fields = ("name", "phone_number")
 
-    def display_birth_date(self, obj):
-        """Display birth date with Nepali month names"""
-        return self.format_nepali_date(obj.birth_date)
 
-    display_birth_date.short_description = "Birth Date"
-    display_birth_date.admin_order_field = "birth_date"
+# Example 2: Using a Mixin
+class BaseAuditAdmin(admin.ModelAdmin):
+    """A fake base class for testing."""
+
+    pass
+
+
+# Use the Mixin if you already have a base Admin class
+@admin.register(AuditedPerson)
+class CustomPersonAdmin(NepaliAdminMixin, BaseAuditAdmin):
+    list_display = ("name", "birth_date", "created_at")
+    list_filter = (
+        ("created_at", NepaliMonthFilter),  # Filter by Nepali Month
+    )
 
-    def display_created_at(self, obj):
-        """Display created date with Nepali month names"""
-        return self.format_nepali_datetime(obj.created_at)
 
-    display_created_at.short_description = "Created At"
-    display_created_at.admin_order_field = "created_at"
+# Example 3: HTMX support
+@admin.register(Citizen)
+class CitizenAdmin(NepaliModelAdmin):
+    list_display = ("name", "province", "district", "municipality")
+    # Filters still work with HTMX
+    list_filter = ("province", "district")
 
-    def display_updated_at(self, obj):
-        """Display updated date with Nepali month names"""
-        return self.format_nepali_datetime(obj.updated_at)
 
-    display_updated_at.short_description = "Updated At"
-    display_updated_at.admin_order_field = "updated_at"
+@admin.register(Transaction)
+class TransactionAdmin(NepaliModelAdmin):
+    list_display = ("title", "amount", "date")
+    list_filter = (("date", NepaliDateFilter),)

example/demo/models.py

@@ -7,21 +7,58 @@ from django_nepkit import (
     ProvinceField,
     DistrictField,
     MunicipalityField,
+    NepaliCurrencyField,
 )
 
 
 class Person(models.Model):
     name = models.CharField(max_length=100)
-    birth_date = NepaliDateField()
-    registration_time = NepaliTimeField(auto_now_add=True)
+    # Dates and times
+    birth_date = NepaliDateField()  # English by default
+    birth_date_ne = NepaliDateField(ne=True, blank=True, null=True)  # Using Devanagari
+    registration_time = NepaliTimeField(auto_now_add=True)  # English digits by default
     phone_number = NepaliPhoneNumberField()
 
-    # Address chaining
-    province = ProvinceField()
+    # Location fields
+    province = ProvinceField()  # English names by default
+    province_ne = ProvinceField(ne=True, blank=True, null=True)  # In Devanagari
     district = DistrictField()
+    district_ne = DistrictField(ne=True, blank=True, null=True)
     municipality = MunicipalityField()
+    municipality_ne = MunicipalityField(ne=True, blank=True, null=True)
+
     created_at = NepaliDateTimeField(auto_now_add=True)
     updated_at = NepaliDateTimeField(auto_now=True)
 
     def __str__(self):
         return self.name
+
+
+class Citizen(models.Model):
+    name = models.CharField(max_length=100)
+
+    # Chaining works automatically
+    province = ProvinceField()
+    district = DistrictField()
+    municipality = MunicipalityField()
+
+    def __str__(self):
+        return self.name
+
+
+class AuditedPerson(models.Model):
+    name = models.CharField(max_length=100)
+    birth_date = NepaliDateField()
+    created_at = NepaliDateTimeField(auto_now_add=True)
+
+    def __str__(self):
+        return self.name
+
+
+class Transaction(models.Model):
+    title = models.CharField(max_length=100)
+    amount = NepaliCurrencyField()
+    date = NepaliDateField(auto_now_add=True)
+
+    def __str__(self):
+        return f"{self.title} - {self.amount}"