kleinanzeigen 0.1.0__tar.gz

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

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request: ~
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  lint:
+    runs-on: ubuntu-26.04
+    steps:
+    - uses: actions/checkout@v7
+    - uses: jdx/mise-action@v5
+    - name: Install pip dependencies
+      run: uv sync
+    - uses: actions/cache@v6
+      with:
+        path: ~/.cache/pre-commit/
+        key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+    - name: Run pre-commit
+      run: pre-commit run --all-files --show-diff-on-failure
+  test:
+    runs-on: ubuntu-26.04
+    strategy:
+      matrix:
+        python-version: ['3.15', '3.14']
+    env:
+      MISE_PYTHON_VERSION: ${{ matrix.python-version }}
+    steps:
+    - uses: actions/checkout@v7
+    - uses: jdx/mise-action@v5
+    - name: Project python version
+      id: project-python-version
+      run: |
+        ver=$(grep -oP 'python\s*=\s*"\K[^"]+' mise.toml | cut -d. -f1-2)
+        echo "python-version=$ver" >> $GITHUB_OUTPUT
+    - name: Install python
+      run: mise install python@${{ matrix.python-version }}
+    - name: Install pip dependencies
+      run: uv sync
+    - name: Run tests
+      run: uv run pytest --cov --junitxml=junit.xml -o junit_family=legacy --cov-branch --cov-report=xml

kleinanzeigen-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+env:
+  MISE_IDIOMATIC_VERSION_FILE_ENABLE_TOOLS: python
+
+jobs:
+  publish:
+    runs-on: ubuntu-26.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/kleinanzeigen
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+    - uses: actions/checkout@v7
+    - uses: jdx/mise-action@v5
+    - name: Install pip dependencies
+      run: uv sync
+    - name: Package
+      run: uv build
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@v1.14.2

kleinanzeigen-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.enola/

kleinanzeigen-0.1.0/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "kleinanzeigen-dev": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--project",
+        "/home/malachi/code/python/kleinanzeigen",
+        "kleinanzeigen-mcp"
+      ]
+    }
+  }
+}

kleinanzeigen-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-yaml
+  - id: check-toml
+  - id: check-added-large-files
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.17.4
+  hooks:
+  - id: ruff-check
+    args:
+      - --fix
+  - id: ruff-format
+- repo: https://github.com/pre-commit/mirrors-mypy
+  rev: v2.4.1
+  hooks:
+  - id: mypy
+    additional_dependencies:
+      - types-beautifulsoup4
+      - pydantic>=2.0
+      - curl-cffi>=0.17.0
+      - mcp>=1.0,<2
+      - click>=8.5.1
+      - humanize>=4.16.0
+      - rich>=15.0.0
+    args: [src]
+    pass_filenames: false

kleinanzeigen-0.1.0/AGENTS.md

@@ -0,0 +1,74 @@
+# kleinanzeigen
+
+Async Python client for [kleinanzeigen.de](https://www.kleinanzeigen.de) over plain
+HTTP (`curl_cffi` with Chrome TLS impersonation + BeautifulSoup). No browser.
+
+## Structure
+
+- `src/kleinanzeigen/client.py` — `Kleinanzeigen` async client. `search()` takes
+  a `SearchParams` and `search_url()` takes a URL; both return a
+  `SearchResult`. `iter_search()` / `iter_search_url()` stream
+  `(PageProgress, listings)` per page for progress UIs;
+  `iter_search_pages(url_for)` is the low-level primitive, and
+  `collect_search_pages()` drains an iterator into a `SearchResult`.
+  `get_listing()` fetches a single ad (`None` when gone). All pagination
+  policy (delays, URL building) lives here — adapters never touch it.
+- `src/kleinanzeigen/parsing.py` — HTML extraction: search cards, breadcrumb
+  totals, ad detail pages, URL building, date/price/location parsing.
+  `apply_min_publish_date()` filters a page's listings and reports whether
+  an old listing ends pagination.
+- `src/kleinanzeigen/models.py` — frozen pydantic models: `SearchParams`
+  (validated request: page/pages/price bounds), `Listing`, `ListingDetail`,
+  `SearchResult`, `Price`, `Seller`, `Location`, `AdStatus`. Upstream
+  `published_at` is naive Europe/Berlin local time.
+- `src/kleinanzeigen/format.py` — typed JSON response boundary shared by CLI
+  and MCP: `SearchResponse` (envelope with `returned` after a response-level
+  `limit`), `ErrorResponse`, `search_response*()`. Responses embed core
+  models directly; keep adapter-only fields (limit/returned) out of
+  `SearchResult`.
+- `src/kleinanzeigen/cli.py` — `kleinanzeigen` command: `search`, `search-url`,
+  `get`. Rich table renders `SearchResult` directly; `--json` serializes via
+  `search_response_json`. Progress spinner consumes `iter_search*` on a
+  worker thread — keep CLI/presentation concerns out of `client.py`.
+- `src/kleinanzeigen/mcp_server.py` — `kleinanzeigen-mcp` MCP server exposing
+  the same search/get operations to MCP clients. Tools return typed models
+  (`SearchResponse`, `ListingDetail | ErrorResponse`) so FastMCP publishes
+  concrete output schemas.
+- `tests/` — pytest suite (currently `test_parsing.py`).
+
+## Setup
+
+Managed with `uv`; the venv is `.venv/`.
+
+```sh
+uv sync
+```
+
+## Run
+
+```sh
+kleinanzeigen search -q "fahrrad" -l "Berlin" --radius 5   # all pages by default
+kleinanzeigen search-url "<saved search URL>" --pages 3
+kleinanzeigen get <url-or-ad-id>
+```
+
+## Tests
+
+```sh
+uv run pytest
+```
+
+Config lives in `pyproject.toml` (`testpaths = ["tests"]`, `pythonpath = ["src"]`).
+Tests are offline — they exercise `parsing.py` against fixtures, not live HTTP.
+
+## Lint / format
+
+Lint/format run through pre-commit only — ruff is not installed in the venv
+(pre-commit pins its own version via `ruff-pre-commit`):
+
+```sh
+pre-commit run -a
+```
+
+Ruff config is in `pyproject.toml` (`src = ["src", "tests"]`); pre-commit's
+pinned ruff version is the single source of truth for the linter version.

kleinanzeigen-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: kleinanzeigen
+Version: 0.1.0
+Summary: Async client for querying kleinanzeigen.de over plain HTTP (no browser)
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: click>=8.5.1
+Requires-Dist: curl-cffi>=0.17.0
+Requires-Dist: humanize>=4.16.0
+Requires-Dist: mcp<2,>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=15.0.0
+Description-Content-Type: text/markdown
+
+# kleinanzeigen
+
+Async Python client for [kleinanzeigen.de](https://www.kleinanzeigen.de) backed by
+plain HTTP (curl_cffi + BeautifulSoup) — no Playwright, no browser. Ships a CLI
+and an MCP server on top of the same client.
+
+Requires Python 3.11+.
+
+Based off the work done in [ebay-kleinanzeigen-api](https://github.com/DanielWTE/ebay-kleinanzeigen-api/) and ported to run without a browser.
+
+> **Note:** this scrapes kleinanzeigen.de without a browser. Pages are fetched
+> sequentially with delays to be polite - don't hammer it, and check
+> kleinanzeigen.de's terms of service for your use case.
+
+## Install
+
+```bash
+# With uv
+uv add kleinanzeigen
+
+# With pip
+pip install kleinanzeigen
+
+# With pipx
+pipx install kleinanzeigen
+```
+
+## Library
+
+```python
+import asyncio
+from datetime import datetime
+
+from kleinanzeigen import Kleinanzeigen, SearchParams
+
+
+async def main():
+    async with Kleinanzeigen() as ka:
+        # keyword search; pages=0 fetches all pages
+        result = await ka.search(
+            SearchParams(query="fahrrad", location="Berlin", radius=25, pages=2)
+        )
+        for listing in result.listings:
+            print(listing.title, listing.price, listing.url)
+        print(result.total_results, result.total_pages, result.pages_fetched)
+
+        # any saved/filtered search URL (page numbers injected automatically)
+        result = await ka.search_url(
+            "https://www.kleinanzeigen.de/s-suche/foo.html", pages=3
+        )
+
+        # drop listings older than a cutoff (naive = Europe/Berlin)
+        result = await ka.search(
+            SearchParams(query="fahrrad", published_after=datetime(2026, 1, 1))
+        )
+
+        # single ad, by URL or bare id — None when the ad is gone
+        detail = await ka.get_listing("123456789")
+        if detail:
+            print(detail.title, detail.price.amount, detail.seller.name, detail.images)
+
+        # streaming progress: yields (PageProgress, listings) per page
+        async for progress, page_listings in ka.iter_search(
+            SearchParams(query="fahrrad")
+        ):
+            print(progress.page, progress.total_pages, len(page_listings))
+
+
+asyncio.run(main())
+```
+
+`SearchParams` fields: `query`, `location`, `radius`, `min_price`, `max_price`,
+`page` (first page, 1-based), `pages` (0 = all), `published_after`.
+`iter_search_url(url, pages=n)` is the streaming variant of `search_url`.
+`iter_search_pages(url_for, first_page=, pages=)` is the low-level primitive
+both streaming variants build on.
+
+`ListingDetail` fields: `ad_id`, `url`, `title`, `status` (`active`/`sold`/
+`reserved`/`deleted`), `price` (`amount` is `None` when the ad shows no
+numeric price, e.g. "VB" or "Zu verschenken"; `negotiable` flags "VB"),
+`categories`, `description`, `location` (`postal_code`/`city`/`state`),
+`delivery` (`pickup`/`shipping`), `images`, `details`, `features`, `seller`
+(`name`, `user_id`, `member_since`, `type`, `badges`), `created_at`,
+`scraped_at`.
+
+
+## CLI
+
+Installed as `kleinanzeigen`:
+
+```sh
+# keyword search — all pages by default; Rich table with live spinner
+kleinanzeigen search -q "fahrrad" -l "Berlin" --radius 5 --pages 3
+
+# filters; --json prints raw JSON instead of the table
+kleinanzeigen search -q "iphone" --min-price 100 --max-price 500 --json
+
+# scrape a saved/filtered search URL
+kleinanzeigen search-url "https://www.kleinanzeigen.de/s-suche/foo.html" --pages 3
+
+# single ad by URL or bare id — prints JSON; exits 1 when the ad is gone
+kleinanzeigen get 123456789
+```
+
+`search` options: `-q/--query` (required), `-l/--location`, `--radius`,
+`--min-price`, `--max-price`, `--page`, `--pages`, `--published-after`,
+`--json`. `search-url` accepts `--pages`, `--published-after`, `--json`.
+
+## MCP server
+
+Installed as `kleinanzeigen-mcp` (stdio). Tools: `search`, `search_url`,
+`get_listing`. Search tools take the same arguments as the library plus a
+`limit` cap on returned listings; both accept `published_after` (ISO
+date/datetime). Responses are typed `SearchResponse` (`listings`,
+`total_results`, `total_pages`, `pages_fetched`, `returned`) or
+`ListingDetail`; a missing ad returns `{"error": "listing not found or removed"}`.
+
+Add the following to your mcp json:
+
+```json
+{
+  "mcpServers": {
+    "kleinanzeigen": {
+      "command": "kleinanzeigen-mcp"
+    }
+  }
+}
+```
+
+From a source checkout: `uv run kleinanzeigen-mcp`.
+
+## Notes
+
+- Pages are fetched **sequentially** with a delay (`page_delay`, default 1s;
+  `search_url` enforces at least 2s) — Kleinanzeigen blocks concurrent
+  requests from one IP.
+- `published_after` stops pagination early once older listings appear and
+  trims them from results. Upstream timestamps are naive Europe/Berlin.
+- `search`/`search_url` return `SearchResult` (`listings`, `total_results`,
+  `total_pages`, `pages_fetched`); `get_listing` returns `ListingDetail` or
+  `None`.
+- Transient HTTP errors are retried (`max_retries`, exponential backoff);
+  exhausted retries raise `KleinanzeigenError`.

kleinanzeigen-0.1.0/README.md

@@ -0,0 +1,143 @@
+# kleinanzeigen
+
+Async Python client for [kleinanzeigen.de](https://www.kleinanzeigen.de) backed by
+plain HTTP (curl_cffi + BeautifulSoup) — no Playwright, no browser. Ships a CLI
+and an MCP server on top of the same client.
+
+Requires Python 3.11+.
+
+Based off the work done in [ebay-kleinanzeigen-api](https://github.com/DanielWTE/ebay-kleinanzeigen-api/) and ported to run without a browser.
+
+> **Note:** this scrapes kleinanzeigen.de without a browser. Pages are fetched
+> sequentially with delays to be polite - don't hammer it, and check
+> kleinanzeigen.de's terms of service for your use case.
+
+## Install
+
+```bash
+# With uv
+uv add kleinanzeigen
+
+# With pip
+pip install kleinanzeigen
+
+# With pipx
+pipx install kleinanzeigen
+```
+
+## Library
+
+```python
+import asyncio
+from datetime import datetime
+
+from kleinanzeigen import Kleinanzeigen, SearchParams
+
+
+async def main():
+    async with Kleinanzeigen() as ka:
+        # keyword search; pages=0 fetches all pages
+        result = await ka.search(
+            SearchParams(query="fahrrad", location="Berlin", radius=25, pages=2)
+        )
+        for listing in result.listings:
+            print(listing.title, listing.price, listing.url)
+        print(result.total_results, result.total_pages, result.pages_fetched)
+
+        # any saved/filtered search URL (page numbers injected automatically)
+        result = await ka.search_url(
+            "https://www.kleinanzeigen.de/s-suche/foo.html", pages=3
+        )
+
+        # drop listings older than a cutoff (naive = Europe/Berlin)
+        result = await ka.search(
+            SearchParams(query="fahrrad", published_after=datetime(2026, 1, 1))
+        )
+
+        # single ad, by URL or bare id — None when the ad is gone
+        detail = await ka.get_listing("123456789")
+        if detail:
+            print(detail.title, detail.price.amount, detail.seller.name, detail.images)
+
+        # streaming progress: yields (PageProgress, listings) per page
+        async for progress, page_listings in ka.iter_search(
+            SearchParams(query="fahrrad")
+        ):
+            print(progress.page, progress.total_pages, len(page_listings))
+
+
+asyncio.run(main())
+```
+
+`SearchParams` fields: `query`, `location`, `radius`, `min_price`, `max_price`,
+`page` (first page, 1-based), `pages` (0 = all), `published_after`.
+`iter_search_url(url, pages=n)` is the streaming variant of `search_url`.
+`iter_search_pages(url_for, first_page=, pages=)` is the low-level primitive
+both streaming variants build on.
+
+`ListingDetail` fields: `ad_id`, `url`, `title`, `status` (`active`/`sold`/
+`reserved`/`deleted`), `price` (`amount` is `None` when the ad shows no
+numeric price, e.g. "VB" or "Zu verschenken"; `negotiable` flags "VB"),
+`categories`, `description`, `location` (`postal_code`/`city`/`state`),
+`delivery` (`pickup`/`shipping`), `images`, `details`, `features`, `seller`
+(`name`, `user_id`, `member_since`, `type`, `badges`), `created_at`,
+`scraped_at`.
+
+
+## CLI
+
+Installed as `kleinanzeigen`:
+
+```sh
+# keyword search — all pages by default; Rich table with live spinner
+kleinanzeigen search -q "fahrrad" -l "Berlin" --radius 5 --pages 3
+
+# filters; --json prints raw JSON instead of the table
+kleinanzeigen search -q "iphone" --min-price 100 --max-price 500 --json
+
+# scrape a saved/filtered search URL
+kleinanzeigen search-url "https://www.kleinanzeigen.de/s-suche/foo.html" --pages 3
+
+# single ad by URL or bare id — prints JSON; exits 1 when the ad is gone
+kleinanzeigen get 123456789
+```
+
+`search` options: `-q/--query` (required), `-l/--location`, `--radius`,
+`--min-price`, `--max-price`, `--page`, `--pages`, `--published-after`,
+`--json`. `search-url` accepts `--pages`, `--published-after`, `--json`.
+
+## MCP server
+
+Installed as `kleinanzeigen-mcp` (stdio). Tools: `search`, `search_url`,
+`get_listing`. Search tools take the same arguments as the library plus a
+`limit` cap on returned listings; both accept `published_after` (ISO
+date/datetime). Responses are typed `SearchResponse` (`listings`,
+`total_results`, `total_pages`, `pages_fetched`, `returned`) or
+`ListingDetail`; a missing ad returns `{"error": "listing not found or removed"}`.
+
+Add the following to your mcp json:
+
+```json
+{
+  "mcpServers": {
+    "kleinanzeigen": {
+      "command": "kleinanzeigen-mcp"
+    }
+  }
+}
+```
+
+From a source checkout: `uv run kleinanzeigen-mcp`.
+
+## Notes
+
+- Pages are fetched **sequentially** with a delay (`page_delay`, default 1s;
+  `search_url` enforces at least 2s) — Kleinanzeigen blocks concurrent
+  requests from one IP.
+- `published_after` stops pagination early once older listings appear and
+  trims them from results. Upstream timestamps are naive Europe/Berlin.
+- `search`/`search_url` return `SearchResult` (`listings`, `total_results`,
+  `total_pages`, `pages_fetched`); `get_listing` returns `ListingDetail` or
+  `None`.
+- Transient HTTP errors are retried (`max_retries`, exponential backoff);
+  exhausted retries raise `KleinanzeigenError`.

kleinanzeigen-0.1.0/mise.toml

@@ -0,0 +1,11 @@
+[tools]
+python = "3.15.2"
+pre-commit = "latest"
+uv = "0.12.21"
+
+[hooks]
+postinstall = "pre-commit install"
+
+[tasks.test]
+description = "Run tests"
+run = "uv run pytest"

kleinanzeigen-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "kleinanzeigen"
+version = "0.1.0"
+description = "Async client for querying kleinanzeigen.de over plain HTTP (no browser)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "beautifulsoup4>=4.12",
+    "click>=8.5.1",
+    "mcp>=1.0,<2",
+    "rich>=15.0.0",
+    "humanize>=4.16.0",
+    "curl-cffi>=0.17.0",
+    "pydantic>=2.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=7.0.0,<8",
+    "pytest-socket>=0.8",
+]
+
+[project.scripts]
+kleinanzeigen = "kleinanzeigen.cli:main"
+kleinanzeigen-mcp = "kleinanzeigen.mcp_server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kleinanzeigen"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+src = ["src", "tests"]

kleinanzeigen-0.1.0/src/kleinanzeigen/__init__.py

@@ -0,0 +1,27 @@
+"""Async client for querying kleinanzeigen.de without a browser."""
+
+from kleinanzeigen.client import Kleinanzeigen, KleinanzeigenError, PageProgress
+from kleinanzeigen.models import (
+    AdStatus,
+    Listing,
+    ListingDetail,
+    Location,
+    Price,
+    SearchParams,
+    SearchResult,
+    Seller,
+)
+
+__all__ = [
+    "AdStatus",
+    "Kleinanzeigen",
+    "KleinanzeigenError",
+    "Listing",
+    "ListingDetail",
+    "Location",
+    "PageProgress",
+    "Price",
+    "SearchParams",
+    "SearchResult",
+    "Seller",
+]

kleinanzeigen-0.1.0/src/kleinanzeigen/_version.py

@@ -0,0 +1,10 @@
+"""Package version from importlib.metadata — pyproject.toml is the source."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+
+def package_version() -> str:
+    try:
+        return version("kleinanzeigen")
+    except PackageNotFoundError:
+        return "unknown"