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).
