California License Plate Checker

A Python CLI application demonstrating asynchronous programming, worker queues, HTTP sessions, testing, and CLI design. It validates batches of California personalized license plate candidates, optionally generates ideas with OpenAI, and writes structured CSV results.

This project is intended as an educational async Python portfolio project. Use it responsibly: keep worker counts low, avoid high-volume requests, respect public-service websites, and do not treat results as official DMV records.

Features

• Asynchronous workers with asyncio and aiohttp
• Concurrent queue processing for batch plate checks
• Input validation for normalized 2-7 character alphanumeric candidates
• Optional OpenAI generation from a topic prompt
• Optional leet-style expansion with --expand
• CSV export for structured results
• Automated tests and CI with pytest and GitHub Actions

Setup

git clone https://github.com/brivera2524/california-plate-checker.git
cd california-plate-checker
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
pip install -r requirements-dev.txt

To use OpenAI topic generation, create a .env file:

OPENAI_API_KEY=your_api_key_here

Usage

Run with a text file of plate candidates:

python -m plate_checker -i test_plates.txt -o results.csv -w 5

Generate candidates from a topic with OpenAI:

python -m plate_checker -t surfing -n 20 -o results.csv -w 5

Expand candidates with leet-style substitutions before checking:

python -m plate_checker -i test_plates.txt -o results.csv --expand

run.py is also available as a convenience wrapper:

python run.py -i test_plates.txt -o results.csv

Arguments

Short	Long	Description	Default
-i	--input	Input file with plate candidates	Required if not using -t
-t	--topic	Generate plate ideas with OpenAI	Required if not using -i
-n	--num-plates	Number of OpenAI candidates to generate	Required with -t
-o	--output	Output CSV file	Required
-w	--workers	Number of concurrent workers	10
-e	--expand	Expand candidates using letter/number substitutions	Disabled

Testing

python -m pytest --basetemp .pytest-tmp

Tests use mocked worker sessions and OpenAI responses. No live DMV or OpenAI requests are required for CI.

Project Structure

.
|-- README.md
|-- run.py
|-- test_plates.txt
|-- pytest.ini
|-- plate_checker/
|   |-- __main__.py
|   |-- config.py
|   |-- plate_generator.py
|   |-- utils.py
|   `-- worker.py
|-- tests/
|   |-- test_main.py
|   |-- test_plate_generator.py
|   |-- test_utils.py
|   `-- test_worker.py
|-- requirements.txt
`-- requirements-dev.txt