django-nepkit 0.1.0__py3-none-any.whl

django_nepkit/__init__.py

@@ -0,0 +1,31 @@
+from .models import (
+    NepaliDateField,
+    NepaliTimeField,
+    NepaliDateTimeField,
+    NepaliPhoneNumberField,
+    ProvinceField,
+    DistrictField,
+    MunicipalityField,
+)
+from .admin import (
+    NepaliDateFilter,
+    format_nepali_date,
+    format_nepali_datetime,
+    NepaliModelAdmin,
+    NepaliAdminMixin,
+)
+
+__all__ = [
+    "NepaliDateField",
+    "NepaliTimeField",
+    "NepaliDateTimeField",
+    "NepaliPhoneNumberField",
+    "ProvinceField",
+    "DistrictField",
+    "MunicipalityField",
+    "NepaliDateFilter",
+    "format_nepali_date",
+    "format_nepali_datetime",
+    "NepaliModelAdmin",
+    "NepaliAdminMixin",
+]

django_nepkit/admin.py

@@ -0,0 +1,211 @@
+from django.contrib import admin
+from django.utils.translation import gettext_lazy as _
+from nepali.datetime import nepalidate, nepalidatetime
+
+from django_nepkit.models import NepaliDateField
+from django_nepkit.utils import (
+    try_parse_nepali_date,
+    try_parse_nepali_datetime,
+)
+
+
+def format_nepali_date(date_value, format_string="%B %d, %Y"):
+    """
+    Format a nepalidate object with Nepali month names.
+
+    Args:
+        date_value: A nepalidate object or string in YYYY-MM-DD format
+        format_string: strftime format string (default: '%B %d, %Y')
+                      %B = Full month name (Baishak, Jestha, etc.)
+                      %b = Short month name
+                      %d = Day of month
+                      %Y = Year
+
+    Returns:
+        Formatted date string with Nepali month names, or empty string if invalid
+    """
+    if date_value is None:
+        return ""
+
+    try:
+        parsed = try_parse_nepali_date(date_value)
+        if parsed is not None:
+            return parsed.strftime(format_string)
+        if isinstance(date_value, nepalidate):
+            return date_value.strftime(
+                format_string
+            )  # defensive; should be covered above
+    except (ValueError, TypeError, AttributeError):
+        pass
+
+    return str(date_value) if date_value else ""
+
+
+def format_nepali_datetime(datetime_value, format_string="%B %d, %Y %I:%M %p"):
+    """
+    Format a nepalidatetime object with Nepali month names.
+
+    Default output uses **12-hour time with AM/PM**.
+    """
+    if datetime_value is None:
+        return ""
+
+    try:
+        parsed = try_parse_nepali_datetime(datetime_value)
+        if parsed is not None:
+            return parsed.strftime(format_string)
+        if isinstance(datetime_value, nepalidatetime):
+            return datetime_value.strftime(
+                format_string
+            )  # defensive; should be covered above
+    except (ValueError, TypeError, AttributeError):
+        pass
+
+    return str(datetime_value) if datetime_value else ""
+
+
+class NepaliDateFilter(admin.FieldListFilter):
+    """
+    A list filter for NepaliDateField to filter by BS Year.
+    """
+
+    def __init__(self, field, request, params, model, model_admin, field_path):
+        self.parameter_name = f"{field_path}_bs_year"
+        super().__init__(field, request, params, model, model_admin, field_path)
+        self.title = _("Nepali Date (Year)")
+
+    def expected_parameters(self):
+        return [self.parameter_name]
+
+    def choices(self, changelist):
+        yield {
+            "selected": self.used_parameters.get(self.parameter_name) is None,
+            "query_string": changelist.get_query_string(remove=[self.parameter_name]),
+            "display": _("All"),
+        }
+        current_year = nepalidate.today().year
+        for year in range(current_year - 10, current_year + 2):
+            yield {
+                "selected": self.used_parameters.get(self.parameter_name) == str(year),
+                "query_string": changelist.get_query_string(
+                    {self.parameter_name: str(year)}
+                ),
+                "display": str(year),
+            }
+
+    def queryset(self, request, queryset):
+        value = self.used_parameters.get(self.parameter_name)
+        if value:
+            year = int(value)
+            # Convert BS year range to AD date range
+            start_date_bs = nepalidate(year, 1, 1)
+            # Find last day of the year. Some BS years end on the 30th,
+            # so we try 31 first and then fall back to 30 if that date
+            # is not valid.
+            try:
+                end_date_bs = nepalidate(year, 12, 31)
+            except ValueError:
+                end_date_bs = nepalidate(year, 12, 30)
+
+            start_date_ad = start_date_bs.to_date()
+            end_date_ad = end_date_bs.to_date()
+
+            return queryset.filter(
+                **{f"{self.field_path}__range": (start_date_ad, end_date_ad)}
+            )
+        return queryset
+
+
+# Register NepaliDateFilter as the default list filter for NepaliDateField
+admin.FieldListFilter.register(
+    lambda f: isinstance(f, NepaliDateField),
+    NepaliDateFilter,
+    take_priority=True,
+)
+
+
+class NepaliAdminMixin:
+    """
+    Mixin for Django admin classes that provides Nepali date utilities.
+    Makes format_nepali_date and NepaliDateFilter available without explicit imports.
+    """
+
+    def format_nepali_date(self, date_value, format_string="%B %d, %Y"):
+        """
+        Format a nepalidate object with Nepali month names.
+        Available as a method on admin classes using this mixin.
+        """
+        return format_nepali_date(date_value, format_string)
+
+    def format_nepali_datetime(
+        self, datetime_value, format_string="%B %d, %Y %I:%M %p"
+    ):
+        return format_nepali_datetime(datetime_value, format_string)
+
+
+class NepaliModelAdmin(NepaliAdminMixin, admin.ModelAdmin):
+    """
+    Base ModelAdmin class with Nepali date utilities built-in.
+    Use this instead of admin.ModelAdmin to have format_nepali_date available.
+
+    Example:
+        from django_nepkit import NepaliModelAdmin, NepaliDateFilter
+
+        @admin.register(MyModel)
+        class MyModelAdmin(NepaliModelAdmin):
+            list_filter = (('date_field', NepaliDateFilter),)
+
+            def display_date(self, obj):
+                return self.format_nepali_date(obj.date_field)
+    """
+
+    # Make NepaliDateFilter available as a class attribute
+    NepaliDateFilter = NepaliDateFilter
+
+    # Ensure admin forms render Nepali fields with the proper widget,
+    # even if a project doesn't provide custom ModelForms.
+    def formfield_for_dbfield(self, db_field, request, **kwargs):
+        """
+        Force Nepali widgets in Django admin without requiring user forms.
+        """
+        try:
+            from django_nepkit.models import NepaliDateField, NepaliDateTimeField
+            from django_nepkit.widgets import NepaliDatePickerWidget
+        except Exception:
+            return super().formfield_for_dbfield(db_field, request, **kwargs)
+
+        if isinstance(db_field, (NepaliDateField, NepaliDateTimeField)):
+            kwargs.setdefault("widget", NepaliDatePickerWidget)
+
+        return super().formfield_for_dbfield(db_field, request, **kwargs)
+
+    class Media:
+        """
+        Django admin ships jQuery as `django.jQuery` (not `window.jQuery`).
+        The Nepali date picker library expects a global `jQuery`, so we bridge it.
+        """
+
+        css = {
+            "all": (
+                "https://nepalidatepicker.sajanmaharjan.com.np/v5/nepali.datepicker/css/nepali.datepicker.v5.0.6.min.css",
+                "django_nepkit/css/admin-nepali-datepicker.css",
+            )
+        }
+        js = (
+            # Bridge admin's `django.jQuery` -> `window.jQuery`
+            "django_nepkit/js/admin-jquery-bridge.js",
+            # Date picker lib
+            "https://nepalidatepicker.sajanmaharjan.com.np/v5/nepali.datepicker/js/nepali.datepicker.v5.0.6.min.js",
+            # Init
+            "django_nepkit/js/nepali-datepicker-init.js",
+        )
+
+
+# Exporting for easy usage
+__all__ = [
+    "NepaliDateFilter",
+    "format_nepali_date",
+    "format_nepali_datetime",
+    "NepaliAdminMixin",
+    "NepaliModelAdmin",
+]

django_nepkit/forms.py

@@ -0,0 +1,50 @@
+from datetime import date as python_date
+
+from django import forms
+from django.utils.translation import gettext_lazy as _
+from nepali.datetime import nepalidate
+
+from django_nepkit.utils import try_parse_nepali_date
+from django_nepkit.validators import validate_nepali_phone_number
+
+
+class NepaliDateFormField(forms.DateField):
+    """
+    A Django Form Field for Nepali Date (Bikram Sambat).
+    """
+
+    from .widgets import NepaliDatePickerWidget
+
+    widget = NepaliDatePickerWidget
+
+    def __init__(self, *args, **kwargs):
+        kwargs.pop("max_length", None)
+        super().__init__(*args, **kwargs)
+
+    def to_python(self, value):
+        if value in self.empty_values:
+            return None
+        if isinstance(value, nepalidate):
+            return value
+        if isinstance(value, python_date):
+            return nepalidate.from_date(value)
+        try:
+            parsed = try_parse_nepali_date(str(value))
+            if parsed is not None:
+                return parsed
+            raise ValueError("Invalid BS date format")
+        except Exception:
+            raise forms.ValidationError(
+                _("Enter a valid Nepali date in YYYY-MM-DD format."),
+                code="invalid",
+            )
+
+
+class NepaliPhoneNumberFormField(forms.CharField):
+    """
+    A Django Form Field for Nepali Phone Numbers.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.validators.append(validate_nepali_phone_number)

django_nepkit/models.py

@@ -0,0 +1,269 @@
+from datetime import date as python_date
+
+from django.db import models
+from django.utils.translation import gettext_lazy as _
+from nepali.datetime import nepalidate, nepalidatetime
+
+from django_nepkit.utils import (
+    BS_DATE_FORMAT,
+    BS_DATETIME_FORMAT,
+    try_parse_nepali_date,
+    try_parse_nepali_datetime,
+)
+from django_nepkit.validators import validate_nepali_phone_number
+
+
+class NepaliPhoneNumberField(models.CharField):
+    description = _("Nepali Phone Number")
+
+    def __init__(self, *args, **kwargs):
+        kwargs.setdefault("max_length", 10)
+        super().__init__(*args, **kwargs)
+        self.validators.append(validate_nepali_phone_number)
+
+
+class NepaliDateField(models.CharField):
+    """
+    A Django Model Field that stores Nepali (Bikram Sambat) Date.
+    Internally it stores the date as BS string (YYYY-MM-DD) in the database.
+    """
+
+    description = _("Nepali Date (Bikram Sambat)")
+
+    def __init__(self, *args, **kwargs):
+        self.auto_now = kwargs.pop("auto_now", False)
+        self.auto_now_add = kwargs.pop("auto_now_add", False)
+
+        # Match Django's DateField behavior
+        if self.auto_now or self.auto_now_add:
+            kwargs.setdefault("editable", False)
+            kwargs.setdefault("blank", True)
+
+        kwargs.setdefault("max_length", 10)
+        super().__init__(*args, **kwargs)
+
+    def pre_save(self, model_instance, add):
+        if self.auto_now or (self.auto_now_add and add):
+            # Using nepalidate.today() to get current BS date.
+            # This is BS-native as much as possible.
+            value = nepalidate.today().strftime(BS_DATE_FORMAT)
+            setattr(model_instance, self.attname, value)
+            return value
+        return super().pre_save(model_instance, add)
+
+    def from_db_value(self, value, expression, connection):
+        parsed = try_parse_nepali_date(value)
+        return parsed if parsed is not None else value
+
+    def to_python(self, value):
+        if value is None or isinstance(value, nepalidate):
+            return value
+        if isinstance(value, python_date):
+            # If we MUST handle AD date object, we convert it to BS.
+            # But we should prefer strings or nepalidate.
+            try:
+                return nepalidate.from_date(value)
+            except (ValueError, TypeError):
+                return str(value)
+        if isinstance(value, str):
+            parsed = try_parse_nepali_date(value)
+            return parsed if parsed is not None else value
+        return super().to_python(value)
+
+    def validate(self, value, model_instance):
+        if isinstance(value, nepalidate):
+            value = value.strftime(BS_DATE_FORMAT)
+        super().validate(value, model_instance)
+
+    def run_validators(self, value):
+        if isinstance(value, nepalidate):
+            value = value.strftime(BS_DATE_FORMAT)
+        super().run_validators(value)
+
+    def get_prep_value(self, value):
+        if value is None:
+            return value
+        if isinstance(value, nepalidate):
+            return value.strftime(BS_DATE_FORMAT)
+        if isinstance(value, python_date):
+            try:
+                return nepalidate.from_date(value).strftime(BS_DATE_FORMAT)
+            except (ValueError, TypeError):
+                return str(value)
+        if isinstance(value, str):
+            return value
+        # Fallback: convert to string
+        return str(value)
+
+    def deconstruct(self):
+        name, path, args, kwargs = super().deconstruct()
+        if self.auto_now:
+            kwargs["auto_now"] = True
+        if self.auto_now_add:
+            kwargs["auto_now_add"] = True
+        return name, path, args, kwargs
+
+    def formfield(self, **kwargs):
+        from .forms import NepaliDateFormField
+        from .widgets import NepaliDatePickerWidget
+
+        defaults = {
+            "form_class": NepaliDateFormField,
+            "widget": NepaliDatePickerWidget,
+        }
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+
+class NepaliTimeField(models.TimeField):
+    """
+    A Django Model Field for Time with Nepali localization support.
+    Supports auto_now and auto_now_add like standard Django TimeField.
+    """
+
+    description = _("Nepali Time")
+
+
+class NepaliDateTimeField(models.CharField):
+    """
+    A Django Model Field that stores Nepali (Bikram Sambat) DateTime.
+    Internally it stores the datetime as BS string (YYYY-MM-DD HH:MM:SS) in the database.
+    """
+
+    description = _("Nepali DateTime (Bikram Sambat)")
+
+    def __init__(self, *args, **kwargs):
+        self.auto_now = kwargs.pop("auto_now", False)
+        self.auto_now_add = kwargs.pop("auto_now_add", False)
+
+        # Match Django's DateTimeField behavior
+        if self.auto_now or self.auto_now_add:
+            kwargs.setdefault("editable", False)
+            kwargs.setdefault("blank", True)
+
+        kwargs.setdefault("max_length", 19)  # YYYY-MM-DD HH:MM:SS
+        super().__init__(*args, **kwargs)
+
+    def pre_save(self, model_instance, add):
+        if self.auto_now or (self.auto_now_add and add):
+            # Using nepalidatetime.now() to get current BS datetime
+            value = nepalidatetime.now().strftime(BS_DATETIME_FORMAT)
+            setattr(model_instance, self.attname, value)
+            return value
+        return super().pre_save(model_instance, add)
+
+    def from_db_value(self, value, expression, connection):
+        parsed = try_parse_nepali_datetime(value)
+        return parsed if parsed is not None else value
+
+    def to_python(self, value):
+        if value is None or isinstance(value, nepalidatetime):
+            return value
+        if isinstance(value, str):
+            parsed = try_parse_nepali_datetime(value)
+            return parsed if parsed is not None else value
+        return super().to_python(value)
+
+    def validate(self, value, model_instance):
+        if isinstance(value, nepalidatetime):
+            value = value.strftime(BS_DATETIME_FORMAT)
+        super().validate(value, model_instance)
+
+    def run_validators(self, value):
+        if isinstance(value, nepalidatetime):
+            value = value.strftime(BS_DATETIME_FORMAT)
+        super().run_validators(value)
+
+    def get_prep_value(self, value):
+        if value is None:
+            return value
+        if isinstance(value, nepalidatetime):
+            return value.strftime(BS_DATETIME_FORMAT)
+        if isinstance(value, str):
+            return value
+        # Fallback: convert to string
+        return str(value)
+
+    def deconstruct(self):
+        name, path, args, kwargs = super().deconstruct()
+        if self.auto_now:
+            kwargs["auto_now"] = True
+        if self.auto_now_add:
+            kwargs["auto_now_add"] = True
+        return name, path, args, kwargs
+
+    def formfield(self, **kwargs):
+        from .widgets import NepaliDatePickerWidget
+
+        defaults = {
+            "widget": NepaliDatePickerWidget,
+        }
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+
+class ProvinceField(models.CharField):
+    """
+    A Django Model Field for Nepali Provinces.
+    """
+
+    description = _("Nepali Province")
+
+    def __init__(self, *args, **kwargs):
+        from nepali.locations import provinces
+
+        kwargs.setdefault("max_length", 100)
+        kwargs.setdefault("choices", [(p.name, p.name) for p in provinces])
+        super().__init__(*args, **kwargs)
+
+    def formfield(self, **kwargs):
+        from .widgets import ProvinceSelectWidget
+
+        defaults = {"widget": ProvinceSelectWidget}
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+
+class DistrictField(models.CharField):
+    """
+    A Django Model Field for Nepali Districts.
+    """
+
+    description = _("Nepali District")
+
+    def __init__(self, *args, **kwargs):
+        from nepali.locations import districts
+
+        kwargs.setdefault("max_length", 100)
+        kwargs.setdefault("choices", [(d.name, d.name) for d in districts])
+        super().__init__(*args, **kwargs)
+
+    def formfield(self, **kwargs):
+        from .widgets import DistrictSelectWidget
+
+        defaults = {"widget": DistrictSelectWidget}
+        defaults.update(kwargs)
+        return super().formfield(**defaults)
+
+
+class MunicipalityField(models.CharField):
+    """
+    A Django Model Field for Nepali Municipalities.
+    Includes Metropolitan, Sub-Metropolitan, Municipality, and Rural Municipality.
+    """
+
+    description = _("Nepali Municipality")
+
+    def __init__(self, *args, **kwargs):
+        from nepali.locations import municipalities
+
+        kwargs.setdefault("max_length", 100)
+        kwargs.setdefault("choices", [(m.name, m.name) for m in municipalities])
+        super().__init__(*args, **kwargs)
+
+    def formfield(self, **kwargs):
+        from .widgets import MunicipalitySelectWidget
+
+        defaults = {"widget": MunicipalitySelectWidget}
+        defaults.update(kwargs)
+        return super().formfield(**defaults)

django_nepkit/serializers.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+from nepali.datetime import nepalidate, nepalidatetime
+
+try:
+    from rest_framework import serializers
+except ModuleNotFoundError as e:
+    raise ModuleNotFoundError(
+        "django-nepkit DRF support is optional. Install with `django-nepkit[drf]` "
+        "to use `django_nepkit.serializers`."
+    ) from e
+
+from django_nepkit.utils import try_parse_nepali_date, try_parse_nepali_datetime
+
+# --------------------------------------------------
+# Base Serializer Field
+# --------------------------------------------------
+
+
+class BaseNepaliBSField(serializers.Field):
+    """
+    Base DRF field for Nepali (BS) Date / DateTime.
+
+    - **Input**: BS string, or an already-parsed `nepalidate`/`nepalidatetime`
+    - **Output**: formatted BS string (configurable)
+    """
+
+    format: str = ""
+    nepali_type: Type[object] = object
+
+    default_error_messages = {
+        "invalid": "Invalid Bikram Sambat value. Expected format: {format}.",
+        "invalid_type": "Invalid type. Expected a string.",
+    }
+
+    def __init__(self, *, format: Optional[str] = None, **kwargs: Any) -> None:
+        """
+        Args:
+            format: Optional `strftime` format used for representation.
+                    If not provided, uses the class default.
+        """
+        if format is not None:
+            self.format = format
+        super().__init__(**kwargs)
+
+    def _parse(self, value: str):
+        if self.nepali_type is nepalidate:
+            return try_parse_nepali_date(value)
+        if self.nepali_type is nepalidatetime:
+            return try_parse_nepali_datetime(value)
+        return None
+
+    def to_representation(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+
+        if isinstance(value, self.nepali_type):
+            return value.strftime(self.format)  # type: ignore[attr-defined]
+
+        # If DB returns string, try to normalize it.
+        if isinstance(value, str):
+            parsed = self._parse(value)
+            if parsed is not None:
+                return parsed.strftime(self.format)  # type: ignore[attr-defined]
+
+        # Fallback: best-effort stringify (keeps behavior non-breaking)
+        return str(value)
+
+    def to_internal_value(self, data: Any):
+        if data in (None, ""):
+            return None
+
+        if isinstance(data, self.nepali_type):
+            return data
+
+        if not isinstance(data, str):
+            self.fail("invalid_type")
+
+        parsed = self._parse(data)
+        if parsed is not None:
+            return parsed
+
+        self.fail("invalid", format=self.format)
+
+
+# --------------------------------------------------
+# Nepali Date (BS)
+# --------------------------------------------------
+
+
+class NepaliDateSerializerField(BaseNepaliBSField):
+    """
+    DRF field for Nepali BS Date (YYYY-MM-DD)
+    """
+
+    format = "%Y-%m-%d"
+    nepali_type = nepalidate
+
+
+# --------------------------------------------------
+# Nepali DateTime (BS)
+# --------------------------------------------------
+
+
+class NepaliDateTimeSerializerField(BaseNepaliBSField):
+    """
+    DRF field for Nepali BS DateTime (YYYY-MM-DD HH:MM:SS)
+    """
+
+    format = "%Y-%m-%d %H:%M:%S"
+    nepali_type = nepalidatetime