nilva-django-utils 0.1.0__py3-none-any.whl

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/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/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/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/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/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/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

nilva_django_utils/numbers.py

@@ -0,0 +1,41 @@
+"""Number and duration helpers shared by the Nilva backends."""
+
+import re
+from datetime import timedelta
+from math import floor
+
+UNITS = {"s": "seconds", "m": "minutes", "h": "hours", "d": "days", "w": "weeks"}
+
+_DURATION_RE = re.compile(r"(?P<value>\d+(\.\d+)?)\s*(?P<unit>[smhdw]?)", flags=re.I)
+
+
+def convert_to_seconds(time_str: str, units: str = "smhdw") -> int:
+    """Human-readable duration to seconds: ``"1h30m"`` -> 5400, ``"2d"`` -> 172800.
+
+    A bare number counts as seconds (``"90"`` -> 90). ``units`` restricts which
+    unit letters are honoured.
+    """
+    timedelta_data = {}
+    for match in _DURATION_RE.finditer(str(time_str)):
+        unit = match.group("unit").lower() or "s"
+        if unit in units and unit in UNITS:
+            timedelta_data[UNITS[unit]] = float(match.group("value"))
+    return int(timedelta(**timedelta_data).total_seconds())
+
+
+def separate_thousands(value) -> str:
+    """``1234567`` -> ``"1,234,567"``. Accepts ints, floats and numeric
+    strings; non-numeric text comes back unchanged."""
+    if isinstance(value, str):
+        stripped = value.strip()
+        try:
+            value = int(stripped) if stripped.lstrip("+-").isdigit() else float(stripped)
+        except ValueError:
+            return value
+    return f"{value:,}"
+
+
+def truncate(number, digits: int = 6) -> float:
+    """Truncate (not round) ``number`` to ``digits`` decimal places."""
+    factor = 10**digits
+    return floor(number * factor) / factor

nilva_django_utils/patterns.py

@@ -0,0 +1,38 @@
+"""Canonical regex patterns for Iranian identifiers.
+
+The union of the per-project ``constants.py`` patterns (Cheshmeh, Etka,
+Bazargah, Xpress, Depository). Plain strings so they can be used in model
+``RegexValidator``\\ s, serializers and plain ``re`` alike.
+"""
+
+#: Canonical national spelling: 09xxxxxxxxx.
+IRANIAN_MOBILE_PATTERN = r"^09\d{9}$"
+
+#: Every accepted spelling: 09…, +989…, 00989…, 989…, bare 9… .
+IRANIAN_MOBILE_ANY_PATTERN = r"^(?:\+98|0098|98|0)?9\d{9}$"
+
+#: Hamrahe-Avval (MCI) ranges only (Cheshmeh's MCI_REGEX_PATTERN).
+MCI_MOBILE_PATTERN = r"^0(91[0-9]|99[0-6])\d{7}$"
+
+#: Landline / "static" numbers: 0 + area code + number, 11 digits total.
+LANDLINE_PATTERN = r"^0\d{10}$"
+
+#: International spelling without '+' as stored by some campaigns: 98… .
+INTL_98_PHONE_PATTERN = r"^98\d{9,14}$"
+
+#: Iranian IBAN (شبا): IR + 24 digits. Structure only — use bank.is_valid_iban
+#: for the mod-97 checksum.
+IBAN_PATTERN = r"^IR\d{24}$"
+
+#: 10-digit postal code.
+POSTAL_CODE_PATTERN = r"^\d{10}$"
+
+#: 16-digit bank card. Structure only — use bank.is_valid_card_number for Luhn.
+CARD_NUMBER_PATTERN = r"^\d{16}$"
+
+#: Bank account number.
+ACCOUNT_NUMBER_PATTERN = r"^\d{6,18}$"
+
+#: 10-digit national code. Structure only — use national_id.is_valid_national_id
+#: for the mod-11 checksum.
+NATIONAL_ID_PATTERN = r"^\d{10}$"

nilva_django_utils/phone.py

@@ -0,0 +1,92 @@
+"""Iranian phone-number validation and normalization.
+
+Replaces the four divergent per-project ``PHONE_REGEX_PATTERN`` constants and
+the Bazargah ``PersianPhoneValidator``: every accepted spelling of an Iranian
+mobile (``09…``, ``+989…``, ``00989…``, ``989…``, bare ``9…``) normalizes to
+the canonical national form ``09xxxxxxxxx`` (or E.164 ``+989xxxxxxxxx``).
+Input digits may be Persian or Arabic-Indic.
+
+For non-Iranian / mixed-country numbers, :func:`normalize_phone` validates
+via Google's libphonenumber (the ``[phonenumbers]`` extra) the way the
+Depository backend does.
+"""
+
+import re
+
+from .digits import to_english_digits
+
+IRANIAN_MOBILE_RE = re.compile(r"^(?:\+98|0098|98|0)?(9\d{9})$")
+
+_SEPARATORS_RE = re.compile(r"[\s\-()]")
+
+DEFAULT_REGION = "IR"
+
+
+def _compact(raw) -> str:
+    return _SEPARATORS_RE.sub("", to_english_digits(raw).strip())
+
+
+def normalize_iranian_mobile(raw) -> str:
+    """Any accepted spelling -> canonical ``09xxxxxxxxx``.
+
+    Raises ``ValueError`` when ``raw`` is not an Iranian mobile number.
+    """
+    match = IRANIAN_MOBILE_RE.match(_compact(raw))
+    if not match:
+        raise ValueError(f"Not a valid Iranian mobile number: {raw!r}")
+    return "0" + match.group(1)
+
+
+def to_e164_iranian(raw) -> str:
+    """Any accepted spelling -> E.164 ``+989xxxxxxxxx``."""
+    return "+98" + normalize_iranian_mobile(raw)[1:]
+
+
+def is_valid_iranian_mobile(raw) -> bool:
+    """True when ``raw`` is an Iranian mobile in any accepted spelling."""
+    try:
+        normalize_iranian_mobile(raw)
+    except ValueError:
+        return False
+    return True
+
+
+def normalize_phone(raw, country_code=None) -> str:
+    """Validate + normalize an international number to E.164 using
+    libphonenumber (``[phonenumbers]`` extra).
+
+    * ``+…`` / ``00…`` input is validated as-is.
+    * ``09…`` is always treated as an Iranian mobile.
+    * Other national numbers parse against ``country_code`` (default Iran).
+
+    Empty input comes back unchanged; invalid numbers raise ``ValueError``.
+    """
+    try:
+        import phonenumbers
+    except ImportError as exc:  # pragma: no cover - exercised via unit test mock
+        raise ImportError(
+            "normalize_phone requires the 'phonenumbers' package — install nilva-django-utils[phonenumbers]"
+        ) from exc
+
+    if raw is None:
+        return raw
+    compact = _compact(raw)
+    if not compact:
+        return compact
+    if compact.startswith("00"):
+        compact = "+" + compact[2:]
+
+    if compact.startswith("+"):
+        region = None
+    elif compact.startswith("09"):
+        region = DEFAULT_REGION
+    else:
+        region = (country_code or DEFAULT_REGION).upper()
+
+    try:
+        number = phonenumbers.parse(compact, region)
+    except phonenumbers.NumberParseException as exc:
+        raise ValueError(f"Not a valid phone number: {raw!r}") from exc
+    if not phonenumbers.is_valid_number(number):
+        raise ValueError(f"Not a valid phone number for its country: {raw!r}")
+    return phonenumbers.format_number(number, phonenumbers.PhoneNumberFormat.E164)

nilva_django_utils/validators.py

@@ -0,0 +1,56 @@
+"""Django validators for Iranian identifiers (the ``[django]`` extra).
+
+Function validators run the real checksums (national code mod-11, IBAN
+mod-97, card Luhn); the ``RegexValidator`` instances mirror the structure-only
+checks the backends already use, with one canonical pattern each. All work in
+DRF serializers too — DRF converts Django ``ValidationError``\\ s.
+"""
+
+from django.core.exceptions import ValidationError
+from django.core.validators import RegexValidator
+from django.utils.translation import gettext_lazy as _
+
+from . import patterns
+from .bank import is_valid_card_number, is_valid_iban
+from .national_id import is_valid_national_id
+from .phone import is_valid_iranian_mobile
+
+
+def validate_national_id(value):
+    """Structural + mod-11 checksum validation of a کد ملی."""
+    if not is_valid_national_id(value):
+        raise ValidationError(_("Enter a valid national code."), code="invalid_national_id")
+
+
+def validate_iranian_mobile(value):
+    """Any accepted spelling of an Iranian mobile (09…, +989…, 00989…, 989…)."""
+    if not is_valid_iranian_mobile(value):
+        raise ValidationError(_("Enter a valid Iranian mobile number."), code="invalid_phone")
+
+
+def validate_iban(value):
+    """Iranian IBAN (شبا) structure + ISO 13616 mod-97 checksum."""
+    if not is_valid_iban(value):
+        raise ValidationError(_("Enter a valid IBAN."), code="invalid_iban")
+
+
+def validate_card_number(value):
+    """16-digit bank card structure + Luhn checksum."""
+    if not is_valid_card_number(value):
+        raise ValidationError(_("Enter a valid card number."), code="invalid_card_number")
+
+
+iranian_mobile_regex_validator = RegexValidator(
+    regex=patterns.IRANIAN_MOBILE_PATTERN, message=_("Phone number is not valid")
+)
+mci_mobile_regex_validator = RegexValidator(regex=patterns.MCI_MOBILE_PATTERN, message=_("Phone number is not valid"))
+landline_regex_validator = RegexValidator(regex=patterns.LANDLINE_PATTERN, message=_("Phone number is not valid"))
+iban_regex_validator = RegexValidator(regex=patterns.IBAN_PATTERN, message=_("IBAN is not valid"))
+postal_code_regex_validator = RegexValidator(regex=patterns.POSTAL_CODE_PATTERN, message=_("Postal code is not valid"))
+card_number_regex_validator = RegexValidator(regex=patterns.CARD_NUMBER_PATTERN, message=_("Card number is not valid"))
+account_number_regex_validator = RegexValidator(
+    regex=patterns.ACCOUNT_NUMBER_PATTERN, message=_("Account number is not valid")
+)
+national_id_regex_validator = RegexValidator(
+    regex=patterns.NATIONAL_ID_PATTERN, message=_("National code is not valid")
+)

nilva_django_utils-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,16 @@
+nilva_django_utils/__init__.py,sha256=FoeAa_S0_lO4wYQyGQvg-V_hJkgAvOwPnUEVy5QvvcU,1735
+nilva_django_utils/admin.py,sha256=Ax0pLdweHqRSI-f6P8xBbIp4p8WZDwc0t8M1AXTRYEI,2908
+nilva_django_utils/bank.py,sha256=DE7rn9gp78jxGI12BbPqyUxvXY4LLJwUPZSInKmlSNM,1443
+nilva_django_utils/conf.py,sha256=u5-TejRf2Zm_0XuVV4aTCWMGqftBqBpnJD1a6Nak6d8,1052
+nilva_django_utils/digits.py,sha256=n1YanqlPRxWoj-d7CX_Md4NtcpbbnBh-4HTZYJMa8PI,1607
+nilva_django_utils/jalali.py,sha256=zkxFYL5dfc1gUM09vwDrXH66teTwnhLZwjkYjMEPe3c,2508
+nilva_django_utils/national_id.py,sha256=SnaxKo4o8JJd8kTsmDPXzWvn-t3p-EDuZX2cfD0HxEU,1383
+nilva_django_utils/numbers.py,sha256=BXj2kPBx7sY03Ak1OtgFSbZUIT-y6Terdd8Kf_zRoDI,1475
+nilva_django_utils/patterns.py,sha256=0UlP92EFtHY868PiZQQvMfgRc6p149p-I0yEYb8sXIc,1352
+nilva_django_utils/phone.py,sha256=W-PpQ9a3wfEIZ8kTd8AdUkWLPAFYfPMyG6u2B2738nc,3083
+nilva_django_utils/validators.py,sha256=ah_0szHrtAPvTUO3yvV0rR7B34K2bAFCpDD7t9Ule78,2600
+nilva_django_utils-0.1.0.dist-info/licenses/LICENSE,sha256=GaZw6y1gmDVsgrV6Kbba2e0GWozUuG_DP41_BT7fHUg,1061
+nilva_django_utils-0.1.0.dist-info/METADATA,sha256=yx3Zu1-TXmmPfU98yxNpgDOw8duLKbXOp-KuD6oPEm0,6290
+nilva_django_utils-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+nilva_django_utils-0.1.0.dist-info/top_level.txt,sha256=-JJLTX01Mm4wlckXnnkKXdL89WlMAajkyzXg3Jr_OwQ,19
+nilva_django_utils-0.1.0.dist-info/RECORD,,

nilva_django_utils-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nilva_django_utils-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+nilva_django_utils