331 lines
6.7 KiB
Markdown
331 lines
6.7 KiB
Markdown
# 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`](https://github.com/opensource-nepal/py-nepali).
|
|
- The date picker UI is implemented from [`sajanm/nepali-date-picker`](https://github.com/sajanm/nepali-date-picker).
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
- [Installation](#installation)
|
|
- [Requirements](#requirements)
|
|
- [Setup](#setup)
|
|
- [Quick Start](#quick-start)
|
|
- [Model Fields](#model-fields)
|
|
- [Address Fields (Chained Selects)](#address-fields-chained-selects)
|
|
- [Django Admin](#django-admin)
|
|
- [Django REST Framework](#django-rest-framework)
|
|
- [Public API](#public-api)
|
|
- [Contributing](#contributing)
|
|
- [License](#license)
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install django-nepkit
|
|
```
|
|
|
|
### Optional: DRF Serializer Fields
|
|
|
|
```bash
|
|
pip install "django-nepkit[drf]"
|
|
```
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Python `>=3.11`
|
|
- Django `>=4.2`
|
|
- `nepali>=1.1.3`
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
### Add to `INSTALLED_APPS`
|
|
|
|
```python
|
|
INSTALLED_APPS = [
|
|
# ...
|
|
"django.contrib.staticfiles",
|
|
"django_nepkit",
|
|
]
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
# 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()
|
|
```
|
|
|
|
```python
|
|
# 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`.
|
|
|
|
```python
|
|
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.
|
|
|
|
```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.
|
|
|
|
```python
|
|
from django_nepkit import NepaliTimeField
|
|
|
|
class Shift(models.Model):
|
|
start_time = NepaliTimeField()
|
|
```
|
|
|
|
---
|
|
|
|
### `NepaliPhoneNumberField`
|
|
|
|
A `CharField` with Nepali phone number validation.
|
|
|
|
```python
|
|
from django_nepkit import NepaliPhoneNumberField
|
|
|
|
class Contact(models.Model):
|
|
phone_number = NepaliPhoneNumberField()
|
|
```
|
|
|
|
---
|
|
|
|
## Address Fields (Chained Selects)
|
|
|
|
Chained fields: province → district → municipality.
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
# 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`
|
|
|
|
```python
|
|
from django.contrib import admin
|
|
from django_nepkit import NepaliModelAdmin
|
|
|
|
@admin.register(MyModel)
|
|
class MyModelAdmin(NepaliModelAdmin):
|
|
pass
|
|
```
|
|
|
|
### `NepaliDateFilter`
|
|
|
|
Filter `NepaliDateField` by BS year:
|
|
|
|
```python
|
|
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:
|
|
|
|
```bash
|
|
pip install "django-nepkit[drf]"
|
|
```
|
|
|
|
### `NepaliDateSerializerField`
|
|
|
|
```python
|
|
from rest_framework import serializers
|
|
from django_nepkit.serializers import NepaliDateSerializerField
|
|
|
|
class PersonSerializer(serializers.Serializer):
|
|
birth_date = NepaliDateSerializerField(format="%Y/%m/%d")
|
|
```
|
|
|
|
### `NepaliDateTimeSerializerField`
|
|
|
|
```python
|
|
from rest_framework import serializers
|
|
from django_nepkit.serializers import NepaliDateTimeSerializerField
|
|
|
|
class LogSerializer(serializers.Serializer):
|
|
created_at = NepaliDateTimeSerializerField()
|
|
```
|
|
|
|
---
|
|
|
|
## Public API
|
|
|
|
```python
|
|
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`):
|
|
|
|
```bash
|
|
git clone <your-fork-url>
|
|
cd prod-django-nepkit
|
|
uv sync
|
|
```
|
|
|
|
### Run the example project
|
|
|
|
The repository contains an example Django project under `example/`.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
uv run pre-commit install
|
|
uv run pre-commit run --all-files
|
|
```
|
|
|
|
You can also run Ruff directly:
|
|
|
|
```bash
|
|
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`](LICENSE).
|