Files
django-nepkit/README.md
T
2026-01-29 15:28:29 +05:45

341 lines
7.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# django-nepkit
<div align="center">
<img src="https://img.shields.io/pypi/v/django-nepkit?color=blue&label=PyPI&logo=pypi&logoColor=white" alt="PyPI">
<img src="https://img.shields.io/badge/Django-4.2%E2%80%936.0-0C4B33?logo=django&logoColor=white" alt="Django 4.2–6.0">
<img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white" alt="Python">
<a href="https://github.com/S4NKALP/django-nepkit/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License"></a>
</div>
`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 https://github.com/S4NKALP/django-nepkit
cd 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).