indiaid 0.1.0__tar.gz

indiaid-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    name: Build distribution and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/indiaid
+    permissions:
+      id-token: write  # Mandatory for PyPI Trusted Publishing via OIDC
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build sdist and wheel
+        run: |
+          python -m build
+
+      - name: Check package distribution
+        run: |
+          twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

indiaid-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,47 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,all]"
+
+      - name: Run linting
+        run: |
+          ruff check .
+
+      - name: Run type checking
+        run: |
+          mypy src
+
+      - name: Run tests with coverage
+        run: |
+          pytest --cov=indiaid --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        continue-on-error: true
+        with:
+          file: ./coverage.xml

indiaid-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+.venv/
+ENV/
+env/
+
+# IDE & editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing & coverage
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff / Linters
+.ruff_cache/

indiaid-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+- Initial project structure with `src/` layout and PEP 561 typing support (`py.typed`).
+- Core registry architecture with string-based and direct validator access.
+- Validators for:
+  - Aadhaar (Verhoeff checksum, starting digit rules, UIDAI compliant masking)
+  - PAN (Structure check, entity type parsing, last name initial check)
+  - GSTIN (15-character check, state code, PAN embedded verification, Luhn mod-36 checksum)
+  - Passport (8-character Indian passport format)
+  - Driving Licence (State RTO code, year validation)
+  - Voter ID / EPIC (Standard & legacy formats)
+  - Vehicle Registration Number (State RTO formats & Bharat Series)
+  - Bank IFSC (RBI structure check)
+  - Mobile Phone (Indian 10-digit formats with prefixes)
+  - Pincode (6-digit postal code & postal circle validation)
+- Integrations:
+  - Pydantic v2 custom types
+  - Django & Django REST Framework validators

indiaid-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to IndiaID
+
+Thank you for your interest in contributing to `indiaid`! We welcome contributions for adding new document types, improving validation rules, writing tests, or adding framework integrations.
+
+## Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/username/indiaid.git
+   cd indiaid
+   ```
+
+2. Create and activate a virtual environment:
+   ```bash
+   python -m venv .venv
+   # Windows:
+   .venv\Scripts\activate
+   # Linux/macOS:
+   source .venv/bin/activate
+   ```
+
+3. Install in editable mode with development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Adding a New Document Type
+
+To add support for a new Indian document:
+
+1. Create a validator file in `src/indiaid/validators/<doc_name>.py`.
+2. Inherit from `BaseValidator` in `src/indiaid/base.py`.
+3. Use the `@register("<doc_name>", "<alias>")` decorator.
+4. Implement:
+   - `validate(self, value: str) -> ValidationResult`
+   - `mask(self, value: str) -> str` (if applicable)
+5. Export the validator in `src/indiaid/validators/__init__.py`.
+6. Add comprehensive unit tests in `tests/test_<doc_name>.py`.
+7. Document the validation rules in `docs/supported_documents.md`.
+
+## Running Tests and Linting
+
+Run tests:
+```bash
+pytest
+```
+
+Run code formatting and linting:
+```bash
+ruff check .
+ruff format .
+```
+
+Run static type checking:
+```bash
+mypy src
+```

indiaid-0.1.0/LICENSE

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

indiaid-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+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

indiaid-0.1.0/README.md

@@ -0,0 +1,150 @@
+# 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