193 lines
5.1 KiB
Markdown
193 lines
5.1 KiB
Markdown
# 🇳🇵 django-nepkit
|
|
|
|
<div align="center">
|
|
|
|
[](https://badge.fury.io/py/django-nepkit)
|
|
[](https://pypi.org/project/django-nepkit/)
|
|
[](https://opensource.org/licenses/MIT)
|
|
|
|
</div>
|
|
|
|
|
|
**The essential toolkit for Django developers building for Nepal.**
|
|
|
|
`django-nepkit` handles the specific localization needs of Nepali web applications with elegance and ease. From correct Bikram Sambat (BS) date handling to smart address management and phone validation, we've got you covered.
|
|
|
|
---
|
|
|
|
## ✨ Key Features
|
|
|
|
- **📅 Bikram Sambat (BS) Support**: Full support for Nepali dates and datetimes in models and forms.
|
|
- **📱 Smart Validation**: Built-in validators for Nepali phone numbers.
|
|
- **🗺️ Administrative Locations**: Chained selects for Provinces, Districts, and Municipalities.
|
|
- **🇳🇵 Bilingual Support**: Seamlessly switch between English and Nepali (Devanagari) output for locations and dates.
|
|
- **🔌 Zero-Config Admin**: `NepaliModelAdmin` automatically integrates the Nepali datepicker and formats list displays.
|
|
- **🚀 API Ready**: Optional DRF serializers with Devanagari support.
|
|
|
|
---
|
|
|
|
## 🛠 Installation
|
|
|
|
Install via pip:
|
|
|
|
```bash
|
|
pip install django-nepkit
|
|
```
|
|
|
|
### Add to `INSTALLED_APPS`
|
|
|
|
In your `settings.py`:
|
|
|
|
```python
|
|
INSTALLED_APPS = [
|
|
# ...
|
|
"django.contrib.staticfiles",
|
|
"django_nepkit",
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Model Fields
|
|
|
|
Define your models with Nepali-specific requirements effortlessly.
|
|
|
|
```python
|
|
from django.db import models
|
|
from django_nepkit import (
|
|
NepaliDateField,
|
|
NepaliDateTimeField,
|
|
NepaliPhoneNumberField
|
|
)
|
|
|
|
class Citizen(models.Model):
|
|
name = models.CharField(max_length=100)
|
|
|
|
# Stores dates as YYYY-MM-DD strings (BS)
|
|
dob = NepaliDateField()
|
|
|
|
# Use ne=True for Devanagari digits/names in forms/admin
|
|
appointment = NepaliDateTimeField(ne=True)
|
|
|
|
# Validates correct Nepali phone patterns
|
|
phone = NepaliPhoneNumberField()
|
|
```
|
|
|
|
### 2. Admin Integration
|
|
|
|
`NepaliModelAdmin` provides a zero-config experience. It:
|
|
- Automatically attaches the **Nepali Datepicker**.
|
|
- Formats `NepaliDateField` and `NepaliDateTimeField` in `list_display`.
|
|
- Registers `NepaliDateFilter` for easy year-based filtering.
|
|
|
|
```python
|
|
from django.contrib import admin
|
|
from django_nepkit import NepaliModelAdmin
|
|
from .models import Citizen
|
|
|
|
@admin.register(Citizen)
|
|
class CitizenAdmin(NepaliModelAdmin):
|
|
list_display = ("name", "dob", "phone")
|
|
```
|
|
|
|
> [!TIP]
|
|
> If you already have a custom base Admin class, use **`NepaliAdminMixin`** to get all formatting and filter benefits.
|
|
|
|
---
|
|
|
|
## 📝 Forms & Widgets
|
|
|
|
Need to build a custom form? `django-nepkit` provides specialized fields and widgets.
|
|
|
|
```python
|
|
from django import forms
|
|
from django_nepkit.forms import NepaliDateFormField, NepaliPhoneNumberFormField
|
|
from django_nepkit.widgets import NepaliDatePickerWidget
|
|
|
|
class RegistrationForm(forms.Form):
|
|
# Field with built-in validation
|
|
birth_date = NepaliDateFormField()
|
|
|
|
# Or apply the widget to a standard field
|
|
event_date = forms.CharField(
|
|
widget=NepaliDatePickerWidget(ne=True) # Devanagari support
|
|
)
|
|
|
|
phone = NepaliPhoneNumberFormField()
|
|
```
|
|
|
|
---
|
|
|
|
## 🗺️ Address Management (Chained Selects)
|
|
|
|
Model Nepal's administrative structure with automatic filtering: Province → District → Municipality. This works out-of-the-box without any extra URL configuration.
|
|
|
|
```python
|
|
from django_nepkit import ProvinceField, DistrictField, MunicipalityField
|
|
|
|
class Address(models.Model):
|
|
# For English names
|
|
province = ProvinceField()
|
|
district = DistrictField()
|
|
municipality = MunicipalityField()
|
|
|
|
# For Devanagari (बागमती, काठमाडौँ, etc.)
|
|
# province = ProvinceField(ne=True)
|
|
```
|
|
|
|
---
|
|
|
|
## 🔌 API Support (Django REST Framework)
|
|
|
|
Install the optional dependency for serializer fields:
|
|
```bash
|
|
pip install "django-nepkit[drf]"
|
|
```
|
|
|
|
Use them in your serializers with optional Devanagari (`ne=True`) output:
|
|
|
|
```python
|
|
from rest_framework import serializers
|
|
from django_nepkit.serializers import NepaliDateSerializerField
|
|
|
|
class CitizenSerializer(serializers.ModelSerializer):
|
|
# Output: "२०८१-१०-१७" if ne=True
|
|
dob = NepaliDateSerializerField(format="%Y-%m-%d", ne=True)
|
|
|
|
class Meta:
|
|
model = Citizen
|
|
fields = "__all__"
|
|
```
|
|
|
|
---
|
|
|
|
## 🛠️ Utility Functions
|
|
|
|
Need to format a date in your logic or views?
|
|
|
|
```python
|
|
from django_nepkit import format_nepali_date
|
|
|
|
# Result: "Magh 17, 2081" (or "माघ १७, २०८१" if ne=True)
|
|
formatted = format_nepali_date(my_date, format_string="%B %d, %Y", ne=False)
|
|
```
|
|
|
|
---
|
|
|
|
## 🤝 Contributing
|
|
|
|
We love contributions!
|
|
|
|
1. Clone the repo: `git clone https://github.com/S4NKALP/django-nepkit`
|
|
2. Install dependencies: `uv sync`
|
|
3. Run the tests: `uv run pytest`
|
|
4. Run the example project: `cd example && python manage.py runserver`
|
|
|
|
---
|
|
|
|
## 📄 License
|
|
|
|
MIT License. Made with ❤️ for the Nepali Django community.
|