pk-cnic 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- pk_cnic-0.1.0/.github/workflows/ci.yml +39 -0
- pk_cnic-0.1.0/.gitignore +5 -0
- pk_cnic-0.1.0/LICENSE +21 -0
- pk_cnic-0.1.0/PKG-INFO +78 -0
- pk_cnic-0.1.0/README.md +56 -0
- pk_cnic-0.1.0/pyproject.toml +35 -0
- pk_cnic-0.1.0/src/pk_cnic/__init__.py +92 -0
- pk_cnic-0.1.0/src/pk_cnic/py.typed +0 -0
- pk_cnic-0.1.0/tests/test_cnic.py +47 -0
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
tags: ["v*"]
|
|
7
|
+
pull_request:
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.14"]
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v4
|
|
17
|
+
- uses: actions/setup-python@v5
|
|
18
|
+
with:
|
|
19
|
+
python-version: ${{ matrix.python-version }}
|
|
20
|
+
- run: pip install . pytest
|
|
21
|
+
- run: pytest -q
|
|
22
|
+
- run: pk-cnic 35202-1234567-1
|
|
23
|
+
|
|
24
|
+
publish:
|
|
25
|
+
if: startsWith(github.ref, 'refs/tags/v')
|
|
26
|
+
needs: test
|
|
27
|
+
runs-on: ubuntu-latest
|
|
28
|
+
environment:
|
|
29
|
+
name: pypi
|
|
30
|
+
url: https://pypi.org/p/pk-cnic
|
|
31
|
+
permissions:
|
|
32
|
+
id-token: write
|
|
33
|
+
steps:
|
|
34
|
+
- uses: actions/checkout@v4
|
|
35
|
+
- uses: actions/setup-python@v5
|
|
36
|
+
with:
|
|
37
|
+
python-version: "3.14"
|
|
38
|
+
- run: pip install build && python -m build
|
|
39
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
pk_cnic-0.1.0/.gitignore
ADDED
pk_cnic-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ali Ahmed
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
pk_cnic-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: pk-cnic
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Validate, normalise and read Pakistani CNIC numbers (13-digit format, region and gender digits, Urdu digits)
|
|
5
|
+
Project-URL: Homepage, https://aliahmed.si/
|
|
6
|
+
Project-URL: Documentation, https://aliahmed.si/blog/pakistan-cnic-number-validation/
|
|
7
|
+
Project-URL: KYC pipeline, https://aliahmed.si/blog/how-kyc-identity-verification-works/
|
|
8
|
+
Project-URL: Urdu OCR, https://aliahmed.si/blog/ocr-non-latin-scripts-arabic-urdu/
|
|
9
|
+
Project-URL: Source, https://github.com/QuantumBreakz/pk-cnic
|
|
10
|
+
Project-URL: Issues, https://github.com/QuantumBreakz/pk-cnic/issues
|
|
11
|
+
Author: Ali Ahmed
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: cnic,identity,kyc,nadra,ocr,pakistan,urdu,validation
|
|
15
|
+
Classifier: Development Status :: 4 - Beta
|
|
16
|
+
Classifier: Intended Audience :: Developers
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
19
|
+
Classifier: Typing :: Typed
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# pk-cnic
|
|
24
|
+
|
|
25
|
+
Validate, normalise and read **Pakistani CNIC numbers** (`12345-1234567-1`). Pure Python, no dependencies, typed.
|
|
26
|
+
|
|
27
|
+
- Accepts the number with or without hyphens and stores one canonical form.
|
|
28
|
+
- Converts Urdu (Extended Arabic-Indic) and Arabic-Indic digits, as produced by OCR or Urdu keyboards.
|
|
29
|
+
- Reads the region from the first digit and the gender from the last (odd male, even female).
|
|
30
|
+
|
|
31
|
+
**A CNIC has no check digit.** Format validation catches badly formed input; it can't tell you the number is real or belongs to the person. Verify identity against NADRA's records.
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install pk-cnic
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from pk_cnic import is_valid, normalize, parse
|
|
43
|
+
|
|
44
|
+
parse("35202-1234567-1")
|
|
45
|
+
# Cnic(number='35202-1234567-1', locality_code='35202', region='Punjab', gender='male')
|
|
46
|
+
|
|
47
|
+
normalize("3520212345671") # '35202-1234567-1'
|
|
48
|
+
normalize("۳۵۲۰۲-۱۲۳۴۵۶۷-۸") # '35202-1234567-8'
|
|
49
|
+
is_valid("35202-12345671") # False: hyphens must be all or none
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`parse` and `normalize` raise `ValueError` for anything that isn't a 13-digit CNIC number.
|
|
53
|
+
|
|
54
|
+
### Command line
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pk-cnic 35202-1234567-1 42101-7654321-2
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Numbers can also be piped on stdin. Exit code is `0` when all are valid and `1` otherwise.
|
|
61
|
+
|
|
62
|
+
## What the digits mean
|
|
63
|
+
|
|
64
|
+
| Part | Digits | Meaning |
|
|
65
|
+
| ------------- | ------ | --------------------------------------------------- |
|
|
66
|
+
| Locality code | 1–5 | First digit is the region; the rest narrow it down |
|
|
67
|
+
| Serial | 6–12 | Sequence number |
|
|
68
|
+
| Last digit | 13 | Odd: male. Even: female |
|
|
69
|
+
|
|
70
|
+
Region by first digit, as commonly documented: 1 Khyber Pakhtunkhwa, 2 FATA (now part of Khyber Pakhtunkhwa), 3 Punjab, 4 Sindh, 5 Balochistan, 6 Islamabad, 7 Gilgit-Baltistan. Use the region and gender digits for consistency checks, not as the source of truth.
|
|
71
|
+
|
|
72
|
+
## Background
|
|
73
|
+
|
|
74
|
+
Why there's no check digit, what to do about it, and where CNIC checks fit in onboarding: [Validating a Pakistani CNIC number](https://aliahmed.si/blog/pakistan-cnic-number-validation/). For the wider verification flow: [How KYC identity verification works](https://aliahmed.si/blog/how-kyc-identity-verification-works/).
|
|
75
|
+
|
|
76
|
+
## License
|
|
77
|
+
|
|
78
|
+
MIT
|
pk_cnic-0.1.0/README.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# pk-cnic
|
|
2
|
+
|
|
3
|
+
Validate, normalise and read **Pakistani CNIC numbers** (`12345-1234567-1`). Pure Python, no dependencies, typed.
|
|
4
|
+
|
|
5
|
+
- Accepts the number with or without hyphens and stores one canonical form.
|
|
6
|
+
- Converts Urdu (Extended Arabic-Indic) and Arabic-Indic digits, as produced by OCR or Urdu keyboards.
|
|
7
|
+
- Reads the region from the first digit and the gender from the last (odd male, even female).
|
|
8
|
+
|
|
9
|
+
**A CNIC has no check digit.** Format validation catches badly formed input; it can't tell you the number is real or belongs to the person. Verify identity against NADRA's records.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
pip install pk-cnic
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
```python
|
|
20
|
+
from pk_cnic import is_valid, normalize, parse
|
|
21
|
+
|
|
22
|
+
parse("35202-1234567-1")
|
|
23
|
+
# Cnic(number='35202-1234567-1', locality_code='35202', region='Punjab', gender='male')
|
|
24
|
+
|
|
25
|
+
normalize("3520212345671") # '35202-1234567-1'
|
|
26
|
+
normalize("۳۵۲۰۲-۱۲۳۴۵۶۷-۸") # '35202-1234567-8'
|
|
27
|
+
is_valid("35202-12345671") # False: hyphens must be all or none
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`parse` and `normalize` raise `ValueError` for anything that isn't a 13-digit CNIC number.
|
|
31
|
+
|
|
32
|
+
### Command line
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pk-cnic 35202-1234567-1 42101-7654321-2
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Numbers can also be piped on stdin. Exit code is `0` when all are valid and `1` otherwise.
|
|
39
|
+
|
|
40
|
+
## What the digits mean
|
|
41
|
+
|
|
42
|
+
| Part | Digits | Meaning |
|
|
43
|
+
| ------------- | ------ | --------------------------------------------------- |
|
|
44
|
+
| Locality code | 1–5 | First digit is the region; the rest narrow it down |
|
|
45
|
+
| Serial | 6–12 | Sequence number |
|
|
46
|
+
| Last digit | 13 | Odd: male. Even: female |
|
|
47
|
+
|
|
48
|
+
Region by first digit, as commonly documented: 1 Khyber Pakhtunkhwa, 2 FATA (now part of Khyber Pakhtunkhwa), 3 Punjab, 4 Sindh, 5 Balochistan, 6 Islamabad, 7 Gilgit-Baltistan. Use the region and gender digits for consistency checks, not as the source of truth.
|
|
49
|
+
|
|
50
|
+
## Background
|
|
51
|
+
|
|
52
|
+
Why there's no check digit, what to do about it, and where CNIC checks fit in onboarding: [Validating a Pakistani CNIC number](https://aliahmed.si/blog/pakistan-cnic-number-validation/). For the wider verification flow: [How KYC identity verification works](https://aliahmed.si/blog/how-kyc-identity-verification-works/).
|
|
53
|
+
|
|
54
|
+
## License
|
|
55
|
+
|
|
56
|
+
MIT
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "pk-cnic"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Validate, normalise and read Pakistani CNIC numbers (13-digit format, region and gender digits, Urdu digits)"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
requires-python = ">=3.10"
|
|
13
|
+
authors = [{ name = "Ali Ahmed" }]
|
|
14
|
+
keywords = ["cnic", "pakistan", "nadra", "kyc", "identity", "validation", "ocr", "urdu"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 4 - Beta",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Topic :: Software Development :: Libraries",
|
|
20
|
+
"Typing :: Typed",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
[project.urls]
|
|
24
|
+
Homepage = "https://aliahmed.si/"
|
|
25
|
+
Documentation = "https://aliahmed.si/blog/pakistan-cnic-number-validation/"
|
|
26
|
+
"KYC pipeline" = "https://aliahmed.si/blog/how-kyc-identity-verification-works/"
|
|
27
|
+
"Urdu OCR" = "https://aliahmed.si/blog/ocr-non-latin-scripts-arabic-urdu/"
|
|
28
|
+
Source = "https://github.com/QuantumBreakz/pk-cnic"
|
|
29
|
+
Issues = "https://github.com/QuantumBreakz/pk-cnic/issues"
|
|
30
|
+
|
|
31
|
+
[project.scripts]
|
|
32
|
+
pk-cnic = "pk_cnic:main"
|
|
33
|
+
|
|
34
|
+
[tool.hatch.version]
|
|
35
|
+
path = "src/pk_cnic/__init__.py"
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"""Validate, normalise and read Pakistani CNIC numbers (12345-1234567-1).
|
|
2
|
+
|
|
3
|
+
Format checks only: a CNIC has no check digit, so a well-formed number can still be
|
|
4
|
+
wrong or belong to someone else. Verify identity against NADRA's records.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import argparse
|
|
10
|
+
import re
|
|
11
|
+
import sys
|
|
12
|
+
from typing import NamedTuple, Sequence
|
|
13
|
+
|
|
14
|
+
__all__ = ["Cnic", "parse", "is_valid", "normalize", "REGIONS", "main"]
|
|
15
|
+
__version__ = "0.1.0"
|
|
16
|
+
|
|
17
|
+
# First digit by region, as commonly documented. A hint for consistency checks, not a source of truth.
|
|
18
|
+
REGIONS = {
|
|
19
|
+
"1": "Khyber Pakhtunkhwa",
|
|
20
|
+
"2": "FATA (now part of Khyber Pakhtunkhwa)",
|
|
21
|
+
"3": "Punjab",
|
|
22
|
+
"4": "Sindh",
|
|
23
|
+
"5": "Balochistan",
|
|
24
|
+
"6": "Islamabad",
|
|
25
|
+
"7": "Gilgit-Baltistan",
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
# Extended Arabic-Indic (Urdu) and Arabic-Indic digits, as produced by OCR or Urdu keyboards.
|
|
29
|
+
_DIGITS = str.maketrans("۰۱۲۳۴۵۶۷۸۹٠١٢٣٤٥٦٧٨٩", "01234567890123456789")
|
|
30
|
+
_SHAPE = re.compile(r"[0-9]{5}-?[0-9]{7}-?[0-9]")
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class Cnic(NamedTuple):
|
|
34
|
+
number: str # canonical form: 12345-1234567-1
|
|
35
|
+
locality_code: str
|
|
36
|
+
region: str
|
|
37
|
+
gender: str # from the last digit: odd male, even female
|
|
38
|
+
|
|
39
|
+
@property
|
|
40
|
+
def digits(self) -> str:
|
|
41
|
+
return self.number.replace("-", "")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def normalize(raw: str) -> str:
|
|
45
|
+
"""Return the canonical hyphenated form. Raises ValueError if the input isn't a CNIC number."""
|
|
46
|
+
text = raw.strip().translate(_DIGITS)
|
|
47
|
+
if not _SHAPE.fullmatch(text) or text.count("-") not in (0, 2):
|
|
48
|
+
raise ValueError(f"not a CNIC number: {raw!r}")
|
|
49
|
+
d = text.replace("-", "")
|
|
50
|
+
return f"{d[:5]}-{d[5:12]}-{d[12]}"
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def parse(raw: str) -> Cnic:
|
|
54
|
+
"""Validate the format of a CNIC number and read what its digits encode."""
|
|
55
|
+
number = normalize(raw)
|
|
56
|
+
d = number.replace("-", "")
|
|
57
|
+
return Cnic(
|
|
58
|
+
number=number,
|
|
59
|
+
locality_code=d[:5],
|
|
60
|
+
region=REGIONS.get(d[0], "unknown"),
|
|
61
|
+
gender="male" if int(d[12]) % 2 else "female",
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
def is_valid(raw: str) -> bool:
|
|
66
|
+
"""True if the input is a well-formed CNIC number (13 digits, hyphens all or none)."""
|
|
67
|
+
try:
|
|
68
|
+
normalize(raw)
|
|
69
|
+
except ValueError:
|
|
70
|
+
return False
|
|
71
|
+
return True
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
75
|
+
parser = argparse.ArgumentParser(prog="pk-cnic", description="Validate and read Pakistani CNIC numbers.")
|
|
76
|
+
parser.add_argument("numbers", nargs="*", help="CNIC numbers; read from stdin if omitted")
|
|
77
|
+
args = parser.parse_args(argv)
|
|
78
|
+
numbers = args.numbers or [line for line in sys.stdin.read().splitlines() if line.strip()]
|
|
79
|
+
status = 0
|
|
80
|
+
for raw in numbers:
|
|
81
|
+
try:
|
|
82
|
+
c = parse(raw)
|
|
83
|
+
except ValueError as exc:
|
|
84
|
+
print(f"invalid {exc}")
|
|
85
|
+
status = 1
|
|
86
|
+
continue
|
|
87
|
+
print(f"ok {c.number} region={c.region} gender={c.gender}")
|
|
88
|
+
return status
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
if __name__ == "__main__":
|
|
92
|
+
sys.exit(main())
|
|
File without changes
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import pytest
|
|
2
|
+
|
|
3
|
+
from pk_cnic import Cnic, is_valid, main, normalize, parse
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def test_parse_hyphenated():
|
|
7
|
+
assert parse("35202-1234567-1") == Cnic("35202-1234567-1", "35202", "Punjab", "male")
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def test_parse_digits_only_normalizes():
|
|
11
|
+
c = parse("3520212345671")
|
|
12
|
+
assert c.number == "35202-1234567-1"
|
|
13
|
+
assert c.digits == "3520212345671"
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def test_gender_digit():
|
|
17
|
+
assert parse("42101-7654321-2").gender == "female"
|
|
18
|
+
assert parse("42101-7654321-2").region == "Sindh"
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def test_urdu_digits():
|
|
22
|
+
assert normalize("۳۵۲۰۲-۱۲۳۴۵۶۷-۸") == "35202-1234567-8"
|
|
23
|
+
assert parse("٣٥٢٠٢١٢٣٤٥٦٧١").number == "35202-1234567-1"
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def test_unknown_region():
|
|
27
|
+
assert parse("91234-1234567-1").region == "unknown"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@pytest.mark.parametrize(
|
|
31
|
+
"bad",
|
|
32
|
+
["35202-1234567", "35202-12345671", "3520-21234567-1", "35202 1234567 1", "35202-1234567-1-", "", "abcde-fghijkl-m", "3520212345671x"],
|
|
33
|
+
)
|
|
34
|
+
def test_invalid(bad):
|
|
35
|
+
assert not is_valid(bad)
|
|
36
|
+
with pytest.raises(ValueError):
|
|
37
|
+
parse(bad)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def test_whitespace_is_trimmed():
|
|
41
|
+
assert is_valid(" 35202-1234567-1\n")
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def test_cli(capsys):
|
|
45
|
+
assert main(["35202-1234567-1"]) == 0
|
|
46
|
+
assert "region=Punjab" in capsys.readouterr().out
|
|
47
|
+
assert main(["35202-1234567"]) == 1
|