Metadata-Version: 2.5
Name: pakdatakit
Version: 2.3.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.get_divisions("Sindh")                    # ['Hyderabad', 'Karachi', 'Larkana', ...]
pdk.get_division_of_district("Kasur")         # 'Lahore'
pdk.get_tehsils("Rawalpindi")                 # ['Gujar Khan', 'Kahuta', ..., 'Murree', ...]
pdk.get_tehsil_district("Murree")             # 'Rawalpindi'
pdk.parse_address("House 12, Street 5, Model Town Lahore 54000")

pdk.get_city_by_postal_code("54660")          # 'Lahore'
pdk.get_post_office("48330")
# PostOffice(code='48330', office='Dulmial', town='Dulmial', district=None, province='Punjab')

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`.

Geography:

| Function                                     | Returns                                                               |
| -------------------------------------------- | --------------------------------------------------------------------- |
| `get_province(city)`                         | Province of a city, or `None`                                         |
| `search_cities(query)`                       | Matching city names, sorted                                           |
| `get_district_province(district)`            | Province of a district, or `None`                                     |
| `search_districts(query)`                    | Matching district names, sorted                                       |
| `get_districts_by_province(province)`        | Districts of a province, sorted                                       |
| `get_divisions(province=None)`               | The 30 divisions of the 2023 census, or those of one province, sorted |
| `get_division_of_district(district)`         | Division of a 2023 census district, or `None`                         |
| `get_tehsils(district)`                      | Tehsils (talukas, sub-divisions) of a district, sorted                |
| `get_tehsil_district(tehsil, province=None)` | Census district of a tehsil, or `None` if unknown or ambiguous        |

Divisions and tehsils come from the 2023 census. Each of the 591 tehsils is
recorded under the district it was in at the census, so `get_tehsils` and
`get_tehsil_district` use census districts (`Rawalpindi` still lists Murree,
and a tehsil of `Quetta` is reported under `Quetta`). Districts created after
the census have no division and may have no tehsils. Azad Jammu and Kashmir
and Gilgit-Baltistan are not covered.

Postal codes:

| Function                        | Returns                                                                                                  |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `get_city_by_postal_code(code)` | City of a post code, or `None` (only cities on pakdatakit's city list)                                   |
| `get_postal_code(city)`         | Primary (GPO) post code of a city, or `None`                                                             |
| `get_postal_codes(city)`        | All post codes of a city, sorted                                                                         |
| `get_postal_areas(city)`        | Post office names of a city, sorted                                                                      |
| `search_postal_codes(query)`    | City post codes matching a city, office name or code prefix, sorted                                      |
| `get_post_office(code)`         | `PostOffice` for any delivery post office, or `None`                                                     |
| `search_post_offices(query)`    | `PostOffice`s whose office name or town contains the query, or whose code starts with it, sorted by code |

`get_city_by_postal_code` only answers for post offices in a city on
pakdatakit's city list (`54660` is Lahore); the code of an office in another
town or village returns `None`. `get_post_office` and `search_post_offices`
cover every delivery office in Pakistan Post's directory (about 2,560),
including towns and villages, as `PostOffice(code, office, town, district,
province)`. `district` is set only when the town is the headquarters a
district is named after.

`BankInfo.type` is one of `commercial`, `public-sector`, `islamic`,
`microfinance`, `digital`, `emi`, `foreign`, `specialized` or `central`.
`BankInfo.active` is `False` for a bank that merged into another or has closed.

`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
