nilva-django-utils 0.1.0__tar.gz

nilva_django_utils-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Nilva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nilva_django_utils-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: nilva-django-utils
+Version: 0.1.0
+Summary: Nilva house Iranian-locale toolkit — Persian digit normalization, Jalali dates and admin widgets, national-code / phone / IBAN / card validation, shared regex patterns
+Author-email: Nilva <dev@nilva.ai>
+License-Expression: MIT
+Project-URL: homepage, https://gitlab.nilva.ai/nilva/dev-assets/django/nilva-django-utils
+Project-URL: repository, https://gitlab.nilva.ai/nilva/dev-assets/django/nilva-django-utils
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Natural Language :: Persian
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: django
+Requires-Dist: django>=6.0; extra == "django"
+Provides-Extra: jalali
+Requires-Dist: jdatetime>=4.1; extra == "jalali"
+Provides-Extra: jalali-admin
+Requires-Dist: django>=6.0; extra == "jalali-admin"
+Requires-Dist: jdatetime>=4.1; extra == "jalali-admin"
+Requires-Dist: django-jalali>=7.0; extra == "jalali-admin"
+Provides-Extra: phonenumbers
+Requires-Dist: phonenumbers>=8.13; extra == "phonenumbers"
+Dynamic: license-file
+
+# nilva-django-utils
+
+Nilva's house Iranian-locale toolkit for Django and plain-Python services.
+Consolidates the digit-normalization, Jalali-date, national-code, phone,
+bank-identifier and regex-constant code that was previously copy-pasted
+(and drifting) across the Nilva backends.
+
+The **core is dependency-free** — `digits`, `numbers`, `national_id`,
+`phone`, `bank`, `patterns` and `conf` are pure standard library. Jalali,
+Django and libphonenumber layers are opt-in extras and are never imported by
+the top-level package.
+
+## Install
+
+```bash
+uv add nilva-django-utils                     # stdlib core only
+uv add "nilva-django-utils[django]"           # + Django validators
+uv add "nilva-django-utils[jalali]"           # + jdatetime formatting helpers
+uv add "nilva-django-utils[jalali-admin]"     # + admin datepicker widgets (django-jalali)
+uv add "nilva-django-utils[phonenumbers]"     # + international E.164 normalization
+```
+
+## Digits — `nilva_django_utils.digits`
+
+```python
+from nilva_django_utils import to_english_digits, to_persian_digits
+
+to_english_digits("۱۰۰۰٠٠٠۰۰۷")            # "1000000007"  (Persian AND Arabic-Indic)
+to_persian_digits(1234567, separate=True)   # "۱,۲۳۴,۵۶۷"
+```
+
+`translate_numbers(text, is_separate=False)` is kept as a drop-in for the
+legacy `utils.general.number_utils` signatures.
+
+## Numbers — `nilva_django_utils.numbers`
+
+```python
+convert_to_seconds("1h30m")     # 5400 — bare numbers count as seconds
+separate_thousands(1234567)     # "1,234,567"
+truncate(1.23456789, 4)         # 1.2345 (truncates, never rounds)
+```
+
+## National code (کد ملی) — `nilva_django_utils.national_id`
+
+Real mod-11 checksum (not `isdigit()`), digit-normalized first:
+
+```python
+is_valid_national_id("۱۲۳۴۵۶۷۸۹۱")          # True
+is_valid_national_id("1111111111")            # False (all-same rejected)
+normalize_national_id("11111119", pad=True)   # "0011111119" — Excel ate the zeros
+```
+
+## Phone — `nilva_django_utils.phone`
+
+```python
+normalize_iranian_mobile("+98 912 345 6789")  # "09123456789" (canonical national)
+to_e164_iranian("۰۹۱۲۳۴۵۶۷۸۹")             # "+989123456789"
+is_valid_iranian_mobile("9123456789")         # True — all house spellings accepted
+
+# international numbers, libphonenumber-backed ([phonenumbers] extra):
+normalize_phone("00442071838750")             # "+442071838750"
+normalize_phone("2071838750", country_code="GB")
+```
+
+## Bank — `nilva_django_utils.bank`
+
+```python
+is_valid_iban("IR49 0000 0000 0000 0000 0000 00")  # ISO 13616 mod-97
+is_valid_card_number("6104-3377-1234-5675")          # Luhn
+```
+
+## Patterns — `nilva_django_utils.patterns`
+
+One canonical constant per identifier (mobile, MCI-only ranges, landline,
+IBAN, postal code, card, account, national id) replacing the divergent
+per-project `PHONE_REGEX_PATTERN`s. Structure-only — pair with the checksum
+helpers above where correctness matters.
+
+## Django validators — `nilva_django_utils.validators`
+
+```python
+from nilva_django_utils.validators import (
+    validate_national_id, validate_iranian_mobile, validate_iban, validate_card_number,
+    iranian_mobile_regex_validator, iban_regex_validator, postal_code_regex_validator,
+)
+
+class Profile(models.Model):
+    national_id = models.CharField(max_length=10, validators=[validate_national_id])
+    phone = models.CharField(max_length=13, validators=[validate_iranian_mobile])
+    sheba = models.CharField(max_length=26, validators=[validate_iban])
+```
+
+They work unchanged in DRF serializers (DRF converts Django `ValidationError`s).
+
+## Jalali — `nilva_django_utils.jalali` / `.admin`
+
+House convention: the database and the API stay **gregorian**; Jalali only
+appears at the display/input boundary.
+
+```python
+from nilva_django_utils.jalali import to_jalali, to_jalali_datetime, parse_jalali
+
+to_jalali(obj.created_at)                 # "1403-01-01"
+to_jalali_datetime(obj.created_at)        # "1403-01-01 08:30" (active TZ when Django is up)
+parse_jalali("۱۴۰۳/۰۱/۰۱")              # datetime.date(2024, 3, 20)
+```
+
+Admin datepickers over gregorian `DateField`s (`[jalali-admin]` extra):
+
+```python
+from nilva_django_utils.admin import JalaliDateAdminMixin, jalali_datetime_display
+
+@admin.register(Delivery)
+class DeliveryAdmin(JalaliDateAdminMixin, admin.ModelAdmin):
+    readonly_fields = ("created_jalali",)
+
+    @admin.display(description="ایجاد")
+    def created_jalali(self, obj):
+        return jalali_datetime_display(obj.created_at)
+```
+
+Add the datepicker static files exactly as Shahab does:
+
+```python
+# settings.py
+from nilva_django_utils.conf import JALALI_SETTINGS  # noqa: F401
+```
+
+Projects that store `jmodels.jDateField` natively (Shahab) or use
+`django-jalali-date` mixins (Etka/Bazargah/Xpress) keep working as-is — this
+module is for the gregorian-DB + Jalali-admin convention (Depository).
+
+## Development
+
+```bash
+uv sync --group dev
+./run_tests.sh          # ./run_tests.sh -c for coverage
+uv run ruff check .
+```

nilva_django_utils-0.1.0/README.md

@@ -0,0 +1,139 @@
+# nilva-django-utils
+
+Nilva's house Iranian-locale toolkit for Django and plain-Python services.
+Consolidates the digit-normalization, Jalali-date, national-code, phone,
+bank-identifier and regex-constant code that was previously copy-pasted
+(and drifting) across the Nilva backends.
+
+The **core is dependency-free** — `digits`, `numbers`, `national_id`,
+`phone`, `bank`, `patterns` and `conf` are pure standard library. Jalali,
+Django and libphonenumber layers are opt-in extras and are never imported by
+the top-level package.
+
+## Install
+
+```bash
+uv add nilva-django-utils                     # stdlib core only
+uv add "nilva-django-utils[django]"           # + Django validators
+uv add "nilva-django-utils[jalali]"           # + jdatetime formatting helpers
+uv add "nilva-django-utils[jalali-admin]"     # + admin datepicker widgets (django-jalali)
+uv add "nilva-django-utils[phonenumbers]"     # + international E.164 normalization
+```
+
+## Digits — `nilva_django_utils.digits`
+
+```python
+from nilva_django_utils import to_english_digits, to_persian_digits
+
+to_english_digits("۱۰۰۰٠٠٠۰۰۷")            # "1000000007"  (Persian AND Arabic-Indic)
+to_persian_digits(1234567, separate=True)   # "۱,۲۳۴,۵۶۷"
+```
+
+`translate_numbers(text, is_separate=False)` is kept as a drop-in for the
+legacy `utils.general.number_utils` signatures.
+
+## Numbers — `nilva_django_utils.numbers`
+
+```python
+convert_to_seconds("1h30m")     # 5400 — bare numbers count as seconds
+separate_thousands(1234567)     # "1,234,567"
+truncate(1.23456789, 4)         # 1.2345 (truncates, never rounds)
+```
+
+## National code (کد ملی) — `nilva_django_utils.national_id`
+
+Real mod-11 checksum (not `isdigit()`), digit-normalized first:
+
+```python
+is_valid_national_id("۱۲۳۴۵۶۷۸۹۱")          # True
+is_valid_national_id("1111111111")            # False (all-same rejected)
+normalize_national_id("11111119", pad=True)   # "0011111119" — Excel ate the zeros
+```
+
+## Phone — `nilva_django_utils.phone`
+
+```python
+normalize_iranian_mobile("+98 912 345 6789")  # "09123456789" (canonical national)
+to_e164_iranian("۰۹۱۲۳۴۵۶۷۸۹")             # "+989123456789"
+is_valid_iranian_mobile("9123456789")         # True — all house spellings accepted
+
+# international numbers, libphonenumber-backed ([phonenumbers] extra):
+normalize_phone("00442071838750")             # "+442071838750"
+normalize_phone("2071838750", country_code="GB")
+```
+
+## Bank — `nilva_django_utils.bank`
+
+```python
+is_valid_iban("IR49 0000 0000 0000 0000 0000 00")  # ISO 13616 mod-97
+is_valid_card_number("6104-3377-1234-5675")          # Luhn
+```
+
+## Patterns — `nilva_django_utils.patterns`
+
+One canonical constant per identifier (mobile, MCI-only ranges, landline,
+IBAN, postal code, card, account, national id) replacing the divergent
+per-project `PHONE_REGEX_PATTERN`s. Structure-only — pair with the checksum
+helpers above where correctness matters.
+
+## Django validators — `nilva_django_utils.validators`
+
+```python
+from nilva_django_utils.validators import (
+    validate_national_id, validate_iranian_mobile, validate_iban, validate_card_number,
+    iranian_mobile_regex_validator, iban_regex_validator, postal_code_regex_validator,
+)
+
+class Profile(models.Model):
+    national_id = models.CharField(max_length=10, validators=[validate_national_id])
+    phone = models.CharField(max_length=13, validators=[validate_iranian_mobile])
+    sheba = models.CharField(max_length=26, validators=[validate_iban])
+```
+
+They work unchanged in DRF serializers (DRF converts Django `ValidationError`s).
+
+## Jalali — `nilva_django_utils.jalali` / `.admin`
+
+House convention: the database and the API stay **gregorian**; Jalali only
+appears at the display/input boundary.
+
+```python
+from nilva_django_utils.jalali import to_jalali, to_jalali_datetime, parse_jalali
+
+to_jalali(obj.created_at)                 # "1403-01-01"
+to_jalali_datetime(obj.created_at)        # "1403-01-01 08:30" (active TZ when Django is up)
+parse_jalali("۱۴۰۳/۰۱/۰۱")              # datetime.date(2024, 3, 20)
+```
+
+Admin datepickers over gregorian `DateField`s (`[jalali-admin]` extra):
+
+```python
+from nilva_django_utils.admin import JalaliDateAdminMixin, jalali_datetime_display
+
+@admin.register(Delivery)
+class DeliveryAdmin(JalaliDateAdminMixin, admin.ModelAdmin):
+    readonly_fields = ("created_jalali",)
+
+    @admin.display(description="ایجاد")
+    def created_jalali(self, obj):
+        return jalali_datetime_display(obj.created_at)
+```
+
+Add the datepicker static files exactly as Shahab does:
+
+```python
+# settings.py
+from nilva_django_utils.conf import JALALI_SETTINGS  # noqa: F401
+```
+
+Projects that store `jmodels.jDateField` natively (Shahab) or use
+`django-jalali-date` mixins (Etka/Bazargah/Xpress) keep working as-is — this
+module is for the gregorian-DB + Jalali-admin convention (Depository).
+
+## Development
+
+```bash
+uv sync --group dev
+./run_tests.sh          # ./run_tests.sh -c for coverage
+uv run ruff check .
+```

nilva_django_utils-0.1.0/nilva_django_utils/__init__.py

@@ -0,0 +1,46 @@
+"""Nilva Django Utils — the Nilva house Iranian-locale toolkit.
+
+Persian / Arabic-Indic digit normalization, Jalali calendar formatting and
+admin datepickers, national-code (کد ملی) validation, Iranian phone-number
+normalization, bank identifier checksums (IBAN, card number) and the shared
+regex patterns that were previously copy-pasted across the Nilva backends.
+
+The core (``digits``, ``numbers``, ``national_id``, ``phone``, ``bank``,
+``patterns``, ``conf``) is pure standard library and works in any Python
+service. The optional layers are imported explicitly and never load from
+here:
+
+* ``nilva_django_utils.jalali`` — requires ``jdatetime`` (``[jalali]`` extra)
+* ``nilva_django_utils.validators`` — requires Django (``[django]`` extra)
+* ``nilva_django_utils.admin`` — requires Django + ``django-jalali``
+  (``[jalali-admin]`` extra)
+* ``phone.normalize_phone`` — requires ``phonenumbers``
+  (``[phonenumbers]`` extra)
+"""
+
+__version__ = "0.1.0"
+
+from . import patterns
+from .bank import is_valid_card_number, is_valid_iban
+from .digits import to_english_digits, to_persian_digits, translate_numbers
+from .national_id import is_valid_national_id, normalize_national_id
+from .numbers import convert_to_seconds, separate_thousands, truncate
+from .phone import is_valid_iranian_mobile, normalize_iranian_mobile, to_e164_iranian
+
+__all__ = [
+    "__version__",
+    "patterns",
+    "is_valid_card_number",
+    "is_valid_iban",
+    "to_english_digits",
+    "to_persian_digits",
+    "translate_numbers",
+    "is_valid_national_id",
+    "normalize_national_id",
+    "convert_to_seconds",
+    "separate_thousands",
+    "truncate",
+    "is_valid_iranian_mobile",
+    "normalize_iranian_mobile",
+    "to_e164_iranian",
+]

nilva_django_utils-0.1.0/nilva_django_utils/admin.py

@@ -0,0 +1,81 @@
+"""Jalali datepickers and display helpers for the Django admin
+(the ``[jalali-admin]`` extra: Django + ``django-jalali``).
+
+Ported from the Depository backend: dates stay *gregorian* in the database
+(the API contract is gregorian ISO-8601) while the admin renders and accepts
+Jalali. ``JalaliDateAdminMixin`` wires the widget onto every ``DateField`` of
+a ``ModelAdmin``; ``jalali_display`` / ``jalali_datetime_display`` are for
+read-only ``list_display`` / ``readonly_fields`` cells.
+
+Projects that instead store ``jmodels.jDateField`` natively (Shahab) or use
+``django-jalali-date`` mixins don't need this module.
+"""
+
+import datetime
+
+import jdatetime
+from django import forms
+from django.db import models
+from django.utils.safestring import mark_safe
+from django_jalali.admin.widgets import AdminjDateWidget
+
+from .jalali import JALALI_DATE_FORMAT, JALALI_DATETIME_FORMAT, parse_jalali, to_jalali, to_jalali_datetime
+
+
+def jalali_display(value, fmt: str = JALALI_DATE_FORMAT) -> str:
+    """Read-only admin cell: Jalali date wrapped LTR so RTL renders cleanly."""
+    text = to_jalali(value, fmt)
+    if not text:
+        return "-"
+    return mark_safe(f'<span dir="ltr">{text}</span>')
+
+
+def jalali_datetime_display(value, fmt: str = JALALI_DATETIME_FORMAT) -> str:
+    """Read-only admin cell: Jalali date+time wrapped LTR."""
+    text = to_jalali_datetime(value, fmt)
+    if not text:
+        return "-"
+    return mark_safe(f'<span dir="ltr">{text}</span>')
+
+
+class JalaliAdminDateWidget(AdminjDateWidget):
+    """Persian datepicker over a *gregorian* ``DateField``.
+
+    Inherits the django-jalali admin datepicker media (jQuery UI calendar) and
+    the ``vjDateField`` class the JS binds to, but converts the incoming
+    gregorian value to a Jalali display string.
+    """
+
+    def __init__(self, attrs=None, format=None):
+        super().__init__(attrs=attrs, format=format or JALALI_DATE_FORMAT)
+
+    def _format_value(self, value):
+        if isinstance(value, datetime.datetime):
+            value = value.date()
+        if isinstance(value, datetime.date) and not isinstance(value, jdatetime.date):
+            value = jdatetime.date.fromgregorian(date=value)
+        return super()._format_value(value)
+
+
+class JalaliFormDateField(forms.DateField):
+    """Form field that reads a Jalali string and stores a gregorian date."""
+
+    widget = JalaliAdminDateWidget
+
+    def to_python(self, value):
+        if value in self.empty_values:
+            return None
+        if isinstance(value, str):
+            try:
+                return parse_jalali(value)
+            except ValueError:
+                pass
+        return super().to_python(value)
+
+
+class JalaliDateAdminMixin:
+    """Mix into a ModelAdmin to give its ``DateField``\\ s a Persian datepicker."""
+
+    formfield_overrides = {
+        models.DateField: {"form_class": JalaliFormDateField, "widget": JalaliAdminDateWidget},
+    }

nilva_django_utils-0.1.0/nilva_django_utils/bank.py

@@ -0,0 +1,43 @@
+"""Bank identifier checksums.
+
+The backends only regex-check IBANs (``^IR\\d{24}$``) and card numbers
+(``^\\d{16}$``); these helpers add the real checksums (ISO 13616 mod-97 and
+Luhn) on top. Input digits may be Persian or Arabic-Indic.
+"""
+
+import re
+
+from .digits import to_english_digits
+
+_IBAN_STRUCTURE_RE = re.compile(r"^[A-Z]{2}\d{2}[A-Z0-9]{1,30}$")
+
+_STRIP_RE = re.compile(r"[\s\-]")
+
+
+def is_valid_iban(value) -> bool:
+    """ISO 13616 mod-97 IBAN check. Iranian IBANs (شبا) are ``IR`` + 24
+    digits; other countries validate too. Accepts spaces/dashes and a
+    leading ``شبا``-less bare form is NOT accepted — the ``IR`` prefix is
+    required."""
+    iban = _STRIP_RE.sub("", to_english_digits(value).strip()).upper()
+    if not _IBAN_STRUCTURE_RE.match(iban):
+        return False
+    rearranged = iban[4:] + iban[:4]
+    numeric = "".join(str(int(char, 36)) for char in rearranged)
+    return int(numeric) % 97 == 1
+
+
+def is_valid_card_number(value) -> bool:
+    """16-digit bank card Luhn check (Iranian cards are Luhn-valid)."""
+    card = _STRIP_RE.sub("", to_english_digits(value).strip())
+    if len(card) != 16 or not card.isdigit() or card == card[0] * 16:
+        return False
+    total = 0
+    for index, char in enumerate(card):
+        digit = int(char)
+        if index % 2 == 0:
+            digit *= 2
+            if digit > 9:
+                digit -= 9
+        total += digit
+    return total % 10 == 0

nilva_django_utils-0.1.0/nilva_django_utils/conf.py

@@ -0,0 +1,27 @@
+"""Settings snippets (pure data — safe to import from a settings module).
+
+``JALALI_SETTINGS`` registers the admin datepicker JS/CSS that
+``django-jalali`` ships, exactly as the Shahab backend does::
+
+    # settings.py
+    from nilva_django_utils.conf import JALALI_SETTINGS  # noqa: F401
+"""
+
+JALALI_SETTINGS = {
+    # JavaScript static files for the admin Jalali date widget
+    "ADMIN_JS_STATIC_FILES": [
+        "admin/jquery.ui.datepicker.jalali/scripts/jquery-1.10.2.min.js",
+        "admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.core.js",
+        "admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.datepicker-cc.js",
+        "admin/jquery.ui.datepicker.jalali/scripts/calendar.js",
+        "admin/jquery.ui.datepicker.jalali/scripts/jquery.ui.datepicker-cc-fa.js",
+        "admin/main.js",
+    ],
+    # CSS static files for the admin Jalali date widget
+    "ADMIN_CSS_STATIC_FILES": {
+        "all": [
+            "admin/jquery.ui.datepicker.jalali/themes/base/jquery-ui.min.css",
+            "admin/css/main.css",
+        ]
+    },
+}

nilva_django_utils-0.1.0/nilva_django_utils/digits.py

@@ -0,0 +1,44 @@
+"""Persian / Arabic-Indic digit normalization.
+
+Every Nilva backend accepts user input typed with Persian (۰-۹) or
+Arabic-Indic (٠-٩) digits and renders numbers back in Persian. These tables
+are the union of the per-project ``str.maketrans`` maps.
+"""
+
+from .numbers import separate_thousands
+
+ASCII_DIGITS = "0123456789"
+PERSIAN_DIGITS = "۰۱۲۳۴۵۶۷۸۹"
+ARABIC_INDIC_DIGITS = "٠١٢٣٤٥٦٧٨٩"
+
+#: Persian and Arabic-Indic digits -> ASCII ("۱۲۳" or "١٢٣" -> "123").
+TO_ENGLISH_TABLE = str.maketrans(PERSIAN_DIGITS + ARABIC_INDIC_DIGITS, ASCII_DIGITS * 2)
+
+#: ASCII and Arabic-Indic digits -> Persian ("123" or "١٢٣" -> "۱۲۳").
+TO_PERSIAN_TABLE = str.maketrans(ASCII_DIGITS + ARABIC_INDIC_DIGITS, PERSIAN_DIGITS * 2)
+
+
+def to_english_digits(text) -> str:
+    """Localized digits (Persian and Arabic-Indic) to ASCII. ``None`` -> ``""``."""
+    if text is None:
+        return ""
+    return str(text).translate(TO_ENGLISH_TABLE)
+
+
+def to_persian_digits(text, separate: bool = False) -> str:
+    """ASCII (and Arabic-Indic) digits to Persian. ``None`` -> ``""``.
+
+    With ``separate=True`` numeric values get thousands separators first
+    (``1234567`` -> ``"۱,۲۳۴,۵۶۷"``).
+    """
+    if text is None:
+        return ""
+    if separate:
+        text = separate_thousands(text)
+    return str(text).translate(TO_PERSIAN_TABLE)
+
+
+def translate_numbers(text, is_separate: bool = False) -> str:
+    """Backwards-compatible alias covering both legacy signatures
+    (``utils.general.number_utils.translate_numbers``)."""
+    return to_persian_digits(text, separate=is_separate)

nilva_django_utils-0.1.0/nilva_django_utils/jalali.py

@@ -0,0 +1,71 @@
+"""Jalali (Persian) calendar formatting and parsing.
+
+Requires ``jdatetime`` (the ``[jalali]`` extra). Dates stay *gregorian* in
+the database and over the API — these helpers only convert at the display /
+input boundary, the convention shared by the Depository and Cheshmeh
+backends. Django is optional: timezone-aware datetimes are localized through
+``django.utils.timezone`` only when Django is installed and configured.
+"""
+
+import datetime
+
+import jdatetime
+
+from .digits import to_english_digits
+
+JALALI_DATE_FORMAT = "%Y-%m-%d"
+JALALI_DATETIME_FORMAT = "%Y-%m-%d %H:%M"
+
+#: Input formats accepted when parsing a Jalali string back to gregorian.
+JALALI_INPUT_FORMATS = (JALALI_DATE_FORMAT, "%Y/%m/%d")
+
+
+def _localtime(value: datetime.datetime) -> datetime.datetime:
+    try:
+        from django.core.exceptions import ImproperlyConfigured
+        from django.utils import timezone
+    except ImportError:
+        return value
+    try:
+        return timezone.localtime(value)
+    except ImproperlyConfigured:
+        return value
+
+
+def to_jalali(value, fmt: str = JALALI_DATE_FORMAT) -> str:
+    """Gregorian date/datetime -> Jalali string (``""`` when empty)."""
+    if value is None:
+        return ""
+    if isinstance(value, datetime.datetime):
+        value = value.date()
+    if isinstance(value, datetime.date) and not isinstance(value, jdatetime.date):
+        value = jdatetime.date.fromgregorian(date=value)
+    if hasattr(value, "strftime"):
+        return value.strftime(fmt)
+    return str(value)
+
+
+def to_jalali_datetime(value, fmt: str = JALALI_DATETIME_FORMAT) -> str:
+    """Gregorian datetime -> Jalali date+time string, localized to the active
+    Django timezone when one is configured (``""`` when empty)."""
+    if value is None:
+        return ""
+    if isinstance(value, datetime.datetime):
+        if value.tzinfo is not None:
+            value = _localtime(value)
+        return jdatetime.datetime.fromgregorian(datetime=value).strftime(fmt)
+    return to_jalali(value, fmt)
+
+
+def parse_jalali(value, formats: tuple = JALALI_INPUT_FORMATS) -> datetime.date:
+    """Jalali date string (any digit script) -> gregorian ``datetime.date``.
+
+    Raises ``ValueError`` when no format matches.
+    """
+    normalized = to_english_digits(value).strip()
+    for fmt in formats:
+        try:
+            return jdatetime.datetime.strptime(normalized, fmt).togregorian().date()
+        except ValueError:
+            continue
+    raise ValueError(f"Not a valid Jalali date: {value!r}")

nilva_django_utils-0.1.0/nilva_django_utils/national_id.py

@@ -0,0 +1,35 @@
+"""Iranian national code (کد ملی) validation.
+
+Implements the real mod-11 weighted checksum (the algorithm behind the
+``codemelli`` package) instead of the ``isdigit()`` / 10-digit-regex checks
+scattered across the backends. Input is digit-normalized first, so a code
+typed as ``۱۰۰۰۰۰۰۰۰۷`` validates the same as ``1000000007``.
+"""
+
+from .digits import to_english_digits
+
+
+def normalize_national_id(value, pad: bool = False) -> str:
+    """Clean ``value`` to an ASCII digit string (localized digits translated,
+    spaces/dashes stripped).
+
+    ``pad=True`` zero-fills 8/9-digit codes back to 10 digits — Excel imports
+    routinely strip leading zeros.
+    """
+    code = to_english_digits(value).strip().replace(" ", "").replace("-", "")
+    if pad and code.isdigit() and 8 <= len(code) < 10:
+        code = code.zfill(10)
+    return code
+
+
+def is_valid_national_id(value, pad: bool = False) -> bool:
+    """True when ``value`` is a structurally valid کد ملی (10 digits, not all
+    identical, mod-11 checksum passes)."""
+    code = normalize_national_id(value, pad=pad)
+    if len(code) != 10 or not code.isdigit():
+        return False
+    if code == code[0] * 10:
+        return False
+    check = int(code[9])
+    remainder = sum(int(code[i]) * (10 - i) for i in range(9)) % 11
+    return check == remainder if remainder < 2 else check == 11 - remainder