autouncle-scraper 0.1.0__tar.gz

autouncle_scraper-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Something isn't working
+title: ""
+labels: bug
+assignees: ""
+---
+
+**Command or code**
+The exact CLI command or Python snippet that triggered the issue.
+
+**Expected behavior**
+What you expected to happen.
+
+**Actual behavior**
+What happened instead - include the full error/traceback if there is one.
+
+**Environment**
+- `autouncle-scraper` version (`autouncle-scraper --version` or `autouncle_scraper.__version__`):
+- Python version:
+- OS:
+
+**Additional context**
+If relevant, the raw response body you got back from AutoUncle (search page HTML,
+detail page HTML, or GraphQL response) - especially useful for anything that looks
+like a markup/API shape change on AutoUncle's end, since several parts of this
+scraper (see docs/REFERENCE.md's "maintenance risk" section) are only as stable
+as AutoUncle's own frontend markup.

autouncle_scraper-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["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 "requests~=2.34" "beautifulsoup4~=4.12" \
+                      "pytest~=9.1" "pytest-cov~=7.1" "responses~=0.26" \
+                      "ruff~=0.15" "mypy~=2.1" "types-requests~=2.33" "types-beautifulsoup4~=4.12"
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Mypy
+        run: mypy autouncle_scraper.py
+
+      - name: Unit tests (no network, e2e excluded)
+        run: pytest

autouncle_scraper-0.1.0/.github/workflows/e2e.yml

@@ -0,0 +1,30 @@
+name: E2E
+
+on:
+  workflow_dispatch: {}
+  schedule:
+    # Weekly, Monday 06:00 UTC - catches drift between AutoUncle's live
+    # markup/API shape and this scraper's fixtures/regexes early, without
+    # gating every PR on the live site's availability.
+    - cron: "0 6 * * 1"
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    continue-on-error: true # live-site scraping is inherently flaky; never block merges on it
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "requests~=2.34" "beautifulsoup4~=4.12" \
+                      "pytest~=9.1" "pytest-cov~=7.1" "responses~=0.26"
+
+      - name: End-to-end tests against the live site
+        run: pytest -m e2e --no-cov

autouncle_scraper-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,90 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Verify __version__ matches the pushed tag
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          python - <<'EOF'
+          import re
+          import sys
+
+          tag = "${{ github.ref_name }}".lstrip("v")
+          # A dry-run pre-release tag (e.g. v0.1.0-rc1) is expected to match
+          # __version__ on its base version only - the "-rc1" suffix is just
+          # a marker to route it through TestPyPI, not a real version bump.
+          base_version = tag.split("-", 1)[0]
+          content = open("autouncle_scraper.py").read()
+          match = re.search(r'__version__\s*=\s*"([^"]+)"', content)
+          version = match.group(1) if match else None
+
+          print(f"tag={tag!r} base_version={base_version!r} __version__={version!r}")
+          if version != base_version:
+              print("::error::__version__ does not match the pushed tag - fix before releasing")
+              sys.exit(1)
+          EOF
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC) - no token stored anywhere
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: publish-testpypi
+    # Only ever publish to real PyPI for an actual vX.Y.Z tag push (never for
+    # a manual workflow_dispatch run, and never for a pre-release-suffixed
+    # tag like v0.1.0-rc1 used to dry-run this workflow).
+    if: startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

autouncle_scraper-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+.env
+.venv/
+venv/
+*.csv
+*.json
+!tests/fixtures/*.json
+.DS_Store

autouncle_scraper-0.1.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-21
+
+Initial release.
+
+### Added
+
+- Scraper for autouncle.ch used-car listings, usable both as a CLI
+  (`autouncle-scraper` / `python autouncle_scraper.py`) and as a library
+  (`from autouncle_scraper import scrape`) with the same call shape as the
+  [AutoScout24 scraper](https://github.com/danyk20/autoscout24-scraper) this
+  project is a drop-in-compatible sibling of.
+- Search by any brand/model (resolved dynamically against AutoUncle's own
+  `/api/v4/car_search_form/config` endpoint, not a hardcoded list), with
+  optional price/mileage/first-registration-year range filters.
+- Two independent search mechanisms, chosen automatically: schema.org
+  JSON-LD pagination for unfiltered searches (the richest, most stable
+  source), and a reverse-engineered GraphQL + Next.js RSC mechanism for
+  filtered searches (AutoUncle suppresses JSON-LD on any filtered page).
+- Full-detail mode (default): visits every matching listing individually to
+  extract every field its detail page exposes - full address, AutoUncle's
+  own price-rating/market-analysis labels, a complete price-history time
+  series (a field AutoScout24 doesn't expose at all), full image gallery,
+  and an equipment/spec breakdown - generically flattened for CSV output.
+  `--no-detail`/`detail=False` for a faster, summary-only pass on
+  unfiltered searches.
+- Every listing's raw JSON and flattened CSV row both carry a direct `url`
+  back to the original ad.
+- `domain` parameter (default `"ch"`) so the API host/locale/URL segment
+  aren't hardcoded to Switzerland, in case another AutoUncle country site is
+  wired up in the future.
+- `ScrapeResult` dataclass return value (`.rows`, `.listings`, `.to_csv()`,
+  `.to_json()`) for library use, with the CLI as a thin wrapper around the
+  same `scrape()` function.
+- Console script entry point (`autouncle-scraper`) and `pip install` support
+  via `pyproject.toml` packaging metadata; `--version` flag.
+- Logging-based output (`-v`/`--verbose`, `-q`/`--quiet`) instead of bare
+  `print()`, so library consumers can configure/suppress it via the
+  standard `logging` module.
+- Full type hints throughout, checked with mypy; linted and formatted with
+  Ruff.
+- Unit test suite (100% coverage, all HTTP mocked, all fixtures real
+  captures from the live site) plus a smaller end-to-end suite against the
+  real live site, run on a separate weekly GitHub Actions schedule.
+- CI (GitHub Actions) running lint, type-check, and the unit suite on every
+  push/PR against Python 3.13.
+- MIT license with an explicit statement welcoming AI agents/bots to use the
+  project under the same terms as a human developer.
+- Project governance docs: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`,
+  `SECURITY.md`, issue/PR templates, `docs/REFERENCE.md`.

autouncle_scraper-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and maintainers pledge to make participation in
+this project a harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex characteristics,
+gender identity and expression, level of experience, education,
+socio-economic status, nationality, personal appearance, race, religion, or
+sexual identity and orientation. This applies equally to human contributors
+and to AI agents/bots acting on someone's behalf.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to maintainer@danielkosc.eu. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

autouncle_scraper-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing
+
+Thanks for considering a contribution — human or AI agent, both welcome (see
+the [License](README.md#license) section of the README).
+
+## Dev setup
+
+```bash
+git clone https://github.com/danyk20/autouncle-scraper.git
+cd autouncle-scraper
+pipenv install --dev
+```
+
+## Before opening a PR
+
+```bash
+pipenv run ruff check .                 # lint
+pipenv run ruff format .                # format
+pipenv run mypy autouncle_scraper.py    # type-check
+pipenv run pytest                       # unit tests, must stay at 100% coverage
+```
+
+If your change touches request/response handling against the real site, also
+run the end-to-end suite (real network calls, a few seconds):
+
+```bash
+pipenv run pytest -m e2e --no-cov
+```
+
+## Expectations
+
+- **Every behavior change needs a test.** The unit suite mocks all HTTP (via
+  `responses`) and enforces 100% coverage — a change without a test will
+  fail CI on that basis alone.
+- **Keep `verbose`/logging output backward compatible** unless the PR is
+  specifically about changing it — other code (and the e2e/CLI tests)
+  depends on the current message wording.
+- If AutoUncle changes its markup or API shape, prefer fixing the affected
+  function directly over adding a workaround — the module docstring in
+  `autouncle_scraper.py` documents the current mechanisms, and
+  `docs/REFERENCE.md`'s "maintenance risk" section lists exactly which bits
+  are most likely to need attention first.
+- Keep the change minimal and focused; this is a small single-file utility
+  by design, same as the AutoScout24 scraper it mirrors.
+
+## If the site's markup changes
+
+Several parts of this scraper (the RSC listing-id regex, the BeautifulSoup
+equipment/gallery selectors, the exact `CarSearchInput` GraphQL field list)
+were derived empirically by watching what AutoUncle's own frontend does,
+not from any published API contract — so they can break if AutoUncle ships
+a redesign. To re-derive them:
+
+1. Open the relevant page in a real browser (search page with the filter
+   form, or a detail page).
+2. Monkey-patch `window.fetch` before interacting, so you can see exactly
+   what the page's own JavaScript sends and receives:
+   ```js
+   const _f = window.fetch;
+   window.fetch = function(...args) {
+     console.log('FETCH', args[0], args[1] && args[1].body);
+     return _f.apply(this, args);
+   };
+   ```
+3. Toggle **one** filter control at a time (price, then km, then year, ...)
+   and read the logged GraphQL request body to (re)learn field names.
+4. For the RSC listing-id pattern: fetch a search URL with header
+   `{"RSC": "1"}`, save the raw response text, and diff a few different
+   real captures (different brand/model/filter combinations) before
+   changing the regex — see `tests/fixtures/rsc_*.txt` for the shape these
+   should take.
+5. For BeautifulSoup selectors: prefer stable `data-*` attributes or
+   structural shape (e.g. "an `<li>` with exactly two `<span>` children")
+   over CSS class names, which are build-hashed and change on every deploy.
+
+## Questions / bug reports
+
+Open a GitHub issue using the bug report template — include the exact
+command you ran and, if relevant, the raw HTML/JSON response you got back.
+
+## Releasing (maintainer only)
+
+Publishing to PyPI is automated via `.github/workflows/release.yml` using
+PyPI Trusted Publishing (no API tokens stored anywhere) — pushing a tag is
+the only manual step. **This requires a one-time setup that hasn't been
+done for this project yet**: a Trusted Publisher registered on both
+pypi.org and test.pypi.org for this repository, and matching GitHub
+Environments named `pypi`/`testpypi`. Until that's done, `release.yml` will
+build successfully but fail at the publish step.
+
+1. Bump `__version__` in `autouncle_scraper.py`.
+2. Add a new entry at the top of `CHANGELOG.md` (Keep a Changelog format).
+3. Commit those two changes, then tag and push:
+   ```bash
+   git commit -am "Release vX.Y.Z"
+   git tag vX.Y.Z
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+4. The release workflow verifies `__version__` matches the tag (fails fast
+   if they disagree), builds, publishes to TestPyPI, then to real PyPI.
+   Watch the Actions tab.
+5. To dry-run the pipeline without a real release, push a pre-release tag
+   instead (e.g. `vX.Y.Z-rc1`) — it publishes to TestPyPI only and never
+   reaches real PyPI, since the version/tag check and the real-PyPI job
+   both key off an exact `vX.Y.Z` tag.

autouncle_scraper-0.1.0/LICENSE

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

autouncle_scraper-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: autouncle-scraper
+Version: 0.1.0
+Summary: Free, keyless scraper and library for autouncle.ch used-car listings. Unofficial, not affiliated with AutoUncle ApS.
+Project-URL: Homepage, https://github.com/danyk20/autouncle-scraper
+Project-URL: Repository, https://github.com/danyk20/autouncle-scraper
+Project-URL: Issues, https://github.com/danyk20/autouncle-scraper/issues
+Project-URL: Changelog, https://github.com/danyk20/autouncle-scraper/blob/master/CHANGELOG.md
+Author-email: Daniel Košč <maintainer@danielkosc.eu>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: autouncle,cars,cli,scraper,switzerland,web-scraping
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: beautifulsoup4~=4.12
+Requires-Dist: requests~=2.34
+Provides-Extra: dev
+Requires-Dist: mypy~=2.1; extra == 'dev'
+Requires-Dist: pytest-cov~=7.1; extra == 'dev'
+Requires-Dist: pytest~=9.1; extra == 'dev'
+Requires-Dist: responses~=0.26; extra == 'dev'
+Requires-Dist: ruff~=0.15; extra == 'dev'
+Requires-Dist: types-beautifulsoup4~=4.12; extra == 'dev'
+Requires-Dist: types-requests~=2.33; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AutoUncle Scraper
+
+[![CI](https://github.com/danyk20/autouncle-scraper/actions/workflows/ci.yml/badge.svg)](https://github.com/danyk20/autouncle-scraper/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/autouncle-scraper)](https://pypi.org/project/autouncle-scraper/)
+[![Coverage](https://img.shields.io/badge/unit%20test%20coverage-100%25-brightgreen)](#testing)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.13](https://img.shields.io/badge/python-3.13-blue)](https://www.python.org/)
+
+> Unofficial, independently developed project — not affiliated with, endorsed by, or sponsored by AutoUncle ApS. "AutoUncle" is a trademark of its respective owner.
+
+Fetches every listing for a given brand/model from AutoUncle — for free, no
+API key, no paid scraping service. It's a drop-in-compatible sibling of the
+[AutoScout24 scraper](https://github.com/danyk20/autoscout24-scraper): same
+`scrape()` call shape, same `ScrapeResult` return type, same CLI flags, same
+MIT license and tooling — switch `from autoscout24_scraper import scrape` to
+`from autouncle_scraper import scrape` and the rest of your code doesn't
+need to change.
+
+Under the hood the two projects work differently, because the two sites do:
+AutoScout24 exposes one clean JSON API; AutoUncle is a Next.js site with no
+such API, so this scraper reads the same structured data (schema.org
+JSON-LD) and, for filtered searches, the same internal data mechanism
+(GraphQL + React Server Components) AutoUncle's own frontend uses — all
+reverse-engineered by observing real traffic, documented in full in the
+module docstring and [docs/REFERENCE.md](docs/REFERENCE.md).
+
+**A stronger legal footing than most scrapers.** AutoUncle's own detail
+pages explicitly mark their listing data as a `Dataset` with
+`"isAccessibleForFree": true`, licensed
+[**CC BY 4.0**](https://creativecommons.org/licenses/by/4.0/). That's not
+just "we call their own frontend's endpoint" reasoning (though that's true
+too, same as AutoScout24) — it's AutoUncle's own explicit declaration that
+this data is meant to be freely reused, with attribution.
+
+**🤖 Robot-friendly.** This project is explicitly intended to be run, read,
+imported, or adapted by AI agents and bots, same as a human developer — see
+[License](#license).
+
+## Setup
+
+Requires [pipenv](https://pipenv.pypa.io/) (`brew install pipenv`).
+
+```bash
+git clone https://github.com/danyk20/autouncle-scraper.git
+cd autouncle-scraper
+pipenv install --dev
+```
+
+Contributing, linting, and testing commands: see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Usage
+
+### CLI
+
+```bash
+pipenv run python autouncle_scraper.py --make VW --model Golf
+```
+
+Prints progress, then writes `vw_golf.csv` and `vw_golf.json` in the current
+directory. Installed via `pip install` instead? Drop `pipenv run` — the same
+command is `autouncle-scraper --make VW --model Golf`.
+
+| Flag | Description |
+|---|---|
+| `--version` | Print the installed version and exit |
+| `--make` | Brand name, e.g. `VW` (required) |
+| `--model` | Model name, e.g. `Golf` (required) |
+| `--domain` | Country domain (default `ch`) — only `ch` is implemented today, see [docs/REFERENCE.md](docs/REFERENCE.md#domains) |
+| `--category` | `car` (default) — the only category implemented |
+| `--out` | Output file base name, without extension. Defaults to `<make>_<model>` |
+| `--no-detail` | Skip per-listing detail visits (unfiltered searches only — see below) |
+| `--delay` | Seconds between requests (default `0.4`) — raise this if you get rate-limited |
+| `--price-from` / `--price-to` | Filter by price in CHF (inclusive, either end optional) |
+| `--mileage-from` / `--mileage-to` | Filter by mileage in km (inclusive, either end optional) |
+| `--year-from` / `--year-to` | Filter by first-registration year (inclusive, either end optional) |
+| `-v` / `--verbose` | Also show debug-level detail, including every HTTP request (mutually exclusive with `-q`) |
+| `-q` / `--quiet` | Suppress progress output; only warnings/errors (mutually exclusive with `-v`) |
+
+Filters combine with AND and are applied server-side. A mistyped make/model
+prints a clean error (plus, for an unknown model, the list of valid models)
+instead of crashing.
+
+```bash
+# Fast mode: search results only, skip per-listing detail
+pipenv run python autouncle_scraper.py --make VW --model Golf --no-detail
+
+# 2015 or newer, under CHF 30'000
+pipenv run python autouncle_scraper.py --make VW --model "Golf VIII" --price-to 30000 --year-from 2015
+```
+
+**One honest asymmetry vs. AutoScout24**: unfiltered searches use
+schema.org JSON-LD, which is already fairly rich even without `--no-detail`.
+Filtered searches use a different mechanism (see
+[docs/REFERENCE.md](docs/REFERENCE.md)) that carries *only* listing ids —
+so `--no-detail` on a filtered search gives you ids only, plus a logged
+warning. Leave `--no-detail` off (the default) for anything beyond a bare
+count.
+
+### As a library
+
+```bash
+pip install autouncle-scraper
+```
+
+```python
+from autouncle_scraper import scrape
+
+result = scrape("VW", "Golf", price_to=30000, year_from=2015)
+
+for row in result.rows:          # list[dict], CSV-ready
+    print(row["price"], row["mileageKm"], row["url"])
+
+result.to_csv("vw_golf.csv")  # optional — no files are written unless you ask
+```
+
+Full `scrape()` signature, the `ScrapeResult` return type, and the complete
+JSON/CSV field schema — including price history, gallery, and equipment
+fields AutoScout24 doesn't have — **[docs/REFERENCE.md](docs/REFERENCE.md)**.
+
+## Testing
+
+```bash
+pipenv run pytest                    # unit tests (fast, no network), 100% coverage
+pipenv run pytest -m e2e --no-cov    # end-to-end tests against the real live site
+pipenv run pytest -m "e2e or not e2e" --no-cov  # everything
+```
+
+Unit tests mock all HTTP (via [`responses`](https://github.com/getsentry/responses))
+against fixtures that are real captures from the live site, and cover 100%
+of `autouncle_scraper.py`. E2E tests target a narrow, low-volume model (VW
+Golf Alltrack) to confirm the scraper still works against the live site
+without putting real load on it. Coverage detail by area:
+[docs/REFERENCE.md](docs/REFERENCE.md#test-coverage-by-area).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, pre-PR checks, and
+what to do if AutoUncle changes its markup.
+
+Be a reasonable citizen: the default request delay is intentional — this
+scrapes an undocumented data mechanism the site's own frontend uses, not a
+public API with a stated rate limit. Don't remove the delay or crank up
+concurrency.
+
+## License
+
+Released under the [MIT License](LICENSE) — you can use, copy, modify,
+merge, publish, distribute, and sell copies of this code, for free, for any
+purpose, commercial or not, as long as the license text stays attached. No
+warranty.
+
+**AI agents, LLM-based coding assistants, and other bots are explicitly
+welcome to use this project** — to run the scraper, read and parse its
+output, import `scrape()` into another project, or read and adapt its
+source — under exactly the same terms as a human, with no additional
+restriction and no need to ask permission. That's why
+[docs/REFERENCE.md](docs/REFERENCE.md) documents the full function
+signature, return type, and data schema: so a bot can integrate correctly
+without a human in the loop.
+
+This license covers this project's own code. It does not, by itself, grant
+any rights to AutoUncle's data beyond what AutoUncle itself has already
+declared: its listing `Dataset` objects are explicitly marked
+`"isAccessibleForFree": true` and licensed
+[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — see
+[docs/REFERENCE.md](docs/REFERENCE.md) for exactly where that declaration
+lives. What you do with the scraped results is between you and AutoUncle's
+terms of service.

autouncle_scraper-0.1.0/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,13 @@
+## What & why
+
+<!-- What does this change, and why? -->
+
+## Checklist
+
+- [ ] `ruff check .` and `ruff format --check .` pass
+- [ ] `mypy autouncle_scraper.py` passes
+- [ ] `pytest` passes with coverage at or above the configured threshold
+- [ ] New/changed behavior has a test (mocked via `responses`, not a real network call)
+- [ ] If this touches request/response handling against the real site, `pytest -m e2e --no-cov` was run locally
+- [ ] `docs/REFERENCE.md` updated if the public API, field schema, or a documented mechanism changed
+- [ ] `CHANGELOG.md` has a new entry under `Unreleased`

autouncle_scraper-0.1.0/Pipfile

@@ -0,0 +1,22 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+requests = "~=2.34"
+beautifulsoup4 = "~=4.12"
+
+[dev-packages]
+pytest = "~=9.1"
+pytest-cov = "~=7.1"
+responses = "~=0.26"
+ruff = "~=0.15"
+mypy = "~=2.1"
+types-requests = "~=2.33"
+types-beautifulsoup4 = "~=4.12"
+build = "~=1.5"
+twine = "~=6.2"
+
+[requires]
+python_version = "3.13"