carinfo-py 0.1.0__tar.gz

carinfo_py-0.1.0/LICENSE

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

carinfo_py-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: carinfo-py
+Version: 0.1.0
+Summary: A lightweight Python client and scraper for CarInfo vehicle RC details and VIP numbers.
+Author: Bhavya Kachhadiya
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bhavyakachhadiya/carinfo-py
+Project-URL: Repository, https://github.com/bhavyakachhadiya/carinfo-py
+Keywords: carinfo,rc-details,vahan,rto,vehicle-info,vip-numbers,scraper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=3.4.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: build>=0.10.0; extra == "dev"
+Requires-Dist: twine>=4.0.0; extra == "dev"
+Dynamic: license-file
+Dynamic: requires-python
+
+# carinfo-py 🚗⚡
+
+[![PyPI version](https://img.shields.io/pypi/v/carinfo-py.svg)](https://pypi.org/project/carinfo-py/)
+[![Python versions](https://img.shields.io/pypi/pyversions/carinfo-py.svg)](https://pypi.org/project/carinfo-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, high-performance Python library and CLI tool for fetching vehicle registration (RC) details, owner information, RTO data, and VIP/fancy numbers from CarInfo.
+
+---
+
+## ✨ Features
+
+- **No Heavy Browser Required:** Directly decrypts the Next.js AES payload in pure Python using `cryptography`. Up to **10x faster** than browser-based scrapers.
+- **Rich Data Fields:**
+  - Registration Number
+  - Make & Model
+  - Owner Name (Masked for privacy)
+  - Registered RTO Office, Address, State & Phone
+  - Insurance Expiry Date & Flags
+  - Vehicle Catalog Image URL
+- **VIP & Fancy Number Scraper:**
+  - Built-in database of Indian / Gujarat RTO VIP and Fancy numbers (e.g., `0001`–`0009`, `1111`–`9999`, `1000`–`9000`, `0786`, `8055`, palindromes, repeating pairs).
+- **Export Options:** Seamless export to structured **JSON** and **CSV**.
+- **CLI Included:** Comes with a `carinfo` command-line utility for quick terminal lookups.
+
+---
+
+## 📦 Installation
+
+Install from PyPI:
+```bash
+pip install carinfo-py
+```
+
+Or install directly from source / GitHub:
+```bash
+git clone https://github.com/bhavyakachhadiya/carinfo-py.git
+cd carinfo-py
+pip install .
+```
+
+---
+
+## 🚀 Python Library Usage
+
+### 1. Fetch a Single Vehicle
+
+```python
+from carinfo import CarInfoClient
+
+client = CarInfoClient()
+vehicle = client.get_rc_details("GJ11CQ0786")
+
+print("Status:", vehicle.status)                 # Found
+print("Make & Model:", vehicle.make_and_model)   # I20 SPORTZ(O) 1.2 KAPPA MT SE
+print("Owner Name:", vehicle.owner_name)         # S****A A****M
+print("RTO Office:", vehicle.registered_rto)     # Majevadi Darvaja, Junagadh, Gujarat - 362001
+print("Insurance Expiry:", vehicle.insurance_expiry) # 06-Jan-2029
+print("Image URL:", vehicle.image_url)
+```
+
+### 2. Scrape a Sequential Range (e.g., 0001 to 0020)
+
+```python
+from carinfo import CarInfoClient
+
+client = CarInfoClient()
+
+# Scrapes GJ11CQ0001 to GJ11CQ0020, saves to JSON & CSV
+results = client.scrape_range(
+    prefix="GJ11CQ",
+    start=1,
+    end=20,
+    delay_range=(1.2, 2.5), # Randomized polite jitter
+    save_csv="rc_gj11cq.csv",
+    save_json="rc_gj11cq.json"
+)
+
+print(f"Scraped {len(results)} records.")
+```
+
+### 3. Scrape VIP / Fancy Numbers
+
+```python
+from carinfo import CarInfoClient
+
+client = CarInfoClient()
+
+# mode='top' fetches 58 core VIP numbers (0001-0009, 1111-9999, 1000-9000, 0786, 8055...)
+# mode='fancy' fetches 173 extended auction numbers (palindromes, pairs, sequentials)
+vip_records = client.scrape_vip(
+    prefix="GJ03QD",
+    mode="top",
+    save_csv="rc_gj03qd_vip.csv",
+    save_json="rc_gj03qd_vip.json"
+)
+```
+
+---
+
+## 💻 Command Line Interface (CLI)
+
+After installing `carinfo-py`, use the `carinfo` command in your terminal:
+
+### Look up a single car:
+```bash
+carinfo get GJ11CQ0786
+```
+
+### Scrape a range:
+```bash
+carinfo scrape GJ11CQ --start 1 --end 20 --csv rc_gj11cq.csv --json rc_gj11cq.json
+```
+
+### Scrape VIP numbers:
+```bash
+# Top 58 VIP numbers
+carinfo vip GJ11CQ --mode top
+
+# All 173 Fancy auction numbers
+carinfo vip GJ03QD --mode fancy
+```
+
+---
+
+## 📤 How to Build and Publish to PyPI
+
+If you are the package maintainer and want to publish `carinfo-py` to [PyPI](https://pypi.org/):
+
+### 1. Install Build and Publishing Tools
+```bash
+pip install --upgrade build twine
+```
+
+### 2. Build Source Distribution and Wheel
+From the project root directory:
+```bash
+python3 -m build
+```
+This generates `.tar.gz` and `.whl` files inside the `dist/` directory:
+```
+dist/
+├── carinfo_py-0.1.0-py3-none-any.whl
+└── carinfo_py-0.1.0.tar.gz
+```
+
+### 3. Check Package Integrity
+```bash
+twine check dist/*
+```
+
+### 4. Upload to TestPyPI (Recommended First Step)
+To test without affecting production:
+```bash
+twine upload --repository testpypi dist/*
+```
+
+### 5. Upload to Official PyPI
+Once tested, upload to the live Python Package Index:
+```bash
+twine upload dist/*
+```
+*You will be prompted for your PyPI API token (`pypi-...`).*
+
+Users will then be able to install your package via:
+```bash
+pip install carinfo-py
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

carinfo_py-0.1.0/README.md

@@ -0,0 +1,174 @@
+# carinfo-py 🚗⚡
+
+[![PyPI version](https://img.shields.io/pypi/v/carinfo-py.svg)](https://pypi.org/project/carinfo-py/)
+[![Python versions](https://img.shields.io/pypi/pyversions/carinfo-py.svg)](https://pypi.org/project/carinfo-py/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A lightweight, high-performance Python library and CLI tool for fetching vehicle registration (RC) details, owner information, RTO data, and VIP/fancy numbers from CarInfo.
+
+---
+
+## ✨ Features
+
+- **No Heavy Browser Required:** Directly decrypts the Next.js AES payload in pure Python using `cryptography`. Up to **10x faster** than browser-based scrapers.
+- **Rich Data Fields:**
+  - Registration Number
+  - Make & Model
+  - Owner Name (Masked for privacy)
+  - Registered RTO Office, Address, State & Phone
+  - Insurance Expiry Date & Flags
+  - Vehicle Catalog Image URL
+- **VIP & Fancy Number Scraper:**
+  - Built-in database of Indian / Gujarat RTO VIP and Fancy numbers (e.g., `0001`–`0009`, `1111`–`9999`, `1000`–`9000`, `0786`, `8055`, palindromes, repeating pairs).
+- **Export Options:** Seamless export to structured **JSON** and **CSV**.
+- **CLI Included:** Comes with a `carinfo` command-line utility for quick terminal lookups.
+
+---
+
+## 📦 Installation
+
+Install from PyPI:
+```bash
+pip install carinfo-py
+```
+
+Or install directly from source / GitHub:
+```bash
+git clone https://github.com/bhavyakachhadiya/carinfo-py.git
+cd carinfo-py
+pip install .
+```
+
+---
+
+## 🚀 Python Library Usage
+
+### 1. Fetch a Single Vehicle
+
+```python
+from carinfo import CarInfoClient
+
+client = CarInfoClient()
+vehicle = client.get_rc_details("GJ11CQ0786")
+
+print("Status:", vehicle.status)                 # Found
+print("Make & Model:", vehicle.make_and_model)   # I20 SPORTZ(O) 1.2 KAPPA MT SE
+print("Owner Name:", vehicle.owner_name)         # S****A A****M
+print("RTO Office:", vehicle.registered_rto)     # Majevadi Darvaja, Junagadh, Gujarat - 362001
+print("Insurance Expiry:", vehicle.insurance_expiry) # 06-Jan-2029
+print("Image URL:", vehicle.image_url)
+```
+
+### 2. Scrape a Sequential Range (e.g., 0001 to 0020)
+
+```python
+from carinfo import CarInfoClient
+
+client = CarInfoClient()
+
+# Scrapes GJ11CQ0001 to GJ11CQ0020, saves to JSON & CSV
+results = client.scrape_range(
+    prefix="GJ11CQ",
+    start=1,
+    end=20,
+    delay_range=(1.2, 2.5), # Randomized polite jitter
+    save_csv="rc_gj11cq.csv",
+    save_json="rc_gj11cq.json"
+)
+
+print(f"Scraped {len(results)} records.")
+```
+
+### 3. Scrape VIP / Fancy Numbers
+
+```python
+from carinfo import CarInfoClient
+
+client = CarInfoClient()
+
+# mode='top' fetches 58 core VIP numbers (0001-0009, 1111-9999, 1000-9000, 0786, 8055...)
+# mode='fancy' fetches 173 extended auction numbers (palindromes, pairs, sequentials)
+vip_records = client.scrape_vip(
+    prefix="GJ03QD",
+    mode="top",
+    save_csv="rc_gj03qd_vip.csv",
+    save_json="rc_gj03qd_vip.json"
+)
+```
+
+---
+
+## 💻 Command Line Interface (CLI)
+
+After installing `carinfo-py`, use the `carinfo` command in your terminal:
+
+### Look up a single car:
+```bash
+carinfo get GJ11CQ0786
+```
+
+### Scrape a range:
+```bash
+carinfo scrape GJ11CQ --start 1 --end 20 --csv rc_gj11cq.csv --json rc_gj11cq.json
+```
+
+### Scrape VIP numbers:
+```bash
+# Top 58 VIP numbers
+carinfo vip GJ11CQ --mode top
+
+# All 173 Fancy auction numbers
+carinfo vip GJ03QD --mode fancy
+```
+
+---
+
+## 📤 How to Build and Publish to PyPI
+
+If you are the package maintainer and want to publish `carinfo-py` to [PyPI](https://pypi.org/):
+
+### 1. Install Build and Publishing Tools
+```bash
+pip install --upgrade build twine
+```
+
+### 2. Build Source Distribution and Wheel
+From the project root directory:
+```bash
+python3 -m build
+```
+This generates `.tar.gz` and `.whl` files inside the `dist/` directory:
+```
+dist/
+├── carinfo_py-0.1.0-py3-none-any.whl
+└── carinfo_py-0.1.0.tar.gz
+```
+
+### 3. Check Package Integrity
+```bash
+twine check dist/*
+```
+
+### 4. Upload to TestPyPI (Recommended First Step)
+To test without affecting production:
+```bash
+twine upload --repository testpypi dist/*
+```
+
+### 5. Upload to Official PyPI
+Once tested, upload to the live Python Package Index:
+```bash
+twine upload dist/*
+```
+*You will be prompted for your PyPI API token (`pypi-...`).*
+
+Users will then be able to install your package via:
+```bash
+pip install carinfo-py
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the [MIT License](LICENSE).

carinfo_py-0.1.0/carinfo/__init__.py

@@ -0,0 +1,56 @@
+"""CarInfo Python Library: Fetch Indian vehicle RC details and VIP numbers."""
+
+from .client import CarInfo, CarInfoClient
+from .models import VehicleDetails, RtoDetails, InsuranceDetails
+from .transport import BaseTransport, UrllibTransport
+from .providers.base import BaseVehicleProvider
+from .providers.carinfo import CarInfoProvider
+from .exporters import BaseExporter, JsonExporter, CsvExporter
+from .scraper import BatchScraper
+from .vip import get_vip_numbers, TOP_VIP_NUMBERS, EXTENDED_FANCY_NUMBERS
+from .crypto import decrypt_carinfo_payload
+from .exceptions import (
+    CarInfoError,
+    RateLimitError,
+    VehicleNotFoundError,
+    DecryptionError,
+    NetworkError,
+    CarInfoRateLimitError
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main Facade
+    "CarInfo",
+    "CarInfoClient",
+    # Domain Models
+    "VehicleDetails",
+    "RtoDetails",
+    "InsuranceDetails",
+    # Transport Abstraction
+    "BaseTransport",
+    "UrllibTransport",
+    # Provider Abstraction
+    "BaseVehicleProvider",
+    "CarInfoProvider",
+    # Exporters
+    "BaseExporter",
+    "JsonExporter",
+    "CsvExporter",
+    # Scraping Engine
+    "BatchScraper",
+    # VIP Catalogs
+    "get_vip_numbers",
+    "TOP_VIP_NUMBERS",
+    "EXTENDED_FANCY_NUMBERS",
+    # Crypto
+    "decrypt_carinfo_payload",
+    # Exceptions
+    "CarInfoError",
+    "RateLimitError",
+    "VehicleNotFoundError",
+    "DecryptionError",
+    "NetworkError",
+    "CarInfoRateLimitError"
+]

carinfo_py-0.1.0/carinfo/cli.py

@@ -0,0 +1,110 @@
+"""Command-line interface (CLI) for the carinfo package."""
+
+import argparse
+import sys
+from .client import CarInfoClient
+from .models import VehicleDetails
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="carinfo",
+        description="CarInfo Python CLI: Fetch vehicle details and scrape series from CarInfo"
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # Subcommand: get
+    get_parser = subparsers.add_parser("get", help="Fetch details for a single vehicle")
+    get_parser.add_argument("rc", help="Vehicle Registration Number (e.g. GJ11CQ0786)")
+
+    # Subcommand: scrape
+    scrape_parser = subparsers.add_parser("scrape", help="Scrape a range of registration numbers")
+    scrape_parser.add_argument("prefix", help="Series prefix (e.g. GJ11CQ)")
+    scrape_parser.add_argument("--start", type=int, default=1, help="Start number (default: 1)")
+    scrape_parser.add_argument("--end", type=int, default=20, help="End number (default: 20)")
+    scrape_parser.add_argument("--json", dest="json_file", help="Save output to JSON file")
+    scrape_parser.add_argument("--csv", dest="csv_file", help="Save output to CSV file")
+
+    # Subcommand: vip
+    vip_parser = subparsers.add_parser("vip", help="Scrape VIP / fancy numbers for a series")
+    vip_parser.add_argument("prefix", help="Series prefix (e.g. GJ11CQ)")
+    vip_parser.add_argument("--mode", choices=["top", "fancy"], default="top", help="VIP mode: 'top' (58) or 'fancy' (173)")
+    vip_parser.add_argument("--json", dest="json_file", help="Save output to JSON file")
+    vip_parser.add_argument("--csv", dest="csv_file", help="Save output to CSV file")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    client = CarInfoClient()
+
+    if args.command == "get":
+        print(f"Fetching vehicle details for {args.rc}...")
+        res = client.get_rc_details(args.rc)
+        print("\n--- Vehicle Details ---")
+        print(f"RC Number:         {res.rc_number}")
+        print(f"Status:            {res.status}")
+        if res.status == "Found":
+            print(f"Make & Model:      {res.make_and_model}")
+            print(f"Owner Name:        {res.owner_name}")
+            print(f"RTO:               {res.rto_number} ({res.registered_rto})")
+            print(f"State:             {res.state}")
+            print(f"Insurance Expiry:  {res.insurance_expiry or 'N/A'}")
+            if res.image_url:
+                print(f"Image:             {res.image_url}")
+        print("-----------------------\n")
+
+    elif args.command == "scrape":
+        clean_prefix = args.prefix.upper().replace(" ", "")
+        json_out = args.json_file or f"rc_{clean_prefix.lower()}.json"
+        csv_out = args.csv_file or f"rc_{clean_prefix.lower()}.csv"
+
+        print(f"Scraping {clean_prefix} range {args.start:04d} to {args.end:04d}...")
+        print(f"Output: {json_out} / {csv_out}")
+
+        def progress(curr, total, item: VehicleDetails):
+            if item.status == "Found":
+                print(f"[{curr}/{total}] {item.rc_number} ✓ {item.make_and_model} | {item.owner_name}")
+            else:
+                print(f"[{curr}/{total}] {item.rc_number} - {item.status}")
+
+        results = client.scrape_range(
+            clean_prefix,
+            start=args.start,
+            end=args.end,
+            save_csv=csv_out,
+            save_json=json_out,
+            progress_callback=progress
+        )
+        print(f"\nDone! Scraped {len(results)} records.")
+
+    elif args.command == "vip":
+        clean_prefix = args.prefix.upper().replace(" ", "")
+        json_out = args.json_file or f"rc_{clean_prefix.lower()}_vip.json"
+        csv_out = args.csv_file or f"rc_{clean_prefix.lower()}_vip.csv"
+
+        print(f"Scraping VIP numbers for {clean_prefix} (Mode: {args.mode.upper()})...")
+        print(f"Output: {json_out} / {csv_out}")
+
+        def progress(curr, total, item: VehicleDetails):
+            if item.status == "Found":
+                print(f"[{curr}/{total}] {item.rc_number} ✓ {item.make_and_model} | {item.owner_name}")
+            elif item.status == "Unassigned":
+                print(f"[{curr}/{total}] {item.rc_number} ⚪ Unassigned")
+            else:
+                print(f"[{curr}/{total}] {item.rc_number} - {item.status}")
+
+        results = client.scrape_vip(
+            clean_prefix,
+            mode=args.mode,
+            save_csv=csv_out,
+            save_json=json_out,
+            progress_callback=progress
+        )
+        print(f"\nDone! Scraped {len(results)} VIP records.")
+
+
+if __name__ == "__main__":
+    main()

carinfo_py-0.1.0/carinfo/client.py

@@ -0,0 +1,92 @@
+"""High-level facade client for CarInfo."""
+
+from typing import List, Optional, Tuple, Callable
+
+from .models import VehicleDetails
+from .transport import BaseTransport, UrllibTransport
+from .providers.base import BaseVehicleProvider
+from .providers.carinfo import CarInfoProvider
+from .exporters import JsonExporter, CsvExporter, BaseExporter
+from .scraper import BatchScraper
+from .exceptions import CarInfoRateLimitError, CarInfoError, RateLimitError
+
+
+class CarInfoClient:
+    """Unified client for CarInfo API and scraping workflows.
+
+    Example:
+        >>> from carinfo import CarInfoClient
+        >>> client = CarInfoClient()
+        >>> vehicle = client.get_rc_details("GJ11CQ0786")
+        >>> print(vehicle.make_and_model)
+    """
+
+    def __init__(
+        self,
+        provider: Optional[BaseVehicleProvider] = None,
+        transport: Optional[BaseTransport] = None,
+        session_token: Optional[str] = None
+    ):
+        self.transport = transport or UrllibTransport()
+        self.provider = provider or CarInfoProvider(
+            transport=self.transport,
+            session_token=session_token
+        )
+
+    def get_rc_details(self, rc_number: str) -> VehicleDetails:
+        """Fetch details for a single vehicle registration number."""
+        return self.provider.fetch_vehicle(rc_number)
+
+    # Short alias for convenience
+    get = get_rc_details
+
+    def scrape_range(
+        self,
+        prefix: str,
+        start: int = 1,
+        end: int = 20,
+        delay_range: Tuple[float, float] = (1.2, 2.4),
+        save_csv: Optional[str] = None,
+        save_json: Optional[str] = None,
+        progress_callback: Optional[Callable[[int, int, VehicleDetails], None]] = None
+    ) -> List[VehicleDetails]:
+        """Scrape a sequential range of vehicle numbers."""
+        exporters: List[BaseExporter] = []
+        if save_csv:
+            exporters.append(CsvExporter(save_csv))
+        if save_json:
+            exporters.append(JsonExporter(save_json))
+
+        scraper = BatchScraper(
+            provider=self.provider,
+            exporters=exporters,
+            delay_range=delay_range
+        )
+        return scraper.scrape_range(prefix, start, end, progress_callback)
+
+    def scrape_vip(
+        self,
+        prefix: str,
+        mode: str = "top",
+        delay_range: Tuple[float, float] = (1.2, 2.4),
+        save_csv: Optional[str] = None,
+        save_json: Optional[str] = None,
+        progress_callback: Optional[Callable[[int, int, VehicleDetails], None]] = None
+    ) -> List[VehicleDetails]:
+        """Scrape VIP or fancy numbers for a given prefix."""
+        exporters: List[BaseExporter] = []
+        if save_csv:
+            exporters.append(CsvExporter(save_csv))
+        if save_json:
+            exporters.append(JsonExporter(save_json))
+
+        scraper = BatchScraper(
+            provider=self.provider,
+            exporters=exporters,
+            delay_range=delay_range
+        )
+        return scraper.scrape_vip(prefix, mode, progress_callback)
+
+
+# Convenient alias
+CarInfo = CarInfoClient