pakdatakit 2.2.0__tar.gz

pakdatakit-2.2.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+build/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+uv.lock

pakdatakit-2.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PakDataKit Contributors
+
+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.

pakdatakit-2.2.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: pakdatakit
+Version: 2.2.0
+Summary: Utilities for Pakistani data: CNIC, phone, IBAN, postal codes, address parsing, Hijri dates, holidays, amounts in words and Raast QR codes
+Project-URL: Homepage, https://github.com/chmuzamil/pakdatakit
+Project-URL: Documentation, https://github.com/chmuzamil/pakdatakit#readme
+Project-URL: Repository, https://github.com/chmuzamil/pakdatakit
+Project-URL: Issues, https://github.com/chmuzamil/pakdatakit/issues
+Project-URL: Changelog, https://github.com/chmuzamil/pakdatakit/blob/main/CHANGELOG.md
+Author: Muzamil Chaudhery
+License-Expression: MIT
+License-File: LICENSE
+Keywords: address,amount-in-words,cnic,hijri,holidays,iban,ntn,pakistan,phone,postal,qr,raast,urdu
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# PakDataKit for Python
+
+Utilities for Pakistani data: CNIC, mobile numbers and networks, WhatsApp links,
+IBAN, postal codes, cities and districts, address parsing, Roman Urdu, Hijri
+dates, public holidays, rupee formatting, amounts in words, NTN/STRN,
+landlines and Raast QR codes.
+
+This is the Python port of the [`pakdatakit` npm package](https://github.com/chmuzamil/pakdatakit).
+It ships **the same datasets** and is tested against **shared test vectors**
+generated from the TypeScript library, so both give identical results.
+Pure Python, no dependencies, Python 3.9+.
+
+## Install
+
+```sh
+pip install pakdatakit
+```
+
+## Examples
+
+```python
+import datetime as dt
+import pakdatakit as pdk
+
+pdk.validate_cnic("35202-1234567-1")          # True
+pdk.get_cnic_info("35202-1234567-1")
+# CNICInfo(digits='3520212345671', formatted='35202-1234567-1', province='Punjab', gender='male')
+
+pdk.format_phone("0300 1234567")              # '+923001234567'
+pdk.get_network("0345-1234567")               # 'Telenor'
+pdk.create_whatsapp_link("03001234567", "Salam!")
+
+pdk.validate_iban("PK36 SCBL 0000 0011 2345 6702")       # True
+pdk.get_bank_from_iban("PK36SCBL0000001123456702")       # 'Standard Chartered Bank (Pakistan) Limited'
+pdk.get_bank_info("MEZN").type                           # 'islamic'
+
+pdk.get_province("Lahore")                    # 'Punjab'
+pdk.parse_address("House 12, Street 5, Model Town Lahore 54000")
+
+pdk.format_pkr(150000)                        # 'Rs. 150,000'
+pdk.format_lakh(2500000)                      # '25 Lakh'
+pdk.amount_in_words(125000, cheque=True)      # 'Rupees One Lakh Twenty-Five Thousand Only'
+pdk.number_to_words(125000, language="ur")    # 'ایک لاکھ پچیس ہزار'
+
+pdk.format_hijri(dt.date(2026, 3, 1))         # '12 Ramadan 1447'
+pdk.get_pakistan_holidays(2026)[0]            # Holiday(id='kashmir-day', ...)
+
+payload = pdk.create_raast_p2p_qr("PK36SCBL0000001123456702", amount=1500, expires_in="1d")
+pdk.validate_raast_qr(payload).valid          # True
+
+pdk.format_cnic_input("3520212")              # '35202-12'
+pdk.check_phone_input("0300 12")              # 'incomplete'
+```
+
+## API
+
+Every function of the npm package is available under its snake_case name
+(`validateCNIC` → `validate_cnic`, `createRaastP2PQr` → `create_raast_p2p_qr`).
+Option objects become keyword arguments (`{ expiresIn: '1d' }` →
+`expires_in="1d"`), structured results are frozen dataclasses with snake_case
+fields, `null` is `None`, and a `RangeError` is a `ValueError`. Dates are
+`datetime.date` / naive local `datetime.datetime`.
+
+`DATA_VERSION` gives the date the datasets were last checked, and
+`__version__` the package version.
+
+See the [main README](https://github.com/chmuzamil/pakdatakit#readme) for the full API
+reference and [DATA.md](https://github.com/chmuzamil/pakdatakit/blob/main/DATA.md)
+for where each dataset comes from.
+
+## Development
+
+From `python/`:
+
+```sh
+uv run --with pytest pytest -q
+```
+
+The data files in `src/pakdatakit/data/` and the vectors in `../test-vectors/`
+are generated from the TypeScript package; don't edit them by hand. From the
+repository root:
+
+```sh
+npm run build && node scripts/generate-test-vectors.mjs
+```
+
+## License
+
+MIT

pakdatakit-2.2.0/README.md

@@ -0,0 +1,89 @@
+# PakDataKit for Python
+
+Utilities for Pakistani data: CNIC, mobile numbers and networks, WhatsApp links,
+IBAN, postal codes, cities and districts, address parsing, Roman Urdu, Hijri
+dates, public holidays, rupee formatting, amounts in words, NTN/STRN,
+landlines and Raast QR codes.
+
+This is the Python port of the [`pakdatakit` npm package](https://github.com/chmuzamil/pakdatakit).
+It ships **the same datasets** and is tested against **shared test vectors**
+generated from the TypeScript library, so both give identical results.
+Pure Python, no dependencies, Python 3.9+.
+
+## Install
+
+```sh
+pip install pakdatakit
+```
+
+## Examples
+
+```python
+import datetime as dt
+import pakdatakit as pdk
+
+pdk.validate_cnic("35202-1234567-1")          # True
+pdk.get_cnic_info("35202-1234567-1")
+# CNICInfo(digits='3520212345671', formatted='35202-1234567-1', province='Punjab', gender='male')
+
+pdk.format_phone("0300 1234567")              # '+923001234567'
+pdk.get_network("0345-1234567")               # 'Telenor'
+pdk.create_whatsapp_link("03001234567", "Salam!")
+
+pdk.validate_iban("PK36 SCBL 0000 0011 2345 6702")       # True
+pdk.get_bank_from_iban("PK36SCBL0000001123456702")       # 'Standard Chartered Bank (Pakistan) Limited'
+pdk.get_bank_info("MEZN").type                           # 'islamic'
+
+pdk.get_province("Lahore")                    # 'Punjab'
+pdk.parse_address("House 12, Street 5, Model Town Lahore 54000")
+
+pdk.format_pkr(150000)                        # 'Rs. 150,000'
+pdk.format_lakh(2500000)                      # '25 Lakh'
+pdk.amount_in_words(125000, cheque=True)      # 'Rupees One Lakh Twenty-Five Thousand Only'
+pdk.number_to_words(125000, language="ur")    # 'ایک لاکھ پچیس ہزار'
+
+pdk.format_hijri(dt.date(2026, 3, 1))         # '12 Ramadan 1447'
+pdk.get_pakistan_holidays(2026)[0]            # Holiday(id='kashmir-day', ...)
+
+payload = pdk.create_raast_p2p_qr("PK36SCBL0000001123456702", amount=1500, expires_in="1d")
+pdk.validate_raast_qr(payload).valid          # True
+
+pdk.format_cnic_input("3520212")              # '35202-12'
+pdk.check_phone_input("0300 12")              # 'incomplete'
+```
+
+## API
+
+Every function of the npm package is available under its snake_case name
+(`validateCNIC` → `validate_cnic`, `createRaastP2PQr` → `create_raast_p2p_qr`).
+Option objects become keyword arguments (`{ expiresIn: '1d' }` →
+`expires_in="1d"`), structured results are frozen dataclasses with snake_case
+fields, `null` is `None`, and a `RangeError` is a `ValueError`. Dates are
+`datetime.date` / naive local `datetime.datetime`.
+
+`DATA_VERSION` gives the date the datasets were last checked, and
+`__version__` the package version.
+
+See the [main README](https://github.com/chmuzamil/pakdatakit#readme) for the full API
+reference and [DATA.md](https://github.com/chmuzamil/pakdatakit/blob/main/DATA.md)
+for where each dataset comes from.
+
+## Development
+
+From `python/`:
+
+```sh
+uv run --with pytest pytest -q
+```
+
+The data files in `src/pakdatakit/data/` and the vectors in `../test-vectors/`
+are generated from the TypeScript package; don't edit them by hand. From the
+repository root:
+
+```sh
+npm run build && node scripts/generate-test-vectors.mjs
+```
+
+## License
+
+MIT

pakdatakit-2.2.0/RELEASING.md

@@ -0,0 +1,51 @@
+# Releasing the Python package
+
+The Python package `pakdatakit` is published to PyPI by
+`.github/workflows/release-python.yml` when a tag like `python-v2.2.0` is
+pushed. It uses [PyPI trusted publishing](https://docs.pypi.org/trusted-publishers/),
+so no API token is stored. See the repository's [RELEASING.md](../RELEASING.md)
+for the release order across all packages.
+
+## Before tagging
+
+- The version in `pyproject.toml` and `src/pakdatakit/__init__.py` matches the
+  npm `pakdatakit` version being released.
+- If data changed, `src/pakdatakit/data_version.py` matches `src/data-version.ts`.
+- Regenerate and commit the shared test vectors and data copies:
+
+  ```bash
+  npm run build
+  node scripts/generate-test-vectors.mjs
+  ```
+
+  CI and the release workflow fail if `test-vectors/` or
+  `python/src/pakdatakit/data/` differ from what this produces.
+
+## What the workflow does
+
+1. Checks the tag matches `pyproject.toml`.
+2. Rebuilds the TypeScript library, regenerates the vectors and data, and fails
+   if they differ from the committed files.
+3. Runs the tests on Python 3.9 and 3.13.
+4. Builds the wheel and sdist with `uv build` and publishes them to PyPI.
+5. Creates a GitHub release.
+
+## One-time setup
+
+On [pypi.org](https://pypi.org) → **Your account** → **Publishing** → **Add a
+new pending publisher** → **GitHub**:
+
+- PyPI project name: `pakdatakit`
+- Owner: `chmuzamil`
+- Repository name: `pakdatakit`
+- Workflow name: `release-python.yml`
+- Environment name: `pypi`
+
+## Testing locally
+
+```bash
+cd python
+uv run --python 3.9 --with pytest pytest -q
+uv run --python 3.13 --with pytest pytest -q
+uv build
+```

pakdatakit-2.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pakdatakit"
+version = "2.2.0"
+description = "Utilities for Pakistani data: CNIC, phone, IBAN, postal codes, address parsing, Hijri dates, holidays, amounts in words and Raast QR codes"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Muzamil Chaudhery" }]
+keywords = [
+  "pakistan", "cnic", "phone", "iban", "postal", "hijri", "urdu",
+  "address", "ntn", "raast", "qr", "holidays", "amount-in-words",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/chmuzamil/pakdatakit"
+Documentation = "https://github.com/chmuzamil/pakdatakit#readme"
+Repository = "https://github.com/chmuzamil/pakdatakit"
+Issues = "https://github.com/chmuzamil/pakdatakit/issues"
+Changelog = "https://github.com/chmuzamil/pakdatakit/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pakdatakit"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/pakdatakit", "tests", "README.md", "RELEASING.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pakdatakit-2.2.0/src/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-2.2.0/src/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-2.2.0/src/pakdatakit/_internal/__init__.py

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

pakdatakit-2.2.0/src/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)}"