# PyCache Scanner & Evaluator

This project provides tools to identify, analyze, and report on compiled Python cache files (.pyc) accidentally bundled within PyPI packages.
We use [uv](https://docs.astral.sh/uv/) as package manager.

## Project Structure
`scan_packages_for_cache_files.py`: A multithreaded scanner that inspects local package artifacts (sdists, wheels, eggs, and zips) to detect files within \__pycache__ directories.

`evaluate.py`: A post-processing script that consumes the scanner's output to generate statistical summaries and a dataset of artifacts for further security analysis.

## Usage
### 1. Scan Packages
Scan a local directory containing Python package artifacts. The scanner fetches metadata from PyPI to match the latest versions.

`uv run scan_packages_for_cache_files.py /path/to/packages --workers 8`

Output: Generates `results.json` containing detailed file lists and "phantom cache" detection (cache files missing corresponding source files).

### 2. Evaluate Results

Process the scan results to view high-level statistics and generate a CSV for replication studies.

`uv run evaluate.py`

Output:
- Console Summary: Statistics on .pyc distribution across artifact types and detected Python versions.
- `analyzed_artifacts.csv`: A CSV including Package URLs (purls) and SHA-256 hashes of the artifacts.