django-nepkit/README.md

django-nepkit

django-nepkit is a lightweight Django utility package for Nepali projects. It provides model fields, validators, and admin helpers for:

• Bikram Sambat (BS) date, time, and datetime
• Nepali phone number validation
• Chained address selects (province → district → municipality)

It also includes Django admin enhancements:

• NepaliModelAdmin automatically wires the Nepali datepicker
• NepaliDateFilter for filtering BS dates by year

Optional Django REST Framework (DRF) serializer fields are available (install with django-nepkit[drf]).

Notes

• The package depends on py-nepali.
• The date picker UI is implemented from sajanm/nepali-date-picker.

---

Table of Contents

• Installation
• Requirements
• Setup
• Quick Start
• Model Fields
• Address Fields (Chained Selects)
• Django Admin
• Django REST Framework
• Public API
• Contributing
• License

---

Installation

pip install django-nepkit

Optional: DRF Serializer Fields

pip install "django-nepkit[drf]"

---

Requirements

• Python >=3.11
• Django >=4.2
• nepali>=1.1.3

---

Setup

Add to INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    "django.contrib.staticfiles",
    "django_nepkit",
]

---

Quick Start

# models.py
from django.db import models
from django_nepkit import NepaliDateField, NepaliDateTimeField, NepaliPhoneNumberField

class Person(models.Model):
    name = models.CharField(max_length=100)
    birth_date = NepaliDateField()
    created_at = NepaliDateTimeField(auto_now_add=True)
    phone_number = NepaliPhoneNumberField()

# admin.py
from django.contrib import admin
from django_nepkit import NepaliModelAdmin
from .models import Person

@admin.register(Person)
class PersonAdmin(NepaliModelAdmin):
    list_display = ("name", "birth_date", "created_at", "phone_number")

NepaliModelAdmin automatically loads the Nepali datepicker assets and applies the widget—no custom forms required.

---

Model Fields

NepaliDateField (BS date)

Stores a BS date in the DB as a string (YYYY-MM-DD). In Python, it returns/accepts nepali.datetime.nepalidate.

from django_nepkit import NepaliDateField

class Event(models.Model):
    event_date = NepaliDateField()

Notes:

• Stored as a string, not SQL DATE
• Accepts BS strings like "2081-10-15", nepalidate, and AD datetime.date (converted to BS)

---

NepaliDateTimeField (BS datetime)

Stores a BS datetime string (YYYY-MM-DD HH:MM:SS) in the DB and uses nepalidatetime in Python.

from django_nepkit import NepaliDateTimeField

class Log(models.Model):
    created_at = NepaliDateTimeField(auto_now_add=True)
    updated_at = NepaliDateTimeField(auto_now=True)

---

NepaliTimeField

A normal Django TimeField for consistency.

from django_nepkit import NepaliTimeField

class Shift(models.Model):
    start_time = NepaliTimeField()

---

NepaliPhoneNumberField

A CharField with Nepali phone number validation.

from django_nepkit import NepaliPhoneNumberField

class Contact(models.Model):
    phone_number = NepaliPhoneNumberField()

---

Address Fields (Chained Selects)

Chained fields: province → district → municipality.

from django.db import models
from django_nepkit import ProvinceField, DistrictField, MunicipalityField

class Address(models.Model):
    province = ProvinceField()
    district = DistrictField()
    municipality = MunicipalityField()

URLs required for chaining

# urls.py
from django.urls import include, path

urlpatterns = [
    # ...
    path("nepkit/", include("django_nepkit.urls")),
]

---

Django Admin

NepaliModelAdmin

• Auto-wires datepicker for BS fields
• Provides format_nepali_date(...) and format_nepali_datetime(...)
• Includes NepaliDateFilter

from django.contrib import admin
from django_nepkit import NepaliModelAdmin

@admin.register(MyModel)
class MyModelAdmin(NepaliModelAdmin):
    pass

NepaliDateFilter

Filter NepaliDateField by BS year:

from django_nepkit import NepaliDateFilter, NepaliModelAdmin

@admin.register(MyModel)
class MyModelAdmin(NepaliModelAdmin):
    list_filter = (("my_nepali_date_field", NepaliDateFilter),)

Datepicker assets used:

• JS: https://nepalidatepicker.sajanmaharjan.com.np/v5/nepali.datepicker/js/nepali.datepicker.v5.0.6.min.js
• CSS: https://nepalidatepicker.sajanmaharjan.com.np/v5/nepali.datepicker/css/nepali.datepicker.v5.0.6.min.css

---

Django REST Framework

Install the extra:

pip install "django-nepkit[drf]"

NepaliDateSerializerField

from rest_framework import serializers
from django_nepkit.serializers import NepaliDateSerializerField

class PersonSerializer(serializers.Serializer):
    birth_date = NepaliDateSerializerField(format="%Y/%m/%d")

NepaliDateTimeSerializerField

from rest_framework import serializers
from django_nepkit.serializers import NepaliDateTimeSerializerField

class LogSerializer(serializers.Serializer):
    created_at = NepaliDateTimeSerializerField()

---

Public API

from django_nepkit import (
    NepaliDateField,
    NepaliTimeField,
    NepaliDateTimeField,
    NepaliPhoneNumberField,
    ProvinceField,
    DistrictField,
    MunicipalityField,
    NepaliDateFilter,
    NepaliModelAdmin,
    NepaliAdminMixin,
)

DRF fields live in django_nepkit.serializers.

---

Contributing

Contributions are welcome. If you find a bug or want an improvement, please open an issue or submit a pull request.

Local setup

Clone the repo and install dependencies (this project uses uv):

git clone <your-fork-url>
cd prod-django-nepkit
uv sync

Run the example project

The repository contains an example Django project under example/.

cd example
uv run manage.py migrate
uv run manage.py createsuperuser
uv run manage.py runserver

Code quality (recommended before every commit)

Install and run pre-commit:

uv run pre-commit install
uv run pre-commit run --all-files

You can also run Ruff directly:

uv run ruff format .
uv run ruff check .

Pull request guidelines

• Keep PRs focused and small when possible.
• Update README.md if behavior or public API changes.
• If you add a new feature, include a minimal example and tests if applicable.

---

License

MIT. See LICENSE.