pakdatakit 2.2.0__py3-none-any.whl

pakdatakit/__init__.py

@@ -0,0 +1,159 @@
+"""PakDataKit: utilities for Pakistani data.
+
+CNIC, phone, networks, WhatsApp, IBAN, postal codes, geography, address
+parsing, Roman Urdu, Hijri dates, holidays, currency formatting, amounts in
+words, tax numbers, landlines and Raast QR codes.
+
+A Python port of the ``pakdatakit`` npm package: it ships the same datasets and
+is tested against shared test vectors, so both give identical results.
+"""
+
+from .address import ParsedAddress, format_address, parse_address
+from .cnic import CNICInfo, get_cnic_info, validate_cnic
+from .data_version import DATA_VERSION, data_version
+from .format import format_lakh, format_pkr
+from .geo import (
+    get_district_province,
+    get_districts_by_province,
+    get_province,
+    search_cities,
+    search_districts,
+)
+from .hijri import (
+    HijriDate,
+    format_hijri,
+    from_hijri,
+    get_hijri_month_name,
+    is_ramadan,
+    to_hijri,
+)
+from .holidays import Holiday, get_holidays_on, get_pakistan_holidays, is_pakistan_holiday
+from .iban import BankInfo, get_bank_from_iban, get_bank_info, get_banks, validate_iban
+from .input import (
+    check_cnic_input,
+    check_iban_input,
+    check_phone_input,
+    format_cnic_input,
+    format_iban_input,
+    format_phone_input,
+)
+from .networks import get_network
+from .numbers import (
+    NumberInfo,
+    analyze_number,
+    get_area_code,
+    get_number_type,
+    validate_landline,
+)
+from .phone import PhoneAnalysis, analyze_phone, format_phone, validate_phone
+from .postal import (
+    get_city_by_postal_code,
+    get_postal_areas,
+    get_postal_code,
+    get_postal_codes,
+    search_postal_codes,
+)
+from .raast import (
+    EmvField,
+    MerchantAccountInfo,
+    ParsedRaastQr,
+    RaastQrValidation,
+    create_merchant_qr,
+    create_raast_p2p_qr,
+    parse_raast_qr,
+    validate_raast_qr,
+)
+from .tax import NTNInfo, analyze_ntn, validate_ntn, validate_strn
+from .text import normalize_roman_urdu, normalize_text, to_english_digits, to_urdu_digits
+from .whatsapp import create_whatsapp_link
+from .words import amount_in_words, number_to_words
+
+__version__ = "2.2.0"
+
+__all__ = [
+    "__version__",
+    "DATA_VERSION",
+    "data_version",
+    # cnic
+    "CNICInfo",
+    "validate_cnic",
+    "get_cnic_info",
+    # phone
+    "PhoneAnalysis",
+    "validate_phone",
+    "format_phone",
+    "analyze_phone",
+    "get_network",
+    "create_whatsapp_link",
+    # iban
+    "validate_iban",
+    "get_bank_from_iban",
+    "BankInfo",
+    "get_bank_info",
+    "get_banks",
+    # postal
+    "get_city_by_postal_code",
+    "get_postal_code",
+    "get_postal_codes",
+    "get_postal_areas",
+    "search_postal_codes",
+    # geo
+    "get_province",
+    "search_cities",
+    "get_district_province",
+    "search_districts",
+    "get_districts_by_province",
+    # address
+    "ParsedAddress",
+    "parse_address",
+    "format_address",
+    # text
+    "normalize_text",
+    "normalize_roman_urdu",
+    "to_urdu_digits",
+    "to_english_digits",
+    # hijri
+    "HijriDate",
+    "to_hijri",
+    "from_hijri",
+    "format_hijri",
+    "get_hijri_month_name",
+    "is_ramadan",
+    # format / words
+    "format_pkr",
+    "format_lakh",
+    "number_to_words",
+    "amount_in_words",
+    # tax
+    "NTNInfo",
+    "analyze_ntn",
+    "validate_ntn",
+    "validate_strn",
+    # numbers
+    "NumberInfo",
+    "analyze_number",
+    "get_number_type",
+    "validate_landline",
+    "get_area_code",
+    # raast
+    "EmvField",
+    "MerchantAccountInfo",
+    "ParsedRaastQr",
+    "RaastQrValidation",
+    "create_raast_p2p_qr",
+    "create_merchant_qr",
+    "parse_raast_qr",
+    "validate_raast_qr",
+    # holidays
+    "Holiday",
+    "get_pakistan_holidays",
+    "get_holidays_on",
+    "is_pakistan_holiday",
+    # input
+    "format_cnic_input",
+    "check_cnic_input",
+    "format_phone_input",
+    "check_phone_input",
+    "format_iban_input",
+    "check_iban_input",
+]

pakdatakit/_data.py

@@ -0,0 +1,19 @@
+"""Loads the bundled JSON datasets (shared with the npm package)."""
+
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from typing import Any
+
+try:  # Python 3.9+
+    from importlib.resources import files as _files
+except ImportError:  # pragma: no cover
+    _files = None  # type: ignore[assignment]
+
+
+@lru_cache(maxsize=None)
+def load(name: str) -> Any:
+    """Returns the parsed contents of ``pakdatakit/data/<name>``."""
+    text = _files("pakdatakit").joinpath("data").joinpath(name).read_text(encoding="utf-8")
+    return json.loads(text)

pakdatakit/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal helpers. Not part of the public API."""

pakdatakit/_internal/emv.py

@@ -0,0 +1,74 @@
+"""EMVCo Merchant-Presented QR encoding (mirrors src/internal/emv.ts)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional
+
+from .js import utf8_bytes
+
+
+@dataclass(frozen=True)
+class EmvField:
+    """A parsed EMV field. ``children`` is set for template fields."""
+
+    id: str
+    value: str
+    children: Optional[List["EmvField"]] = None
+
+
+class EmvSyntaxError(ValueError):
+    """Malformed EMV data."""
+
+
+def is_template_id(field_id: str) -> bool:
+    n = int(field_id)
+    return 26 <= n <= 51 or n == 62 or n == 64 or 80 <= n <= 99
+
+
+def crc16(text: str) -> str:
+    """CRC-16/CCITT-FALSE (poly 0x1021, init 0xFFFF), as 4 uppercase hex digits."""
+    crc = 0xFFFF
+    for byte in utf8_bytes(text):
+        crc ^= byte << 8
+        for _ in range(8):
+            crc = ((crc << 1) ^ 0x1021) & 0xFFFF if crc & 0x8000 else (crc << 1) & 0xFFFF
+    return format(crc, "04X")
+
+
+def encode_field(field_id: str, value: str) -> str:
+    """Encodes one field. Length counts characters, as the EMV spec requires."""
+    length = len(value)
+    if length > 99:
+        raise ValueError(f"EMV field {field_id} is longer than 99 characters")
+    return f"{field_id}{length:02d}{value}"
+
+
+def _is_digits(text: str) -> bool:
+    return all("0" <= c <= "9" for c in text)
+
+
+def parse_fields(data: str, nested: bool = True) -> List[EmvField]:
+    """Parses EMV fields. Raises ``EmvSyntaxError`` if the data is malformed."""
+    chars = data
+    fields: List[EmvField] = []
+    i = 0
+    while i < len(chars):
+        header = chars[i : i + 4]
+        if len(header) != 4 or not _is_digits(header):
+            raise EmvSyntaxError(f"Malformed EMV field at position {i}")
+        field_id = header[:2]
+        length = int(header[2:])
+        if i + 4 + length > len(chars):
+            raise EmvSyntaxError(f"EMV field {field_id} is truncated")
+        value = chars[i + 4 : i + 4 + length]
+        children = parse_fields(value, False) if nested and is_template_id(field_id) else None
+        fields.append(EmvField(field_id, value, children))
+        i += 4 + length
+    return fields
+
+
+def with_crc(payload: str) -> str:
+    """Appends the CRC field (63) to an encoded payload."""
+    data = f"{payload}6304"
+    return f"{data}{crc16(data)}"

pakdatakit/_internal/js.py

@@ -0,0 +1,200 @@
+"""Helpers that reproduce JavaScript semantics, so results match the npm package.
+
+Python and JavaScript differ in small ways that matter for exact parity:
+whitespace classes, ``Math.round``, number-to-string conversion,
+``toFixed`` rounding, ``Number(string)`` parsing and ``localeCompare``.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import unicodedata
+from decimal import ROUND_HALF_UP, Decimal
+from typing import Any, List, Tuple
+
+#: Characters matched by JavaScript's ``\\s`` and removed by ``String.prototype.trim``.
+WS_CHARS = (
+    "\t\n\x0b\x0c\r   "
+    "           "
+    "

  　"
+)
+
+#: Regex character-class body equivalent to JavaScript's ``\\s``.
+WS = "\\t\\n\\x0b\\x0c\\r \\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff"
+
+MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def trim(value: str) -> str:
+    """``String.prototype.trim``."""
+    return value.strip(WS_CHARS)
+
+
+def trim_end(value: str) -> str:
+    """``String.prototype.trimEnd``."""
+    return value.rstrip(WS_CHARS)
+
+
+def is_number(value: Any) -> bool:
+    """``typeof value === 'number'`` (bools are not numbers in JavaScript)."""
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def is_finite(value: Any) -> bool:
+    """``Number.isFinite``."""
+    if not is_number(value):
+        return False
+    try:
+        return math.isfinite(float(value))
+    except OverflowError:
+        return False
+
+
+def is_integer(value: Any) -> bool:
+    """``Number.isInteger``."""
+    if isinstance(value, bool):
+        return False
+    if isinstance(value, int):
+        return True
+    return isinstance(value, float) and math.isfinite(value) and value.is_integer()
+
+
+def is_safe_integer(value: Any) -> bool:
+    """``Number.isSafeInteger``."""
+    return is_integer(value) and abs(value) <= MAX_SAFE_INTEGER
+
+
+def js_round(value: float) -> int:
+    """``Math.round``: halves round towards positive infinity."""
+    floor = math.floor(value)
+    return floor + 1 if value - floor >= 0.5 else floor
+
+
+def number_to_string(value: float) -> str:
+    """``String(number)`` / template-literal conversion of a number."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int) and abs(value) < 10**21:
+        return str(value)
+    value = float(value)
+    if math.isnan(value):
+        return "NaN"
+    if math.isinf(value):
+        return "Infinity" if value > 0 else "-Infinity"
+    if value == 0:
+        return "0"
+    sign = "-" if value < 0 else ""
+    _, digits_tuple, exponent = Decimal(repr(abs(value))).normalize().as_tuple()
+    digits = "".join(str(d) for d in digits_tuple)
+    k = len(digits)
+    n = int(exponent) + k
+    if k <= n <= 21:
+        text = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        text = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        text = "0." + "0" * (-n) + digits
+    else:
+        e = n - 1
+        exp = ("+" if e >= 0 else "-") + str(abs(e))
+        text = digits + "e" + exp if k == 1 else digits[0] + "." + digits[1:] + "e" + exp
+    return sign + text
+
+
+def to_fixed(value: float, places: int) -> str:
+    """``Number.prototype.toFixed`` (rounds the exact binary value half up)."""
+    value = float(value)
+    if not math.isfinite(value) or abs(value) >= 1e21:
+        return number_to_string(value)
+    if value == 0:
+        return "0." + "0" * places if places else "0"
+    quantum = Decimal(1).scaleb(-places)
+    return format(Decimal(value).quantize(quantum, rounding=ROUND_HALF_UP), "f")
+
+
+_DECIMAL_LITERAL = re.compile(
+    r"[+-]?(?:Infinity|(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][+-]?[0-9]+)?)\Z"
+)
+_RADIX_LITERAL = re.compile(r"0(?:[xX][0-9a-fA-F]+|[oO][0-7]+|[bB][01]+)\Z")
+
+
+def to_number(text: str) -> float:
+    """``Number(string)``: returns ``nan`` where JavaScript returns ``NaN``."""
+    text = trim(text)
+    if text == "":
+        return 0.0
+    if _DECIMAL_LITERAL.match(text):
+        if text.lstrip("+-") == "Infinity":
+            return float("-inf") if text.startswith("-") else float("inf")
+        return float(text)
+    if _RADIX_LITERAL.match(text):
+        return float(int(text, 0))
+    return float("nan")
+
+
+# Root-collation order of ASCII punctuation and symbols (CLDR / ICU), all of
+# which sort before digits and letters.
+_PUNCTUATION = "_-,;:!?.'\"()[]{}@*/\\&#%`^+<=>|~$"
+
+
+def collation_key(text: str) -> Tuple[Any, ...]:
+    """Sort key approximating ``a.localeCompare(b)`` (ICU root collation).
+
+    Compares base letters case- and accent-insensitively first, then accents,
+    then case (lowercase first), like ICU's default strength.
+    """
+    primary: List[Tuple[int, Any]] = []
+    secondary: List[int] = []
+    tertiary: List[int] = []
+    for char in unicodedata.normalize("NFD", text):
+        if unicodedata.combining(char):
+            secondary.append(ord(char))
+            continue
+        if char in WS_CHARS:
+            weight: Tuple[int, Any] = (0, ord(char))
+        elif char in _PUNCTUATION:
+            weight = (1, _PUNCTUATION.index(char))
+        elif char.isdigit():
+            weight = (2, unicodedata.digit(char, 0))
+        elif char.isalpha():
+            weight = (3, char.lower())
+        else:
+            weight = (4, ord(char))
+        primary.append(weight)
+        secondary.append(0)
+        tertiary.append(1 if char.isupper() else 0)
+    return (tuple(primary), tuple(secondary), tuple(tertiary), text)
+
+
+def locale_sorted(values: List[str]) -> List[str]:
+    """``values.sort((a, b) => a.localeCompare(b))``."""
+    return sorted(values, key=collation_key)
+
+
+def object_entries(mapping: Any) -> List[Tuple[str, Any]]:
+    """``Object.entries`` order: integer-like keys ascending, then insertion order."""
+    keys = list(mapping.keys())
+
+    def is_index(key: str) -> bool:
+        return (
+            isinstance(key, str)
+            and key.isascii()
+            and key.isdigit()
+            and (key == "0" or not key.startswith("0"))
+            and int(key) < 2**32 - 1
+        )
+
+    indices = sorted((k for k in keys if is_index(k)), key=int)
+    others = [k for k in keys if not is_index(k)]
+    return [(k, mapping[k]) for k in indices + others]
+
+
+def utf16_length(text: str) -> int:
+    """``string.length`` (UTF-16 code units)."""
+    return sum(2 if ord(c) > 0xFFFF else 1 for c in text)
+
+
+def utf8_bytes(text: str) -> bytes:
+    """``new TextEncoder().encode(text)``: lone surrogates become U+FFFD."""
+    return re.sub("[\ud800-\udfff]", "�", text).encode("utf-8")

pakdatakit/_internal/normalize.py

@@ -0,0 +1,36 @@
+"""Input normalization shared by the modules (mirrors src/internal/normalize.ts)."""
+
+from __future__ import annotations
+
+import re
+
+from .js import WS, trim
+
+_URDU_DIGITS = "۰۱۲۳۴۵۶۷۸۹"
+_ARABIC_INDIC_DIGITS = "٠١٢٣٤٥٦٧٨٩"
+_DIGIT_TABLE = {ord(c): str(i) for i, c in enumerate(_URDU_DIGITS)}
+_DIGIT_TABLE.update({ord(c): str(i) for i, c in enumerate(_ARABIC_INDIC_DIGITS)})
+
+# Whitespace, hyphens and dashes, dots, slashes and parentheses.
+_SEPARATORS = re.compile("[" + WS + r"\-‐‑‒–—./()]")
+_WHITESPACE_RUN = re.compile("[" + WS + "]+")
+
+
+def to_ascii_digits(value: str) -> str:
+    """Converts Urdu (Extended Arabic-Indic) and Arabic-Indic digits to ASCII digits."""
+    return value.translate(_DIGIT_TABLE)
+
+
+def strip_separators(value: str) -> str:
+    """Removes whitespace, hyphens and dashes, dots, slashes and parentheses."""
+    return _SEPARATORS.sub("", value)
+
+
+def normalize_whitespace(value: str) -> str:
+    """Collapses internal whitespace and trims leading/trailing whitespace."""
+    return _WHITESPACE_RUN.sub(" ", trim(value))
+
+
+def normalize_key(value: str) -> str:
+    """Lowercase with collapsed whitespace."""
+    return normalize_whitespace(value).lower()

pakdatakit/_internal/phone_utils.py

@@ -0,0 +1,54 @@
+"""Mobile number normalization (mirrors src/internal/phone-utils.ts)."""
+
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from .._data import load
+from .normalize import strip_separators, to_ascii_digits
+
+_MOBILE = re.compile(r"3[0-9]{9}\Z")
+_allocated: Optional[frozenset] = None
+
+
+def _allocated_prefixes() -> frozenset:
+    global _allocated
+    if _allocated is None:
+        _allocated = frozenset(entry["prefix"] for entry in load("networks.json"))
+    return _allocated
+
+
+def is_allocated_prefix(prefix: str) -> bool:
+    """Whether a ``03XX`` mobile prefix is allocated to an operator."""
+    return prefix in _allocated_prefixes()
+
+
+def normalize_phone_digits(phone: str) -> Optional[str]:
+    """Normalizes a phone string to digits with country code (no leading plus).
+
+    Returns ``None`` when the input is not a Pakistani mobile number on an
+    allocated ``03XX`` prefix.
+    """
+    digits = strip_separators(to_ascii_digits(phone))
+    if digits.startswith("+"):
+        digits = digits[1:]
+    elif digits.startswith("00"):
+        digits = digits[2:]
+    if digits.startswith("92") and len(digits) > 10:
+        digits = digits[2:]
+    if digits.startswith("0"):
+        digits = digits[1:]
+    if not _MOBILE.match(digits):
+        return None
+    if f"0{digits[:3]}" not in _allocated_prefixes():
+        return None
+    return f"92{digits}"
+
+
+def get_phone_prefix(phone: str) -> Optional[str]:
+    """Returns the local mobile prefix (``0XXX``), or ``None`` if invalid."""
+    digits = normalize_phone_digits(phone)
+    if digits is None:
+        return None
+    return f"0{digits[2:5]}"