django-nepkit 0.1.0__tar.gz → 0.2.1__tar.gz

django_nepkit-0.2.1/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: django-nepkit
+Version: 0.2.1
+Summary: Django Nepali date, time, phone, and address fields with helpers.
+Home-page: https://github.com/S4NKALP/django-nepkit
+Author: Sankalp Tharu
+Author-email: Sankalp Tharu <sankalptharu50028@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/S4NKALP/django-nepkit
+Keywords: django,django-fields,django-forms,nepal,nepali,nepali-date,bikram-sambat,nepali-calendar,timezone,asia-kathmandu,phone-number,address,province,district,municipality
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 6.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Operating System :: OS Independent
+Classifier: Natural Language :: English
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.2
+Requires-Dist: django-filter>=25.2
+Requires-Dist: djangorestframework>=3.16.1
+Requires-Dist: nepali>=1.2.0
+Provides-Extra: drf
+Requires-Dist: djangorestframework>=3.14; extra == "drf"
+Requires-Dist: django-filter>=23.1; extra == "drf"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# 🇳🇵 django-nepkit
+
+<div align="center">
+
+[![PyPI version](https://badge.fury.io/py/django-nepkit.svg)](https://badge.fury.io/py/django-nepkit)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-nepkit.svg)](https://pypi.org/project/django-nepkit/)
+[![Django Versions](https://img.shields.io/badge/Django-3.2%20%7C%204.2%20%7C%205.0%20%7C%206.0-blue.svg)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**A toolkit for handling BS dates, regional locations, and validation in the local context.**
+
+</div>
+
+Building software for local requirements comes with unique challenges, from handling BS dates to managing the regional administrative hierarchy. `django-nepkit` provides solutions for these requirements directly within the Django ecosystem.
+
+![Showcase](docs/showcase.gif)
+
+---
+
+## 🎯 Features
+
+- **📅 BS Date Support**: Model fields for `nepalidate` and `nepalidatetime` objects.
+- **🗺️ Regional Locations**: Pre-defined Provinces, Districts, and Municipalities.
+- **📱 Phone Validation**: Patterns for local mobile and landline numbers.
+- **💰 Currency Formatting**: `NepaliCurrencyField` with automatic Lakhs/Crores comma placement.
+- **🔤 Numbers to Words**: Convert digits into Nepali text representation.
+- **🔌 Admin Integration**: Automatic setup for datepickers and localized list displays.
+- **🚀 API Support**: DRF Serializers and Filtering backends for BS searching and ordering.
+- **⚡ Location Chaining**: Address linking via client side JS or server driven HTMX.
+- **🔍 Address Normalization**: Utility to extract structured locations from raw strings.
+
+---
+
+## 🛠 Setup
+
+Installation:
+
+```bash
+pip install django-nepkit
+```
+
+### 1. Basic Configuration
+
+Add it to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_nepkit",
+]
+```
+
+### 2. Global Control
+
+Configure behavior in your `settings.py`:
+
+```python
+NEPKIT = {
+    "DEFAULT_LANGUAGE": "en",           # "en" or "ne"
+    "ADMIN_DATEPICKER": True,           # Toggle the datepicker
+    "TIME_FORMAT": 12,                  # 12 or 24 hour display
+    "DATE_INPUT_FORMATS": ["%Y-%m-%d", "%d/%m/%Y", "%d-%m-%Y"], # Input formats
+}
+```
+
+---
+
+## 🚀 Core Usage
+
+### 1. Model Implementation
+
+Fields store `YYYY-MM-DD` strings for database stability while providing BS objects in Python.
+
+```python
+from django_nepkit import NepaliDateField, NepaliPhoneNumberField
+
+class Profile(models.Model):
+    name = models.CharField(max_length=100)
+    birth_date = NepaliDateField() # BS Date support
+    phone = NepaliPhoneNumberField() # Local pattern validation
+```
+
+### 2. Admin Integration
+
+Use `NepaliModelAdmin` for automatic formatting and datepicker support.
+
+```python
+from django_nepkit import NepaliModelAdmin, NepaliDateFilter
+
+@admin.register(Profile)
+class ProfileAdmin(NepaliModelAdmin):
+    list_display = ("name", "birth_date", "phone")
+    list_filter = (("birth_date", NepaliDateFilter),)
+```
+
+---
+
+## 🗺️ Address Management
+
+Manage the **Province → District → Municipality** hierarchy.
+
+### Client-Side Chaining (Standard)
+
+Cascading selects in the Django Admin without extra configuration.
+
+```python
+from django_nepkit import ProvinceField, DistrictField, MunicipalityField
+
+class Address(models.Model):
+    province = ProvinceField()
+    district = DistrictField()
+    municipality = MunicipalityField()
+
+### Address Normalization
+
+Standardize raw strings into structured location data (Province, District, Municipality).
+
+```python
+from django_nepkit.utils import normalize_address
+
+# Supports English or Nepali input
+result = normalize_address("House 123, Bharatpur, Chitwan")
+# Returns: {'province': 'Bagmati Province', 'district': 'Chitawan', 'municipality': 'Bharatpur Metropolitan City'}
+
+result_ne = normalize_address("विराटनगर, कोशी")
+# Returns: {'province': 'कोशी प्रदेश', 'district': 'मोरङ', 'municipality': 'विराटनगर महानगरपालिका'}
+```
+```
+
+### Server Side Chaining (HTMX)
+
+Enable `htmx=True` for a server driven experience.
+
+> [!IMPORTANT]
+> **HTMX Setup:**
+> Include the required URLs in your main `urls.py`:
+>
+> ```python
+> path("nepkit/", include("django_nepkit.urls")),
+> ```
+
+---
+
+## 🔌 API & DRF Support
+
+Search and ordering work natively. BS year/month filtering is supported.
+
+```python
+from django_nepkit.filters import NepaliDateYearFilter
+
+class ProfileFilter(filters.FilterSet):
+    # Filter by BS Year (e.g., /api/profiles/?year=2081)
+    year = NepaliDateYearFilter(field_name="birth_date")
+```
+
+---
+
+## 💰 Formatting & Helpers
+
+### 1. Currency & Numbers
+Use `NepaliCurrencyField` for automatic formatting in the admin and templates.
+
+```python
+from django_nepkit import NepaliCurrencyField
+
+class Transaction(models.Model):
+    amount = NepaliCurrencyField() # Defaults to 19 digits, 2 decimals
+```
+
+### 2. Template Filters
+Load the tags to use localized formatting in your templates.
+
+```html
+{% load nepali %}
+
+<!-- Comma formatting: Rs. 1,12,000.00 -->
+<p>{{ 112000 | nepali_currency }}</p>
+
+<!-- Numbers to Words: एक सय तेईस -->
+<p>{{ 123 | nepali_words }}</p>
+
+<!-- English to Nepali Digits: १२३ -->
+<p>{{ "123" | nepali_unicode }}</p>
+```
+
+---
+
+## 🕒 Technical Design
+
+This library is engineered for performance, data integrity, and local compliance.
+
+### 1. The "Source of Truth" Strategy
+We avoid on-the-fly `AD to BS` conversion during database queries because it is computationally expensive and prone to logical drift (due to lunar calendar offsets).
+- **Storage**: All BS dates are stored as `VARCHAR(10)` in `YYYY-MM-DD` format.
+- **Sorting**: Because `YYYY` is at the start, string based database sorting (ascending/descending) accurately matches chronological order.
+- **Indexability**: Standard B-Tree indexes work perfectly on these fields without requiring custom database functions.
+- **Timezone Safety**: Dates are stored without time components, making them immune to server side timezone shifts during saving.
+
+### 2. Python Object Mapping
+While data is stored as strings, it is automatically hydrated into rich Python objects.
+- **`nepali-datetime` Integration**: Values are cast to `nepalidate` or `nepalidatetime` objects when retrieved from the database.
+- **Validation**: Fields use specialized validators (e.g., `validate_nepali_phone_number`) that leverage official regional patterns.
+
+### 3. Frontend Architecture
+- **Automatic Initialization**: The library includes a lightweight JS observer that automatically initializes the datepicker for any field with the `.nepkit-datepicker` class.
+- **Theme Support**: The datepicker dynamically adapts its skin based on the Django Admin's dark/light mode state.
+
+---
+
+## ❓ FAQ
+
+**Q: How do I handle Null or Optional dates?**
+
+Just like standard Django fields, pass `null=True, blank=True` to any `django-nepkit` field. The library handles empty strings and `None` values gracefully.
+
+**Q: Can I change the database storage format?**
+
+No. The `YYYY-MM-DD` format is hardcoded to ensure database level sorting and indexing work consistently. However, you can change the **display** format via global settings or template filters.
+
+**Q: Can I use Devanagari output?**
+
+Yes. Pass `ne=True` to fields, forms, or serializers.
+
+**Q: Can I display the datepicker in English?**
+
+Yes. By default, if you pass `en=True` (or if `DEFAULT_LANGUAGE` is set to `"en"`), the datepicker will display month and day names in English instead of Devanagari script.
+
+```python
+birth_date = NepaliDateField(en=True)  # English month/day names in picker
+```
+
+**Q: Is the location data up to date?**
+
+Yes. Province, District, and Municipality data is sourced from the `nepali` Python package, which is regularly updated to reflect administrative changes in Nepal.
+
+**Q: Does it work with standard Django Forms?**
+
+Yes. `NepaliDateField` uses a specialized `NepaliDateFormField` that automatically handles input parsing and error reporting.
+
+**Q: How do I migrate existing English (AD) dates to BS?**
+
+We recommend staying on standard `DateField` for AD data. If you must convert to BS, use our [Migration Script](docs/migration_guide.py) to perform a bulk data transformation safely.
+
+**Q: Why use VARCHAR instead of a native DateField?**
+
+Native `DateField` in most SQL engines is locked to the Gregorian calendar. Using `VARCHAR` allows us to treat the BS date as the primary data point, avoiding the "off-by-one" conversion errors common when syncing two disparate calendars.
+
+---
+
+## 🤝 Community
+
+We welcome contributions and feedback from the community.
+
+1. **Clone**: `git clone https://github.com/S4NKALP/django-nepkit`
+2. **Setup**: `uv sync`
+3. **Test**: `uv run pytest`
+
+---
+
+## 🙏 Credits
+
+This library is built on top of excellent open source projects:
+
+- **[nepali](https://github.com/opensource-nepal/py-nepali)** by [@opensource-nepal](https://github.com/opensource-nepal) - Provides the core `nepalidate`, `nepalidatetime` objects and regional location data (Provinces, Districts, Municipalities).
+- **[Nepali Datepicker](https://nepalidatepicker.sajanmaharjan.com.np/)** by [Sajan Maharjan](https://github.com/sajanm/nepali-date-picker) - Powers the beautiful BS date picker widget in the Django Admin.
+
+---
+
+MIT License. Designed for the local Django ecosystem.

django_nepkit-0.2.1/README.md

@@ -0,0 +1,269 @@
+# 🇳🇵 django-nepkit
+
+<div align="center">
+
+[![PyPI version](https://badge.fury.io/py/django-nepkit.svg)](https://badge.fury.io/py/django-nepkit)
+[![Python Versions](https://img.shields.io/pypi/pyversions/django-nepkit.svg)](https://pypi.org/project/django-nepkit/)
+[![Django Versions](https://img.shields.io/badge/Django-3.2%20%7C%204.2%20%7C%205.0%20%7C%206.0-blue.svg)](https://www.djangoproject.com/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**A toolkit for handling BS dates, regional locations, and validation in the local context.**
+
+</div>
+
+Building software for local requirements comes with unique challenges, from handling BS dates to managing the regional administrative hierarchy. `django-nepkit` provides solutions for these requirements directly within the Django ecosystem.
+
+![Showcase](docs/showcase.gif)
+
+---
+
+## 🎯 Features
+
+- **📅 BS Date Support**: Model fields for `nepalidate` and `nepalidatetime` objects.
+- **🗺️ Regional Locations**: Pre-defined Provinces, Districts, and Municipalities.
+- **📱 Phone Validation**: Patterns for local mobile and landline numbers.
+- **💰 Currency Formatting**: `NepaliCurrencyField` with automatic Lakhs/Crores comma placement.
+- **🔤 Numbers to Words**: Convert digits into Nepali text representation.
+- **🔌 Admin Integration**: Automatic setup for datepickers and localized list displays.
+- **🚀 API Support**: DRF Serializers and Filtering backends for BS searching and ordering.
+- **⚡ Location Chaining**: Address linking via client side JS or server driven HTMX.
+- **🔍 Address Normalization**: Utility to extract structured locations from raw strings.
+
+---
+
+## 🛠 Setup
+
+Installation:
+
+```bash
+pip install django-nepkit
+```
+
+### 1. Basic Configuration
+
+Add it to your `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_nepkit",
+]
+```
+
+### 2. Global Control
+
+Configure behavior in your `settings.py`:
+
+```python
+NEPKIT = {
+    "DEFAULT_LANGUAGE": "en",           # "en" or "ne"
+    "ADMIN_DATEPICKER": True,           # Toggle the datepicker
+    "TIME_FORMAT": 12,                  # 12 or 24 hour display
+    "DATE_INPUT_FORMATS": ["%Y-%m-%d", "%d/%m/%Y", "%d-%m-%Y"], # Input formats
+}
+```
+
+---
+
+## 🚀 Core Usage
+
+### 1. Model Implementation
+
+Fields store `YYYY-MM-DD` strings for database stability while providing BS objects in Python.
+
+```python
+from django_nepkit import NepaliDateField, NepaliPhoneNumberField
+
+class Profile(models.Model):
+    name = models.CharField(max_length=100)
+    birth_date = NepaliDateField() # BS Date support
+    phone = NepaliPhoneNumberField() # Local pattern validation
+```
+
+### 2. Admin Integration
+
+Use `NepaliModelAdmin` for automatic formatting and datepicker support.
+
+```python
+from django_nepkit import NepaliModelAdmin, NepaliDateFilter
+
+@admin.register(Profile)
+class ProfileAdmin(NepaliModelAdmin):
+    list_display = ("name", "birth_date", "phone")
+    list_filter = (("birth_date", NepaliDateFilter),)
+```
+
+---
+
+## 🗺️ Address Management
+
+Manage the **Province → District → Municipality** hierarchy.
+
+### Client-Side Chaining (Standard)
+
+Cascading selects in the Django Admin without extra configuration.
+
+```python
+from django_nepkit import ProvinceField, DistrictField, MunicipalityField
+
+class Address(models.Model):
+    province = ProvinceField()
+    district = DistrictField()
+    municipality = MunicipalityField()
+
+### Address Normalization
+
+Standardize raw strings into structured location data (Province, District, Municipality).
+
+```python
+from django_nepkit.utils import normalize_address
+
+# Supports English or Nepali input
+result = normalize_address("House 123, Bharatpur, Chitwan")
+# Returns: {'province': 'Bagmati Province', 'district': 'Chitawan', 'municipality': 'Bharatpur Metropolitan City'}
+
+result_ne = normalize_address("विराटनगर, कोशी")
+# Returns: {'province': 'कोशी प्रदेश', 'district': 'मोरङ', 'municipality': 'विराटनगर महानगरपालिका'}
+```
+```
+
+### Server Side Chaining (HTMX)
+
+Enable `htmx=True` for a server driven experience.
+
+> [!IMPORTANT]
+> **HTMX Setup:**
+> Include the required URLs in your main `urls.py`:
+>
+> ```python
+> path("nepkit/", include("django_nepkit.urls")),
+> ```
+
+---
+
+## 🔌 API & DRF Support
+
+Search and ordering work natively. BS year/month filtering is supported.
+
+```python
+from django_nepkit.filters import NepaliDateYearFilter
+
+class ProfileFilter(filters.FilterSet):
+    # Filter by BS Year (e.g., /api/profiles/?year=2081)
+    year = NepaliDateYearFilter(field_name="birth_date")
+```
+
+---
+
+## 💰 Formatting & Helpers
+
+### 1. Currency & Numbers
+Use `NepaliCurrencyField` for automatic formatting in the admin and templates.
+
+```python
+from django_nepkit import NepaliCurrencyField
+
+class Transaction(models.Model):
+    amount = NepaliCurrencyField() # Defaults to 19 digits, 2 decimals
+```
+
+### 2. Template Filters
+Load the tags to use localized formatting in your templates.
+
+```html
+{% load nepali %}
+
+<!-- Comma formatting: Rs. 1,12,000.00 -->
+<p>{{ 112000 | nepali_currency }}</p>
+
+<!-- Numbers to Words: एक सय तेईस -->
+<p>{{ 123 | nepali_words }}</p>
+
+<!-- English to Nepali Digits: १२३ -->
+<p>{{ "123" | nepali_unicode }}</p>
+```
+
+---
+
+## 🕒 Technical Design
+
+This library is engineered for performance, data integrity, and local compliance.
+
+### 1. The "Source of Truth" Strategy
+We avoid on-the-fly `AD to BS` conversion during database queries because it is computationally expensive and prone to logical drift (due to lunar calendar offsets).
+- **Storage**: All BS dates are stored as `VARCHAR(10)` in `YYYY-MM-DD` format.
+- **Sorting**: Because `YYYY` is at the start, string based database sorting (ascending/descending) accurately matches chronological order.
+- **Indexability**: Standard B-Tree indexes work perfectly on these fields without requiring custom database functions.
+- **Timezone Safety**: Dates are stored without time components, making them immune to server side timezone shifts during saving.
+
+### 2. Python Object Mapping
+While data is stored as strings, it is automatically hydrated into rich Python objects.
+- **`nepali-datetime` Integration**: Values are cast to `nepalidate` or `nepalidatetime` objects when retrieved from the database.
+- **Validation**: Fields use specialized validators (e.g., `validate_nepali_phone_number`) that leverage official regional patterns.
+
+### 3. Frontend Architecture
+- **Automatic Initialization**: The library includes a lightweight JS observer that automatically initializes the datepicker for any field with the `.nepkit-datepicker` class.
+- **Theme Support**: The datepicker dynamically adapts its skin based on the Django Admin's dark/light mode state.
+
+---
+
+## ❓ FAQ
+
+**Q: How do I handle Null or Optional dates?**
+
+Just like standard Django fields, pass `null=True, blank=True` to any `django-nepkit` field. The library handles empty strings and `None` values gracefully.
+
+**Q: Can I change the database storage format?**
+
+No. The `YYYY-MM-DD` format is hardcoded to ensure database level sorting and indexing work consistently. However, you can change the **display** format via global settings or template filters.
+
+**Q: Can I use Devanagari output?**
+
+Yes. Pass `ne=True` to fields, forms, or serializers.
+
+**Q: Can I display the datepicker in English?**
+
+Yes. By default, if you pass `en=True` (or if `DEFAULT_LANGUAGE` is set to `"en"`), the datepicker will display month and day names in English instead of Devanagari script.
+
+```python
+birth_date = NepaliDateField(en=True)  # English month/day names in picker
+```
+
+**Q: Is the location data up to date?**
+
+Yes. Province, District, and Municipality data is sourced from the `nepali` Python package, which is regularly updated to reflect administrative changes in Nepal.
+
+**Q: Does it work with standard Django Forms?**
+
+Yes. `NepaliDateField` uses a specialized `NepaliDateFormField` that automatically handles input parsing and error reporting.
+
+**Q: How do I migrate existing English (AD) dates to BS?**
+
+We recommend staying on standard `DateField` for AD data. If you must convert to BS, use our [Migration Script](docs/migration_guide.py) to perform a bulk data transformation safely.
+
+**Q: Why use VARCHAR instead of a native DateField?**
+
+Native `DateField` in most SQL engines is locked to the Gregorian calendar. Using `VARCHAR` allows us to treat the BS date as the primary data point, avoiding the "off-by-one" conversion errors common when syncing two disparate calendars.
+
+---
+
+## 🤝 Community
+
+We welcome contributions and feedback from the community.
+
+1. **Clone**: `git clone https://github.com/S4NKALP/django-nepkit`
+2. **Setup**: `uv sync`
+3. **Test**: `uv run pytest`
+
+---
+
+## 🙏 Credits
+
+This library is built on top of excellent open source projects:
+
+- **[nepali](https://github.com/opensource-nepal/py-nepali)** by [@opensource-nepal](https://github.com/opensource-nepal) - Provides the core `nepalidate`, `nepalidatetime` objects and regional location data (Provinces, Districts, Municipalities).
+- **[Nepali Datepicker](https://nepalidatepicker.sajanmaharjan.com.np/)** by [Sajan Maharjan](https://github.com/sajanm/nepali-date-picker) - Powers the beautiful BS date picker widget in the Django Admin.
+
+---
+
+MIT License. Designed for the local Django ecosystem.

{django_nepkit-0.1.0 → django_nepkit-0.2.1}/django_nepkit/__init__.py

@@ -6,14 +6,26 @@ from .models import (
     ProvinceField,
     DistrictField,
     MunicipalityField,
+    NepaliCurrencyField,
 )
 from .admin import (
     NepaliDateFilter,
+    NepaliMonthFilter,
     format_nepali_date,
     format_nepali_datetime,
     NepaliModelAdmin,
     NepaliAdminMixin,
 )
+from .serializers import (
+    NepaliCurrencySerializerField,
+    NepaliLocalizedSerializerMixin,
+)
+from .filters import (
+    NepaliDateYearFilter,
+    NepaliDateMonthFilter,
+    NepaliDateRangeFilter,
+    NepaliCurrencyRangeFilter,
+)
 
 __all__ = [
     "NepaliDateField",
@@ -24,8 +36,16 @@ __all__ = [
     "DistrictField",
     "MunicipalityField",
     "NepaliDateFilter",
+    "NepaliMonthFilter",
     "format_nepali_date",
     "format_nepali_datetime",
     "NepaliModelAdmin",
     "NepaliAdminMixin",
+    "NepaliCurrencyField",
+    "NepaliCurrencySerializerField",
+    "NepaliLocalizedSerializerMixin",
+    "NepaliDateYearFilter",
+    "NepaliDateMonthFilter",
+    "NepaliDateRangeFilter",
+    "NepaliCurrencyRangeFilter",
 ]