india-kit 0.1.0__tar.gz

india_kit-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+node_modules/
+dist/
+*.tgz
+.turbo/
+.DS_Store
+pnpm-lock.yaml
+.env
+coverage/
+/.vscode/
+.idea/
+/.cache/

india_kit-0.1.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: india-kit
+Version: 0.1.0
+Summary: The definitive Indian developer toolkit — validate Aadhaar, PAN, GSTIN, IFSC, UPI, pincode and more
+Project-URL: Homepage, https://github.com/Inreal-Solutions/India-kit
+Project-URL: Repository, https://github.com/Inreal-Solutions/India-kit
+Project-URL: Issues, https://github.com/Inreal-Solutions/India-kit/issues
+Author-email: Inreal Solutions <aryan23062001@gmail.com>
+License: MIT
+Keywords: aadhaar,fintech,gst,gstin,ifsc,india,indian,pan,pincode,upi,validate,validator
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# india-kit
+
+The definitive Indian developer toolkit for Python. Validate Aadhaar, PAN, GSTIN, IFSC, UPI, pincode and more — zero dependencies, fully typed.
+
+## Install
+
+```bash
+pip install india-kit
+```
+
+## Usage
+
+```python
+from india_kit import (
+    validate_pan, mask_pan, mock_pan,
+    validate_aadhaar, mock_aadhaar,
+    validate_gstin, mock_gstin,
+    validate_ifsc, lookup_ifsc,
+    validate_upi,
+    validate_pincode, lookup_pincode,
+    split_gst,
+)
+
+validate_pan("ABCDE1234F")      # {"valid": True}
+validate_aadhaar("234123412346") # {"valid": True/False}
+validate_gstin("27ABCDE1234F1Z5") # {"valid": True/False}
+validate_ifsc("SBIN0000001")    # {"valid": True}
+validate_upi("alice@icici")     # {"valid": True}
+validate_pincode("110001")      # {"valid": True}
+
+lookup_ifsc("SBIN0000001")      # {"bank": "State Bank of India", ...}
+lookup_pincode("110001")        # {"district": "Central Delhi", "state": "Delhi"}
+
+split_gst(1000, 18)             # {"cgst": 90.0, "sgst": 90.0, "igst": 0.0, "total_tax": 180.0}
+split_gst(1000, 18, intra_state=False)  # {"cgst": 0.0, "sgst": 0.0, "igst": 180.0, ...}
+
+mask_pan("ABCDE1234F")          # "ABCXX1234F"
+mock_pan()                      # random valid PAN
+mock_aadhaar()                  # random valid Aadhaar
+```
+
+## License
+
+MIT

india_kit-0.1.0/README.md

@@ -0,0 +1,44 @@
+# india-kit
+
+The definitive Indian developer toolkit for Python. Validate Aadhaar, PAN, GSTIN, IFSC, UPI, pincode and more — zero dependencies, fully typed.
+
+## Install
+
+```bash
+pip install india-kit
+```
+
+## Usage
+
+```python
+from india_kit import (
+    validate_pan, mask_pan, mock_pan,
+    validate_aadhaar, mock_aadhaar,
+    validate_gstin, mock_gstin,
+    validate_ifsc, lookup_ifsc,
+    validate_upi,
+    validate_pincode, lookup_pincode,
+    split_gst,
+)
+
+validate_pan("ABCDE1234F")      # {"valid": True}
+validate_aadhaar("234123412346") # {"valid": True/False}
+validate_gstin("27ABCDE1234F1Z5") # {"valid": True/False}
+validate_ifsc("SBIN0000001")    # {"valid": True}
+validate_upi("alice@icici")     # {"valid": True}
+validate_pincode("110001")      # {"valid": True}
+
+lookup_ifsc("SBIN0000001")      # {"bank": "State Bank of India", ...}
+lookup_pincode("110001")        # {"district": "Central Delhi", "state": "Delhi"}
+
+split_gst(1000, 18)             # {"cgst": 90.0, "sgst": 90.0, "igst": 0.0, "total_tax": 180.0}
+split_gst(1000, 18, intra_state=False)  # {"cgst": 0.0, "sgst": 0.0, "igst": 180.0, ...}
+
+mask_pan("ABCDE1234F")          # "ABCXX1234F"
+mock_pan()                      # random valid PAN
+mock_aadhaar()                  # random valid Aadhaar
+```
+
+## License
+
+MIT

india_kit-0.1.0/india_kit/__init__.py

@@ -0,0 +1,19 @@
+from .identity.pan import validate_pan, mask_pan, mock_pan
+from .identity.aadhaar import validate_aadhaar, mock_aadhaar
+from .identity.gstin import validate_gstin, mock_gstin
+from .banking.ifsc import validate_ifsc, lookup_ifsc
+from .banking.upi import validate_upi
+from .address.pincode import validate_pincode, lookup_pincode
+from .finance.gst import split_gst
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "validate_pan", "mask_pan", "mock_pan",
+    "validate_aadhaar", "mock_aadhaar",
+    "validate_gstin", "mock_gstin",
+    "validate_ifsc", "lookup_ifsc",
+    "validate_upi",
+    "validate_pincode", "lookup_pincode",
+    "split_gst",
+]

india_kit-0.1.0/india_kit/address/__init__.py

@@ -0,0 +1,3 @@
+from .pincode import validate_pincode, lookup_pincode
+
+__all__ = ["validate_pincode", "lookup_pincode"]

india_kit-0.1.0/india_kit/address/pincode.py

@@ -0,0 +1,29 @@
+import re
+
+_PINCODE_RE = re.compile(r'^[1-9][0-9]{5}$')
+
+_PINCODE_DB = {
+    "110001": {"district": "Central Delhi", "state": "Delhi"},
+    "400001": {"district": "Mumbai City", "state": "Maharashtra"},
+    "560001": {"district": "Bangalore Urban", "state": "Karnataka"},
+    "600001": {"district": "Chennai", "state": "Tamil Nadu"},
+    "500001": {"district": "Hyderabad", "state": "Telangana"},
+    "700001": {"district": "Kolkata", "state": "West Bengal"},
+    "380001": {"district": "Ahmedabad", "state": "Gujarat"},
+    "411001": {"district": "Pune", "state": "Maharashtra"},
+    "302001": {"district": "Jaipur", "state": "Rajasthan"},
+    "226001": {"district": "Lucknow", "state": "Uttar Pradesh"},
+}
+
+
+def validate_pincode(pin: str) -> dict:
+    if not isinstance(pin, str):
+        return {"valid": False, "reason": "must be a string"}
+    p = pin.strip()
+    if not _PINCODE_RE.match(p):
+        return {"valid": False, "reason": "invalid pincode (must be 6 digits, first digit 1-9)"}
+    return {"valid": True}
+
+
+def lookup_pincode(pin: str) -> dict | None:
+    return _PINCODE_DB.get(pin.strip())

india_kit-0.1.0/india_kit/banking/__init__.py

@@ -0,0 +1,4 @@
+from .ifsc import validate_ifsc, lookup_ifsc
+from .upi import validate_upi
+
+__all__ = ["validate_ifsc", "lookup_ifsc", "validate_upi"]

india_kit-0.1.0/india_kit/banking/ifsc.py

@@ -0,0 +1,25 @@
+import re
+
+_IFSC_RE = re.compile(r'^[A-Z]{4}0[A-Z0-9]{6}$')
+
+_IFSC_DB = {
+    "SBIN0000001": {"bank": "State Bank of India", "branch": "Mumbai Main", "city": "Mumbai"},
+    "HDFC0000002": {"bank": "HDFC Bank", "branch": "Delhi Main", "city": "Delhi"},
+    "ICIC0000003": {"bank": "ICICI Bank", "branch": "Bangalore Main", "city": "Bangalore"},
+    "AXIS0000004": {"bank": "Axis Bank", "branch": "Chennai Main", "city": "Chennai"},
+    "KKBK0000005": {"bank": "Kotak Mahindra Bank", "branch": "Pune Main", "city": "Pune"},
+}
+
+
+def validate_ifsc(ifsc: str) -> dict:
+    if not isinstance(ifsc, str):
+        return {"valid": False, "reason": "must be a string"}
+    i = ifsc.strip().upper()
+    if not _IFSC_RE.match(i):
+        return {"valid": False, "reason": "invalid IFSC format (expected AAAA0XXXXXX)"}
+    return {"valid": True}
+
+
+def lookup_ifsc(ifsc: str) -> dict | None:
+    i = ifsc.strip().upper()
+    return _IFSC_DB.get(i)

india_kit-0.1.0/india_kit/banking/upi.py

@@ -0,0 +1,11 @@
+import re
+
+_UPI_RE = re.compile(r'^[a-zA-Z0-9._+%\-]{2,}@[a-zA-Z]{2,}$')
+
+
+def validate_upi(vpa: str) -> dict:
+    if not isinstance(vpa, str):
+        return {"valid": False, "reason": "must be a string"}
+    if not _UPI_RE.match(vpa.strip()):
+        return {"valid": False, "reason": "invalid UPI VPA format (expected localpart@bank)"}
+    return {"valid": True}

india_kit-0.1.0/india_kit/finance/__init__.py

@@ -0,0 +1,3 @@
+from .gst import split_gst
+
+__all__ = ["split_gst"]

india_kit-0.1.0/india_kit/finance/gst.py

@@ -0,0 +1,6 @@
+def split_gst(amount: float, rate_percent: float, intra_state: bool = True) -> dict:
+    total_tax = round(amount * rate_percent / 100, 2)
+    if intra_state:
+        half = round(total_tax / 2, 2)
+        return {"cgst": half, "sgst": half, "igst": 0.0, "total_tax": total_tax}
+    return {"cgst": 0.0, "sgst": 0.0, "igst": total_tax, "total_tax": total_tax}

india_kit-0.1.0/india_kit/identity/__init__.py

@@ -0,0 +1,9 @@
+from .pan import validate_pan, mask_pan, mock_pan
+from .aadhaar import validate_aadhaar, mock_aadhaar
+from .gstin import validate_gstin, mock_gstin
+
+__all__ = [
+    "validate_pan", "mask_pan", "mock_pan",
+    "validate_aadhaar", "mock_aadhaar",
+    "validate_gstin", "mock_gstin",
+]

india_kit-0.1.0/india_kit/identity/aadhaar.py

@@ -0,0 +1,66 @@
+import random
+
+_D = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+    [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+    [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+    [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+    [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+    [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+    [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+]
+
+_P = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+    [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+    [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+    [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+    [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+    [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+]
+
+_INV = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9]
+
+
+def _verhoeff_check(number: str) -> bool:
+    c = 0
+    for i, ch in enumerate(reversed(number)):
+        c = _D[c][_P[i % 8][int(ch)]]
+    return c == 0
+
+
+def _verhoeff_checksum(number: str) -> int:
+    c = 0
+    padded = number + "0"
+    for i, ch in enumerate(reversed(padded)):
+        c = _D[c][_P[i % 8][int(ch)]]
+    return _INV[c]
+
+
+def validate_aadhaar(aadhaar: str) -> dict:
+    if not isinstance(aadhaar, str):
+        return {"valid": False, "reason": "must be a string"}
+    a = aadhaar.strip().replace(" ", "")
+    if not a.isdigit() or len(a) != 12:
+        return {"valid": False, "reason": "must be exactly 12 digits"}
+    if a[0] in "01":
+        return {"valid": False, "reason": "first digit cannot be 0 or 1"}
+    if not _verhoeff_check(a):
+        return {"valid": False, "reason": "invalid Verhoeff checksum"}
+    return {"valid": True}
+
+
+def mock_aadhaar() -> str:
+    while True:
+        first = str(random.randint(2, 9))
+        rest = ''.join([str(random.randint(0, 9)) for _ in range(10)])
+        base = first + rest
+        check = _verhoeff_checksum(base)
+        candidate = base + str(check)
+        if _verhoeff_check(candidate):
+            return candidate

india_kit-0.1.0/india_kit/identity/gstin.py

@@ -0,0 +1,35 @@
+import re
+import random
+import string
+from .pan import validate_pan, mock_pan
+
+
+_GSTIN_RE = re.compile(r'^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$')
+
+_STATE_CODES = [
+    "01","02","03","04","05","06","07","08","09","10",
+    "11","12","13","14","15","16","17","18","19","20",
+    "21","22","23","24","25","26","27","28","29","30",
+    "31","32","33","34","35","36","37",
+]
+
+
+def validate_gstin(gstin: str) -> dict:
+    if not isinstance(gstin, str):
+        return {"valid": False, "reason": "must be a string"}
+    g = gstin.strip().upper()
+    if not _GSTIN_RE.match(g):
+        return {"valid": False, "reason": "invalid GSTIN format"}
+    embedded_pan = g[2:12]
+    result = validate_pan(embedded_pan)
+    if not result["valid"]:
+        return {"valid": False, "reason": "embedded PAN is invalid"}
+    return {"valid": True}
+
+
+def mock_gstin() -> str:
+    state = random.choice(_STATE_CODES)
+    pan = mock_pan()
+    entity = str(random.randint(1, 9))
+    checksum = random.choice(string.digits + string.ascii_uppercase)
+    return state + pan + entity + "Z" + checksum

india_kit-0.1.0/india_kit/identity/pan.py

@@ -0,0 +1,30 @@
+import re
+import random
+import string
+
+
+_PAN_RE = re.compile(r'^[A-Z]{5}[0-9]{4}[A-Z]$')
+
+_ENTITY_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+
+def validate_pan(pan: str) -> dict:
+    if not isinstance(pan, str):
+        return {"valid": False, "reason": "must be a string"}
+    p = pan.strip().upper()
+    if not _PAN_RE.match(p):
+        return {"valid": False, "reason": "invalid PAN format (expected AAAAA9999A)"}
+    return {"valid": True}
+
+
+def mask_pan(pan: str) -> str:
+    p = pan.strip().upper()
+    return p[:3] + "XX" + p[5:]
+
+
+def mock_pan() -> str:
+    letters = string.ascii_uppercase
+    part1 = ''.join(random.choices(letters, k=5))
+    part2 = ''.join(random.choices(string.digits, k=4))
+    part3 = random.choice(letters)
+    return part1 + part2 + part3

india_kit-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "india-kit"
+version = "0.1.0"
+description = "The definitive Indian developer toolkit — validate Aadhaar, PAN, GSTIN, IFSC, UPI, pincode and more"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Inreal Solutions", email = "aryan23062001@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = [
+  "india", "indian", "aadhaar", "pan", "gstin", "ifsc",
+  "upi", "pincode", "validate", "validator", "fintech", "gst"
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://github.com/Inreal-Solutions/India-kit"
+Repository = "https://github.com/Inreal-Solutions/India-kit"
+Issues = "https://github.com/Inreal-Solutions/India-kit/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["india_kit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

india_kit-0.1.0/tests/test_aadhaar.py

@@ -0,0 +1,22 @@
+from india_kit import validate_aadhaar, mock_aadhaar
+
+
+def test_invalid_short():
+    assert validate_aadhaar("12345678901")["valid"] is False
+
+def test_invalid_letters():
+    assert validate_aadhaar("12345678901X")["valid"] is False
+
+def test_invalid_first_digit_zero():
+    assert validate_aadhaar("012345678901")["valid"] is False
+
+def test_mock_aadhaar_is_valid():
+    for _ in range(50):
+        a = mock_aadhaar()
+        result = validate_aadhaar(a)
+        assert result["valid"] is True, f"mock_aadhaar() returned invalid: {a}"
+
+def test_mock_aadhaar_is_12_digits():
+    a = mock_aadhaar()
+    assert len(a) == 12
+    assert a.isdigit()

india_kit-0.1.0/tests/test_pan.py

@@ -0,0 +1,19 @@
+from india_kit import validate_pan, mask_pan, mock_pan
+
+
+def test_valid_pan():
+    assert validate_pan("ABCDE1234F")["valid"] is True
+
+def test_invalid_pan_short():
+    assert validate_pan("ABCD1234F")["valid"] is False
+
+def test_pan_lowercase_normalized():
+    assert validate_pan("abcde1234f")["valid"] is True
+
+def test_mask_pan():
+    assert mask_pan("ABCDE1234F") == "ABCXX1234F"
+
+def test_mock_pan_is_valid():
+    for _ in range(50):
+        pan = mock_pan()
+        assert validate_pan(pan)["valid"] is True, f"mock_pan() returned invalid PAN: {pan}"

india_kit-0.1.0/tests/test_validators.py

@@ -0,0 +1,63 @@
+from india_kit import (
+    validate_gstin, mock_gstin,
+    validate_ifsc, lookup_ifsc,
+    validate_upi,
+    validate_pincode, lookup_pincode,
+    split_gst,
+)
+
+
+def test_valid_gstin():
+    g = mock_gstin()
+    assert len(g) == 15
+
+def test_invalid_gstin():
+    assert validate_gstin("INVALID")["valid"] is False
+
+def test_valid_ifsc():
+    assert validate_ifsc("SBIN0000001")["valid"] is True
+
+def test_invalid_ifsc():
+    assert validate_ifsc("SBI001")["valid"] is False
+
+def test_lookup_ifsc():
+    result = lookup_ifsc("SBIN0000001")
+    assert result is not None
+    assert result["bank"] == "State Bank of India"
+
+def test_lookup_ifsc_missing():
+    assert lookup_ifsc("XXXX0000000") is None
+
+def test_valid_upi():
+    assert validate_upi("alice@icici")["valid"] is True
+    assert validate_upi("bob.smith@upi")["valid"] is True
+
+def test_invalid_upi():
+    assert validate_upi("@icici")["valid"] is False
+    assert validate_upi("alice@")["valid"] is False
+
+def test_valid_pincode():
+    assert validate_pincode("110001")["valid"] is True
+
+def test_invalid_pincode():
+    assert validate_pincode("011001")["valid"] is False
+    assert validate_pincode("11001")["valid"] is False
+
+def test_lookup_pincode():
+    result = lookup_pincode("110001")
+    assert result is not None
+    assert result["state"] == "Delhi"
+
+def test_split_gst_intra():
+    result = split_gst(1000, 18, intra_state=True)
+    assert result["cgst"] == 90.0
+    assert result["sgst"] == 90.0
+    assert result["igst"] == 0.0
+    assert result["total_tax"] == 180.0
+
+def test_split_gst_inter():
+    result = split_gst(1000, 18, intra_state=False)
+    assert result["cgst"] == 0.0
+    assert result["sgst"] == 0.0
+    assert result["igst"] == 180.0
+    assert result["total_tax"] == 180.0