Metadata-Version: 2.5
Name: indiaid
Version: 0.1.0
Summary: Comprehensive, zero-dependency validation and masking library for Indian IDs and documents.
Project-URL: Homepage, https://github.com/username/indiaid
Project-URL: Documentation, https://github.com/username/indiaid#readme
Project-URL: Repository, https://github.com/username/indiaid
Project-URL: Issues, https://github.com/username/indiaid/issues
Project-URL: Changelog, https://github.com/username/indiaid/blob/main/CHANGELOG.md
Author: IndiaID Contributors
License: MIT
License-File: LICENSE
Keywords: aadhaar,driving-licence,fintech,gstin,ifsc,india,kyc,pan,passport,pincode,validation,voter-id
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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 :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Provides-Extra: all
Requires-Dist: django>=4.2; extra == 'all'
Requires-Dist: pydantic>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pydantic>=2.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: django
Requires-Dist: django>=4.2; extra == 'django'
Provides-Extra: pydantic
Requires-Dist: pydantic>=2.0; extra == 'pydantic'
Description-Content-Type: text/markdown

# IndiaID 🇮🇳

[![PyPI version](https://img.shields.io/pypi/v/indiaid.svg)](https://pypi.org/project/indiaid/)
[![Python versions](https://img.shields.io/pypi/pyversions/indiaid.svg)](https://pypi.org/project/indiaid/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**IndiaID** is a lightweight, zero-dependency Python library for validating, parsing, and masking Indian government IDs, identity numbers, and document codes.

Designed for FinTechs, KYC onboarding pipelines, HRMS, and modern web applications.

---

## ✨ Features

- ⚡ **Zero Runtime Dependencies**: Pure Python 3.9+ standard library.
- 🧮 **Algorithmic Validation**: Verhoeff algorithm for Aadhaar, Luhn mod-36 for GSTIN.
- 🎭 **Privacy & Masking**: UIDAI-compliant Aadhaar masking (`XXXXXXXX1234`).
- 🧩 **Metadata Extraction**: Parse state, entity type (PAN), issue year (DL), and circle.
- 🔌 **Framework Integrations**: First-class support for **Pydantic v2**, **Django**, and **DRF**.
- 🛡️ **Fully Type-Hinted**: PEP 561 compliant (`py.typed`) with strict typing.

---

## 📦 Installation

```bash
pip install indiaid
```

With optional integrations:
```bash
# With Pydantic v2 support
pip install "indiaid[pydantic]"

# With Django support
pip install "indiaid[django]"

# With all integrations
pip install "indiaid[all]"
```

---

## 🚀 Quickstart

### 1. Direct Document Imports (Most Popular)

Import document validators directly:

```python
from indiaid import pan, aadhaar, gstin

# Validate directly (returns True / False)
pan.is_valid("ABCPE1234F")          # True
aadhaar.is_valid("3675 9834 6215")  # True (checks Verhoeff checksum)

# Or use callable shortcut
if pan("ABCPE1234F"):
    print("Valid PAN!")

# Mask for privacy / compliance
pan.mask("ABCPE1234F")              # "ABXXXXXX4F"
aadhaar.mask("3675 9834 6215")      # "XXXXXXXX6215"
```

### 2. Rich Validation & Metadata Extraction

```python
from indiaid import validate

# Parse PAN details
result = validate("pan", "ABCPE1234F")
if result.is_valid:
    print(result.cleaned_value)       # "ABCPE1234F"
    print(result.metadata["entity_type"])  # "Individual"
    print(result.metadata["surname_initial"]) # "E"

# Parse GSTIN details
result = validate("gstin", "27ABCPE1234F1Z5")
if result.is_valid:
    print(result.metadata["state_code"])  # "27"
    print(result.metadata["state_name"])  # "Maharashtra"
    print(result.metadata["pan"])         # "ABCPE1234F"

# Vehicle State Lookup
from indiaid import vehicle
print(vehicle.state("MH01A2925"))   # "Maharashtra"
print(vehicle.state("MH"))          # "Maharashtra"
print(vehicle.state("22BH1234AA"))  # "Bharat Series (All India)"
```

### 3. Masking for Privacy Compliance

```python
import indiaid

# Mask Aadhaar for UIDAI/RBI compliance
masked = indiaid.mask("aadhaar", "3675 9834 6215")
print(masked)  # "XXXXXXXX6215"
```

---

## 📑 Supported Documents

| Document | Type Key | Algorithm / Checks | Masking |
| :--- | :--- | :--- | :---: |
| **Aadhaar** | `aadhaar` | Verhoeff checksum, starting digit rules | ✅ |
| **PAN Card** | `pan` | Entity type, surname initial, sequence | ✅ |
| **GSTIN** | `gstin` | State code, embedded PAN, Luhn mod-36 | ✅ |
| **Passport** | `passport` | 8-character Indian passport format | ✅ |
| **Driving Licence** | `driving_licence`, `dl` | State RTO code, year validation | ❌ |
| **Voter ID (EPIC)** | `voter_id`, `epic` | 10-char standard + legacy formats | ✅ |
| **Vehicle RC** | `vehicle`, `rc` | State RTO codes + Bharat (BH) series | ❌ |
| **Bank IFSC** | `ifsc` | RBI 11-char alphanumeric format | ❌ |
| **Mobile Phone** | `phone` | Indian 10-digit mobile series | ✅ |
| **Pincode** | `pincode` | 6-digit postal circle validation | ❌ |

---

## 🛠️ Framework Integrations

### Pydantic v2

```python
from pydantic import BaseModel
from indiaid.integrations.pydantic import AadhaarStr, PanStr, GstinStr

class UserKYC(BaseModel):
    pan: PanStr
    aadhaar: AadhaarStr
    gstin: GstinStr
```

### Django Models & Forms

```python
from django.db import models
from indiaid.integrations.django import validate_pan, validate_aadhaar

class Profile(models.Model):
    pan = models.CharField(max_length=10, validators=[validate_pan])
    aadhaar = models.CharField(max_length=12, validators=[validate_aadhaar])
```

---

## 📄 License

MIT © IndiaID Contributors
