tutti-scraper 0.1.0__tar.gz

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

@@ -0,0 +1,26 @@
+---
+name: Bug report
+about: Something isn't working — e.g. wrong/missing data, a crash, or tutti.ch changed their API
+title: ""
+labels: bug
+assignees: ""
+---
+
+**Exact command you ran** (CLI flags, or the `scrape(...)` call if using it as a library)
+
+```
+```
+
+**What happened**
+
+**What you expected instead**
+
+**Version** (`tutti-scraper --version`, or the git commit if running from source)
+
+**If this looks like the API changed:** paste the raw response you got back
+(e.g. from `-v`/`--verbose`, or by hitting the endpoint directly with curl).
+This is the fastest way to confirm whether tutti.ch changed something on
+their end vs. a bug in this project.
+
+```json
+```

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

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

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

@@ -0,0 +1,28 @@
+name: E2E (live API)
+
+on:
+  schedule:
+    # Every Monday at 06:00 UTC. Keeps this off the main CI path (real
+    # network calls against tutti.ch shouldn't run on every push) while
+    # still giving an early warning if tutti.ch changes their API shape.
+    - cron: "0 6 * * 1"
+  workflow_dispatch: {}
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install "requests~=2.34" "pytest~=9.1" "pytest-cov~=7.1" "responses~=0.26"
+
+      - name: End-to-end tests against the live API
+        run: pytest -m e2e --no-cov

tutti_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.12"
+
+      - 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("tutti_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

tutti_scraper-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+.env
+__pycache__/
+*.pyc
+*.csv
+*.json
+!Pipfile.lock
+*.jsonl
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/

tutti_scraper-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# 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).
+
+## [0.1.0] - 2026-07-05
+
+Initial release.
+
+### Added
+
+- Scraper for tutti.ch listings, usable both as a CLI
+  (`tutti-scraper` / `python tutti_scraper.py`) and as a library
+  (`from tutti_scraper import scrape`).
+- Search by any free-text phrase against tutti.ch's own GraphQL API
+  (reverse-engineered from its compiled JS bundles, not a published
+  schema).
+- Recursive category/price-range partitioning that works around the
+  API's ~3000-offset pagination cap, so result sets far larger than one
+  page can still be fully covered; listings are de-duplicated by ID
+  across every slice.
+- Full-detail mode (default): visits every matching listing individually
+  to extract GPS coordinates, full-resolution images, structured
+  attributes, and richer seller info, generically flattened for CSV
+  output; `--no-detail`/`detail=False` for a faster summary-only pass.
+- Every listing's raw JSON and flattened CSV row both carry a direct
+  `url` back to the original ad.
+- `lang` parameter (default `"de"`) for `"fr"`/`"it"` tutti.ch locales.
+- `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 (`tutti-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) plus a smaller
+  end-to-end suite against the real live API, run on a separate weekly
+  GitHub Actions schedule.
+- CI (GitHub Actions) running lint, type-check, and the unit suite on
+  every push/PR across Python 3.11 and 3.12.
+- 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.
+- Deliberately interchangeable in shape with the sibling
+  [`autoscout24-scraper`](https://github.com/danyk20/autoscout24-scraper)
+  project: same `scrape()`/`ScrapeResult`/CLI/logging pattern, adapted to
+  tutti.ch's free-text search and GraphQL API instead of AutoScout24's
+  make/model REST API.

tutti_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 report@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.

tutti_scraper-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# 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/tutti-scraper.git
+cd tutti-scraper
+pipenv install --dev
+```
+
+## Before opening a PR
+
+```bash
+pipenv run ruff check .          # lint
+pipenv run ruff format .         # format
+pipenv run mypy tutti_scraper.py # type-check
+pipenv run pytest                # unit tests, must stay at 100% coverage
+```
+
+If your change touches request/response handling against the real API,
+also run the end-to-end suite (real network calls, ~10s):
+
+```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 tutti.ch changes its GraphQL schema, required headers, or pagination
+  behavior, prefer fixing the affected function directly over adding a
+  workaround — the module docstring in `tutti_scraper.py` documents the
+  current API shape, and it was reverse-engineered from tutti.ch's own
+  compiled JS bundles rather than any published schema.
+- Keep the change minimal and focused; this is a small single-file utility
+  by design (see the README's [Notes](README.md#notes) section for what's
+  intentionally out of scope, e.g. concurrency, Docker, a database layer).
+- This project aims to stay interchangeable in shape with its sibling
+  [`autoscout24-scraper`](https://github.com/danyk20/autoscout24-scraper)
+  (same `scrape()`/`ScrapeResult`/CLI pattern, different data source) —
+  when both projects have an equivalent concept, prefer matching its name
+  and behavior over inventing a new one, unless tutti.ch's domain genuinely
+  requires something different.
+
+## Questions / bug reports
+
+Open a GitHub issue using the bug report template — include the exact
+command you ran and, if relevant, the raw API 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:
+
+1. Bump `__version__` in `tutti_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 master
+   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.
+
+One-time setup this depends on (not done yet for this repo — see the
+release workflow's own notes): a Trusted Publisher registered on both
+pypi.org and test.pypi.org for this repo, and matching GitHub Environments
+named `pypi`/`testpypi`.

tutti_scraper-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Daniel Košč
+
+Permission is hereby granted, free of charge, to any person or automated
+agent (including AI assistants, bots, and other software acting on behalf
+of a 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.