blocket-toolkit 0.1.0__py3-none-any.whl

blocket_toolkit/__init__.py

@@ -0,0 +1,6 @@
+"""blocket-toolkit: search all of Blocket.se from the terminal."""
+
+from .client import BlocketClient, Page
+
+__version__ = "0.1.0"
+__all__ = ["BlocketClient", "Page", "__version__"]

blocket_toolkit/cli.py

@@ -0,0 +1,563 @@
+"""Command-line interface for blocket-toolkit."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from collections.abc import Callable
+from typing import Any
+
+from httpx import HTTPStatusError, RequestError
+
+from . import __version__
+from .client import AD_TYPES, BlocketClient, Page
+from .enums import (
+    BoatSortOrder,
+    BoatType,
+    CarColor,
+    CarModel,
+    CarSortOrder,
+    CarTransmission,
+    CarWheelDrive,
+    Category,
+    Location,
+    McModel,
+    McSortOrder,
+    McType,
+    SortOrder,
+    SubCategory,
+    enum_items,
+    resolve,
+    resolve_many,
+    subcategories_of,
+)
+from .format import (
+    BOAT_COLUMNS,
+    CAR_COLUMNS,
+    LISTING_COLUMNS,
+    MC_COLUMNS,
+    OPTION_COLUMNS,
+    render,
+    render_json,
+    render_pairs,
+)
+
+Fetch = Callable[[int], Page]
+
+
+def _sort_choices(enum_cls: type) -> list[str]:
+    return [member.name for member in enum_cls]
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument(
+        "-o",
+        "--output",
+        choices=("json", "jsonl", "table"),
+        default="json",
+        help="Output format (default: json)",
+    )
+    common.add_argument(
+        "--raw",
+        action="store_true",
+        help="Return Blocket's raw API objects instead of compacted records",
+    )
+
+    paging = argparse.ArgumentParser(add_help=False)
+    paging.add_argument("--page", type=int, default=1, help="Page number, 1-based (default: 1)")
+    paging.add_argument(
+        "-n", "--limit", type=int, default=None, help="Maximum number of results to return"
+    )
+    paging.add_argument(
+        "--all", action="store_true", dest="all_pages", help="Fetch all pages (see --max-pages)"
+    )
+    paging.add_argument(
+        "--max-pages", type=int, default=20, help="Safety cap for --all (default: 20)"
+    )
+
+    locations = argparse.ArgumentParser(add_help=False)
+    locations.add_argument(
+        "-l",
+        "--location",
+        action="append",
+        metavar="REGION",
+        help="Region name or id (repeatable or comma-separated), e.g. STOCKHOLM,SKANE",
+    )
+
+    parser = argparse.ArgumentParser(
+        prog="blocket-toolkit",
+        description="Search all of Blocket.se: general items, cars, boats and motorcycles.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"blocket-toolkit {__version__}"
+    )
+    sub = parser.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    p = sub.add_parser(
+        "search",
+        parents=[common, paging, locations],
+        help="Search general items (torget)",
+        description="Search general items on Blocket torget.",
+    )
+    p.add_argument("query", help="Search term")
+    p.add_argument(
+        "-c",
+        "--category",
+        help="Category name or id, e.g. ELEKTRONIK_OCH_VITVAROR or 0.93",
+    )
+    p.add_argument(
+        "--sub-category", help="Subcategory name or id, e.g. DATORER or 1.93.3215"
+    )
+    p.add_argument(
+        "--sort",
+        type=str.upper,
+        choices=_sort_choices(SortOrder),
+        default="RELEVANCE",
+    )
+    p.add_argument("--price-min", type=int, default=None, help="Minimum price, SEK (client-side)")
+    p.add_argument("--price-max", type=int, default=None, help="Maximum price, SEK (client-side)")
+    p.add_argument(
+        "--newer-than",
+        type=float,
+        default=None,
+        metavar="HOURS",
+        help="Only ads newer than N hours",
+    )
+    p.set_defaults(handler=_cmd_search)
+
+    p = sub.add_parser(
+        "cars",
+        parents=[common, paging, locations],
+        help="Search used cars",
+        description="Search used cars on Blocket mobility.",
+    )
+    p.add_argument("query", nargs="?", default=None, help="Optional free-text search term")
+    p.add_argument("-m", "--model", action="append", metavar="BRAND", help="Car brand, e.g. VOLVO")
+    p.add_argument("--color", action="append", metavar="COLOR", help="Exterior colour, e.g. SVART")
+    p.add_argument("--transmission", action="append", metavar="GEARBOX", help="AUTOMATIC or MANUAL")
+    p.add_argument(
+        "--wheel-drive", action="append", metavar="DRIVE", help="FWD, RWD, FOUR or TWO"
+    )
+    p.add_argument("--price-min", type=int, default=None, help="Minimum price, SEK")
+    p.add_argument("--price-max", type=int, default=None, help="Maximum price, SEK")
+    p.add_argument(
+        "--year-min", type=int, default=None, dest="year_from", help="Earliest model year"
+    )
+    p.add_argument(
+        "--year-max", type=int, default=None, dest="year_to", help="Latest model year"
+    )
+    p.add_argument(
+        "--mileage-min",
+        type=int,
+        default=None,
+        dest="mileage_from",
+        help="Minimum milage, km",
+    )
+    p.add_argument(
+        "--mileage-max",
+        type=int,
+        default=None,
+        dest="mileage_to",
+        help="Maximum milage, km",
+    )
+    p.add_argument(
+        "--hp-min", type=int, default=None, dest="horsepower_from", help="Minimum horsepower"
+    )
+    p.add_argument(
+        "--hp-max", type=int, default=None, dest="horsepower_to", help="Maximum horsepower"
+    )
+    p.add_argument(
+        "--sort", type=str.upper, choices=_sort_choices(CarSortOrder), default="RELEVANCE"
+    )
+    p.set_defaults(handler=_cmd_cars)
+
+    p = sub.add_parser(
+        "boats",
+        parents=[common, paging, locations],
+        help="Search used boats",
+        description="Search used boats on Blocket mobility.",
+    )
+    p.add_argument("query", nargs="?", default=None, help="Optional free-text search term")
+    p.add_argument(
+        "-t",
+        "--type",
+        action="append",
+        metavar="TYPE",
+        help="Boat type, e.g. SEGELBAT_MOTORSEGLARE",
+    )
+    p.add_argument("--price-min", type=int, default=None, help="Minimum price, SEK")
+    p.add_argument("--price-max", type=int, default=None, help="Maximum price, SEK")
+    p.add_argument(
+        "--length-min", type=int, default=None, dest="length_from", help="Minimum length, feet"
+    )
+    p.add_argument(
+        "--length-max", type=int, default=None, dest="length_to", help="Maximum length, feet"
+    )
+    p.add_argument(
+        "--sort", type=str.upper, choices=_sort_choices(BoatSortOrder), default="RELEVANCE"
+    )
+    p.set_defaults(handler=_cmd_boats)
+
+    p = sub.add_parser(
+        "mc",
+        parents=[common, paging, locations],
+        help="Search used motorcycles",
+        description="Search used motorcycles on Blocket mobility.",
+    )
+    p.add_argument("query", nargs="?", default=None, help="Optional free-text search term")
+    p.add_argument("-m", "--model", action="append", metavar="BRAND", help="MC brand, e.g. YAMAHA")
+    p.add_argument("-t", "--type", action="append", metavar="TYPE", help="MC type, e.g. SPORT")
+    p.add_argument("--price-min", type=int, default=None, help="Minimum price, SEK")
+    p.add_argument("--price-max", type=int, default=None, help="Maximum price, SEK")
+    p.add_argument(
+        "--engine-min",
+        type=int,
+        default=None,
+        dest="engine_volume_from",
+        help="Minimum engine volume, cc",
+    )
+    p.add_argument(
+        "--engine-max",
+        type=int,
+        default=None,
+        dest="engine_volume_to",
+        help="Maximum engine volume, cc",
+    )
+    p.add_argument(
+        "--sort", type=str.upper, choices=_sort_choices(McSortOrder), default="RELEVANCE"
+    )
+    p.set_defaults(handler=_cmd_mc)
+
+    p = sub.add_parser(
+        "ad",
+        parents=[common],
+        help="Fetch one listing",
+        description="Fetch the full listing for an ad id.",
+    )
+    p.add_argument("ad_id", type=int, help="The ad id from a search result")
+    p.add_argument(
+        "--type", choices=AD_TYPES, default="recommerce", help="Listing kind (default: recommerce)"
+    )
+    p.set_defaults(handler=_cmd_ad)
+
+    p = sub.add_parser(
+        "categories",
+        parents=[common],
+        help="List categories",
+        description="List all general item categories.",
+    )
+    p.set_defaults(handler=_cmd_categories)
+
+    p = sub.add_parser(
+        "subcategories",
+        parents=[common],
+        help="List subcategories",
+        description="List subcategories, optionally for a single category.",
+    )
+    p.add_argument("-c", "--category", help="Restrict to one category")
+    p.set_defaults(handler=_cmd_subcategories)
+
+    p = sub.add_parser(
+        "locations",
+        parents=[common],
+        help="List regions",
+        description="List all Swedish regions.",
+    )
+    p.set_defaults(handler=_cmd_locations)
+
+    p = sub.add_parser(
+        "car-options",
+        parents=[common],
+        help="List car filter options",
+        description="List car brands, colours, gearboxes and sort orders.",
+    )
+    p.set_defaults(handler=_cmd_car_options)
+
+    p = sub.add_parser(
+        "boat-options",
+        parents=[common],
+        help="List boat filter options",
+        description="List boat types and sort orders.",
+    )
+    p.set_defaults(handler=_cmd_boat_options)
+
+    p = sub.add_parser(
+        "mc-options",
+        parents=[common],
+        help="List motorcycle filter options",
+        description="List MC brands, types and sort orders.",
+    )
+    p.set_defaults(handler=_cmd_mc_options)
+
+    return parser
+
+
+def _gather(fetch: Fetch, args: argparse.Namespace) -> tuple[list[dict], dict[str, Any]]:
+    limit = args.limit
+    items: list[dict[str, Any]] = []
+    last_page: int | None = None
+    total: int | None = None
+    start = args.page
+
+    if args.all_pages:
+        page_no = start
+        for _ in range(args.max_pages):
+            page = fetch(page_no)
+            items.extend(page.items)
+            last_page = page.last_page
+            total = page.total if total is None else total
+            if not page.items:
+                break
+            if limit is not None and len(items) >= limit:
+                break
+            if page.last_page is not None and page_no >= page.last_page:
+                break
+            page_no += 1
+    else:
+        page = fetch(start)
+        items = list(page.items)
+        last_page = page.last_page
+        total = page.total
+
+    if limit is not None:
+        items = items[:limit]
+
+    meta = {"page": start, "last_page": last_page, "total": total, "count": len(items)}
+    return items, meta
+
+
+def _price_of(item: dict[str, Any]) -> int | None:
+    price = item.get("price")
+    if isinstance(price, dict):
+        price = price.get("amount")
+    if isinstance(price, (int, float)):
+        return int(price)
+    return None
+
+
+def _filter_local(
+    items: list[dict[str, Any]],
+    *,
+    price_min: int | None,
+    price_max: int | None,
+    newer_than: float | None,
+) -> list[dict[str, Any]]:
+    cutoff = (time.time() - newer_than * 3600) * 1000 if newer_than else None
+    out = []
+    for item in items:
+        if price_min is not None or price_max is not None:
+            price = _price_of(item)
+            if price is None:
+                continue
+            if price_min is not None and price < price_min:
+                continue
+            if price_max is not None and price > price_max:
+                continue
+        if cutoff is not None:
+            timestamp = item.get("timestamp")
+            if not isinstance(timestamp, (int, float)) or timestamp < cutoff:
+                continue
+        out.append(item)
+    return out
+
+
+def _print(items: list[dict], args: argparse.Namespace, meta: dict[str, Any], columns) -> None:
+    if args.output == "json":
+        print(render_json({**meta, "items": items}))
+    else:
+        print(render(items, args.output, columns))
+
+
+def _print_options(items: Any, args: argparse.Namespace, columns=OPTION_COLUMNS) -> None:
+    print(render(items, args.output, columns))
+
+
+def _cmd_search(args: argparse.Namespace) -> None:
+    if args.category and args.sub_category:
+        raise ValueError("Cannot combine --category and --sub-category")
+
+    client = BlocketClient()
+    locations = resolve_many(Location, args.location)
+    sort_order = resolve(SortOrder, args.sort)
+    category = resolve(Category, args.category) if args.category else None
+    sub_category = resolve(SubCategory, args.sub_category) if args.sub_category else None
+    compact = not args.raw
+
+    def fetch(page: int) -> Page:
+        return client.search(
+            args.query,
+            page=page,
+            sort_order=sort_order,
+            locations=locations,
+            category=category,
+            sub_category=sub_category,
+            compact=compact,
+        )
+
+    items, meta = _gather(fetch, args)
+    items = _filter_local(
+        items, price_min=args.price_min, price_max=args.price_max, newer_than=args.newer_than
+    )
+    meta["count"] = len(items)
+    _print(items, args, meta, LISTING_COLUMNS)
+
+
+def _cmd_cars(args: argparse.Namespace) -> None:
+    client = BlocketClient()
+    fetch_ = lambda page: client.search_cars(  # noqa: E731
+        args.query,
+        page=page,
+        sort_order=resolve(CarSortOrder, args.sort),
+        locations=resolve_many(Location, args.location),
+        models=resolve_many(CarModel, args.model),
+        price_from=args.price_min,
+        price_to=args.price_max,
+        year_from=args.year_from,
+        year_to=args.year_to,
+        mileage_from=args.mileage_from,
+        mileage_to=args.mileage_to,
+        horsepower_from=args.horsepower_from,
+        horsepower_to=args.horsepower_to,
+        colors=resolve_many(CarColor, args.color),
+        transmissions=resolve_many(CarTransmission, args.transmission),
+        wheel_drive=resolve_many(CarWheelDrive, args.wheel_drive),
+        compact=not args.raw,
+    )
+    items, meta = _gather(fetch_, args)
+    _print(items, args, meta, CAR_COLUMNS)
+
+
+def _cmd_boats(args: argparse.Namespace) -> None:
+    client = BlocketClient()
+    fetch_: Fetch = lambda page: client.search_boats(  # noqa: E731
+        args.query,
+        page=page,
+        sort_order=resolve(BoatSortOrder, args.sort),
+        locations=resolve_many(Location, args.location),
+        types=resolve_many(BoatType, args.type),
+        price_from=args.price_min,
+        price_to=args.price_max,
+        length_from=args.length_from,
+        length_to=args.length_to,
+        compact=not args.raw,
+    )
+    items, meta = _gather(fetch_, args)
+    _print(items, args, meta, BOAT_COLUMNS)
+
+
+def _cmd_mc(args: argparse.Namespace) -> None:
+    client = BlocketClient()
+    fetch_: Fetch = lambda page: client.search_mc(  # noqa: E731
+        args.query,
+        page=page,
+        sort_order=resolve(McSortOrder, args.sort),
+        locations=resolve_many(Location, args.location),
+        models=resolve_many(McModel, args.model),
+        types=resolve_many(McType, args.type),
+        price_from=args.price_min,
+        price_to=args.price_max,
+        engine_volume_from=args.engine_volume_from,
+        engine_volume_to=args.engine_volume_to,
+        compact=not args.raw,
+    )
+    items, meta = _gather(fetch_, args)
+    _print(items, args, meta, MC_COLUMNS)
+
+
+def _cmd_ad(args: argparse.Namespace) -> None:
+    client = BlocketClient()
+    details = client.get_ad(args.ad_id, ad_type=args.type, raw=args.raw)
+    if args.output == "jsonl":
+        print(render([details], "jsonl"))
+    elif args.output == "table":
+        print(render_pairs(details))
+    else:
+        print(render_json(details))
+
+
+def _cmd_categories(args: argparse.Namespace) -> None:
+    _print_options(enum_items(Category), args)
+
+
+def _cmd_subcategories(args: argparse.Namespace) -> None:
+    items: list[dict[str, Any]] = []
+    if args.category:
+        category = resolve(Category, args.category)
+        items = [
+            {"category": category.name, "name": sub.name, "id": str(sub.value)}
+            for sub in subcategories_of(category)
+        ]
+    else:
+        for category in Category:
+            items.extend(
+                {"category": category.name, "name": sub.name, "id": str(sub.value)}
+                for sub in subcategories_of(category)
+            )
+        items.sort(key=lambda item: (item["category"], item["name"]))
+    _print_options(items, args, ("category", "name", "id"))
+
+
+def _cmd_locations(args: argparse.Namespace) -> None:
+    _print_options(enum_items(Location), args)
+
+
+def _cmd_car_options(args: argparse.Namespace) -> None:
+    _print_options(
+        {
+            "models": enum_items(CarModel),
+            "colors": enum_items(CarColor),
+            "transmissions": enum_items(CarTransmission),
+            "wheel_drives": enum_items(CarWheelDrive),
+            "sort_orders": enum_items(CarSortOrder),
+        },
+        args,
+    )
+
+
+def _cmd_boat_options(args: argparse.Namespace) -> None:
+    _print_options(
+        {"types": enum_items(BoatType), "sort_orders": enum_items(BoatSortOrder)}, args
+    )
+
+
+def _cmd_mc_options(args: argparse.Namespace) -> None:
+    _print_options(
+        {
+            "models": enum_items(McModel),
+            "types": enum_items(McType),
+            "sort_orders": enum_items(McSortOrder),
+        },
+        args,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        args.handler(args)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    except HTTPStatusError as exc:
+        print(
+            f"error: Blocket returned HTTP {exc.response.status_code} for {exc.request.url}",
+            file=sys.stderr,
+        )
+        return 1
+    except RequestError as exc:
+        print(f"error: network problem talking to Blocket: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

blocket_toolkit/client.py

@@ -0,0 +1,366 @@
+"""Thin wrapper around ``blocket_api`` returning compact, JSON-friendly records."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+from blocket_api import BlocketAPI, BoatAd, CarAd, McAd, RecommerceAd
+
+from .enums import (
+    BoatSortOrder,
+    BoatType,
+    CarColor,
+    CarModel,
+    CarSortOrder,
+    CarTransmission,
+    CarWheelDrive,
+    Category,
+    Location,
+    McModel,
+    McSortOrder,
+    McType,
+    SortOrder,
+    SubCategory,
+)
+
+AD_CLASSES: dict[str, type] = {
+    "recommerce": RecommerceAd,
+    "car": CarAd,
+    "boat": BoatAd,
+    "mc": McAd,
+}
+
+AD_TYPES: tuple[str, ...] = tuple(AD_CLASSES)
+
+_LISTING_KEYS = (
+    "id",
+    "ad_id",
+    "heading",
+    "subheading",
+    "location",
+    "trade_type",
+    "flags",
+    "labels",
+    "dealer_segment",
+    "seller_type",
+    "org_id",
+)
+
+_VEHICLE_KEYS = (
+    "make",
+    "model",
+    "model_specification",
+    "series",
+    "registration_class",
+    "vehicle_type",
+    "regno",
+    "year",
+    "model_year",
+    "mileage",
+    "milage",
+    "mileage_unit",
+    "transmission",
+    "fuel",
+    "horsepower",
+    "engine_volume",
+    "volume",
+    "length",
+    "width",
+    "length_feet",
+    "motor_type",
+    "motor_fuel",
+    "motor_size",
+    "class",
+    "engine_type",
+    "seats",
+    "old_price",
+)
+
+_PRICE_UNITS_TO_DROP = {"TOTAL", "kr", "KR", "SEK"}
+
+
+@dataclass
+class Page:
+    """One page of search results."""
+
+    items: list[dict[str, Any]]
+    page: int = 1
+    last_page: int | None = None
+    total: int | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "page": self.page,
+            "last_page": self.last_page,
+            "total": self.total,
+            "count": len(self.items),
+            "items": self.items,
+        }
+
+
+def _iso(timestamp_ms: float) -> str:
+    return datetime.fromtimestamp(timestamp_ms / 1000, tz=UTC).isoformat()
+
+
+def compact_listing(doc: dict[str, Any]) -> dict[str, Any]:
+    """Reduce a raw Blocket search hit to a flat, predictable record."""
+    out: dict[str, Any] = {}
+
+    for key in _LISTING_KEYS + _VEHICLE_KEYS:
+        value = doc.get(key)
+        if value is not None:
+            out[key] = value
+
+    if isinstance(out.get("id"), str) and out["id"].isdigit():
+        out["id"] = int(out["id"])
+
+    url = doc.get("canonical_url") or doc.get("url")
+    if not url and doc.get("id") is not None:
+        url = f"https://www.blocket.se/recommerce/forsale/item/{doc['id']}"
+    if url:
+        out["url"] = url
+
+    image = doc.get("image")
+    if isinstance(image, dict) and image.get("url"):
+        out["image_url"] = image["url"]
+    elif doc.get("image_url"):
+        out["image_url"] = doc["image_url"]
+    elif doc.get("image_urls"):
+        out["image_urls"] = doc["image_urls"]
+
+    price = doc.get("price")
+    if isinstance(price, dict):
+        out["price"] = price.get("amount")
+        unit = price.get("price_unit")
+        if unit and unit not in _PRICE_UNITS_TO_DROP:
+            out["price_unit"] = unit
+    elif isinstance(price, (int, float)):
+        out["price"] = int(price)
+
+    timestamp = doc.get("timestamp")
+    if isinstance(timestamp, (int, float)):
+        out["timestamp"] = timestamp
+        out["published_at"] = _iso(timestamp)
+
+    return out
+
+
+def _slim_recommerce(payload: dict[str, Any]) -> dict[str, Any]:
+    section = (payload.get("loaderData") or {}).get("item-recommerce") or {}
+    item = section.get("itemData")
+    if not isinstance(item, dict):
+        return payload
+
+    out = dict(item)
+    images = item.get("images")
+    if isinstance(images, list):
+        urls = [
+            image.get("url") or image.get("uri")
+            for image in images
+            if isinstance(image, dict) and (image.get("url") or image.get("uri"))
+        ]
+        if urls:
+            out["image_urls"] = urls
+    if section.get("jsonLd"):
+        out["jsonLd"] = section["jsonLd"]
+    if section.get("meta"):
+        out["meta"] = section["meta"]
+    return out
+
+
+def _paging(raw: dict[str, Any], page: int) -> tuple[int, int | None, int | None]:
+    meta = raw.get("metadata") or {}
+    paging = meta.get("paging") or {}
+
+    current = paging.get("current") or paging.get("page") or page
+    last = paging.get("last") or paging.get("last_page") or paging.get("total_pages")
+
+    tracking = meta.get("tracking") or {}
+    tracking_object = tracking.get("object") or {}
+    total = (
+        (meta.get("result_size") or {}).get("match_count")
+        or tracking_object.get("numItems")
+        or meta.get("total")
+        or meta.get("total_count")
+    )
+
+    def as_int(value: Any) -> int | None:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return None
+
+    return as_int(current) or page, as_int(last), as_int(total)
+
+
+class BlocketClient:
+    """Search Blocket.se for items, cars, boats and motorcycles."""
+
+    def __init__(self, api: BlocketAPI | None = None) -> None:
+        self._api = api if api is not None else BlocketAPI()
+
+    def _page(self, raw: dict[str, Any], page: int, compact: bool) -> Page:
+        docs = raw.get("docs") or []
+        items = [compact_listing(doc) for doc in docs] if compact else docs
+        current, last, total = _paging(raw, page)
+        return Page(items=items, page=current, last_page=last, total=total)
+
+    def search(
+        self,
+        query: str,
+        *,
+        page: int = 1,
+        sort_order: SortOrder = SortOrder.RELEVANCE,
+        locations: list[Location] | None = None,
+        category: Category | None = None,
+        sub_category: SubCategory | None = None,
+        compact: bool = True,
+    ) -> Page:
+        """Search general items (torget)."""
+        raw = self._api.search(
+            query,
+            page=page,
+            sort_order=sort_order,
+            locations=list(locations or []),
+            category=category,
+            sub_category=sub_category,
+        )
+        return self._page(raw, page, compact)
+
+    def search_cars(
+        self,
+        query: str | None = None,
+        *,
+        page: int = 1,
+        sort_order: CarSortOrder = CarSortOrder.RELEVANCE,
+        locations: list[Location] | None = None,
+        models: list[CarModel] | None = None,
+        price_from: int | None = None,
+        price_to: int | None = None,
+        year_from: int | None = None,
+        year_to: int | None = None,
+        mileage_from: int | None = None,
+        mileage_to: int | None = None,
+        horsepower_from: int | None = None,
+        horsepower_to: int | None = None,
+        colors: list[CarColor] | None = None,
+        transmissions: list[CarTransmission] | None = None,
+        wheel_drive: list[CarWheelDrive] | None = None,
+        compact: bool = True,
+    ) -> Page:
+        """Search used cars."""
+        raw = self._api.search_car(
+            query or None,
+            page=page,
+            sort_order=sort_order,
+            locations=list(locations or []),
+            models=list(models or []),
+            price_from=price_from,
+            price_to=price_to,
+            year_from=year_from,
+            year_to=year_to,
+            milage_from=mileage_from,
+            milage_to=mileage_to,
+            horsepower_from=horsepower_from,
+            horsepower_to=horsepower_to,
+            colors=list(colors or []),
+            transmissions=list(transmissions or []),
+            wheel_drive=list(wheel_drive or []),
+        )
+        return self._page(raw, page, compact)
+
+    def search_boats(
+        self,
+        query: str | None = None,
+        *,
+        page: int = 1,
+        sort_order: BoatSortOrder = BoatSortOrder.RELEVANCE,
+        locations: list[Location] | None = None,
+        types: list[BoatType] | None = None,
+        price_from: int | None = None,
+        price_to: int | None = None,
+        length_from: int | None = None,
+        length_to: int | None = None,
+        compact: bool = True,
+    ) -> Page:
+        """Search used boats."""
+        raw = self._api.search_boat(
+            query or None,
+            page=page,
+            sort_order=sort_order,
+            types=list(types or []),
+            locations=list(locations or []),
+            price_from=price_from,
+            price_to=price_to,
+            length_from=length_from,
+            length_to=length_to,
+        )
+        return self._page(raw, page, compact)
+
+    def search_mc(
+        self,
+        query: str | None = None,
+        *,
+        page: int = 1,
+        sort_order: McSortOrder = McSortOrder.RELEVANCE,
+        locations: list[Location] | None = None,
+        models: list[McModel] | None = None,
+        types: list[McType] | None = None,
+        price_from: int | None = None,
+        price_to: int | None = None,
+        engine_volume_from: int | None = None,
+        engine_volume_to: int | None = None,
+        compact: bool = True,
+    ) -> Page:
+        """Search used motorcycles."""
+        raw = self._api.search_mc(
+            query or None,
+            page=page,
+            sort_order=sort_order,
+            models=list(models or []),
+            types=list(types or []),
+            locations=list(locations or []),
+            price_from=price_from,
+            price_to=price_to,
+            engine_volume_from=engine_volume_from,
+            engine_volume_to=engine_volume_to,
+        )
+        return self._page(raw, page, compact)
+
+    def get_ad(
+        self, ad_id: int, ad_type: str = "recommerce", raw: bool = False
+    ) -> dict[str, Any]:
+        """Fetch the full listing for a single ad.
+
+        For ``recommerce`` listings the React-router hydration blob is reduced to
+        the useful ``itemData`` payload unless ``raw`` is set.
+        """
+        ad_class = AD_CLASSES.get(ad_type)
+        if ad_class is None:
+            raise ValueError(f"Unknown ad type: {ad_type!r}. Valid: {', '.join(AD_TYPES)}")
+
+        payload = self._api.get_ad(ad_class(int(ad_id)))
+        if raw or ad_type != "recommerce":
+            return payload
+        return _slim_recommerce(payload)
+
+    def paginate(
+        self,
+        fetch: Callable[[int], Page],
+        *,
+        start_page: int = 1,
+        max_pages: int = 20,
+    ) -> Iterator[Page]:
+        """Yield consecutive pages from a ``fetch(page_number) -> Page`` callable."""
+        page_no = start_page
+        for _ in range(max_pages):
+            page = fetch(page_no)
+            yield page
+            if not page.items:
+                return
+            if page.last_page is not None and page_no >= page.last_page:
+                return
+            page_no += 1

blocket_toolkit/enums.py

@@ -0,0 +1,114 @@
+"""Name and value resolution for the blocket_api enumerations."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TypeVar
+
+from blocket_api import (
+    BoatSortOrder,
+    BoatType,
+    CarColor,
+    CarModel,
+    CarSortOrder,
+    CarTransmission,
+    CarWheelDrive,
+    Category,
+    Location,
+    McModel,
+    McSortOrder,
+    McType,
+    SortOrder,
+    SubCategory,
+)
+
+E = TypeVar("E", bound=Enum)
+
+__all__ = [
+    "BoatSortOrder",
+    "BoatType",
+    "CarColor",
+    "CarModel",
+    "CarSortOrder",
+    "CarTransmission",
+    "CarWheelDrive",
+    "Category",
+    "Location",
+    "McModel",
+    "McSortOrder",
+    "McType",
+    "SortOrder",
+    "SubCategory",
+    "enum_items",
+    "resolve",
+    "resolve_many",
+    "subcategories_of",
+]
+
+
+def _slug(token: str) -> str:
+    return token.strip().upper().replace(" ", "_").replace("-", "_")
+
+
+def resolve(enum_cls: type[E], token: str) -> E:
+    """Resolve a user token to an enum member.
+
+    Accepts the member name case-insensitively (spaces and dashes are treated as
+    underscores) or the raw Blocket value, e.g. ``"elektronik_och_vitvaror"``,
+    ``"Elektronik och vitvaror"`` or ``"0.93"``.
+    """
+    if not isinstance(token, str) or not token.strip():
+        raise ValueError(f"Empty value for {enum_cls.__name__}")
+
+    key = _slug(token)
+    if key in enum_cls.__members__:
+        return enum_cls[key]
+
+    raw = token.strip()
+    for member in enum_cls:
+        if str(member.value) == raw:
+            return member
+
+    names = ", ".join(_names(enum_cls))
+    raise ValueError(
+        f"Unknown {enum_cls.__name__}: {token!r}. Valid names or ids: {names}"
+    )
+
+
+def resolve_many(enum_cls: type[E], tokens: list[str] | None) -> list[E]:
+    """Resolve a list of tokens, flattening comma-separated values."""
+    if not tokens:
+        return []
+    out: list[E] = []
+    for token in tokens:
+        for part in str(token).split(","):
+            part = part.strip()
+            if part:
+                out.append(resolve(enum_cls, part))
+    return out
+
+
+def _names(enum_cls: type[Enum]) -> list[str]:
+    return [m.name for m in enum_cls]
+
+
+def enum_items(enum_cls: type[E]) -> list[dict[str, object]]:
+    """Return an enum as a sorted list of ``{"name", "id"}`` dicts."""
+    return sorted(
+        ({"name": m.name, "id": str(m.value)} for m in enum_cls),
+        key=lambda item: str(item["name"]),
+    )
+
+
+def subcategories_of(category: Category) -> list[SubCategory]:
+    """Return the subcategories that belong to a category.
+
+    Blocket encodes the hierarchy in the ids: a category ``0.93`` has
+    subcategories ``1.93.<n>``.
+    """
+    prefix = f"0.{str(category.value).split('.')[-1]}"
+    return [
+        sub
+        for sub in SubCategory
+        if f"0.{str(sub.value).split('.')[1]}" == prefix
+    ]

blocket_toolkit/format.py

@@ -0,0 +1,96 @@
+"""Output rendering: JSON, JSON-lines and plain text tables."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+LISTING_COLUMNS = ("id", "price", "heading", "location", "url")
+CAR_COLUMNS = ("id", "price", "heading", "year", "mileage", "location", "url")
+BOAT_COLUMNS = ("id", "price", "heading", "year", "length", "location", "url")
+MC_COLUMNS = ("id", "price", "heading", "year", "volume", "location", "url")
+OPTION_COLUMNS = ("name", "id")
+
+MAX_CELL = 60
+
+
+def render_json(data: Any) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=False, default=str)
+
+
+def render_jsonl(items: list[Any]) -> str:
+    return "\n".join(
+        json.dumps(item, ensure_ascii=False, default=str) for item in items
+    )
+
+
+def _cell(value: Any) -> str:
+    if value is None or value == "":
+        return "-"
+    if isinstance(value, (dict, list, tuple)):
+        value = json.dumps(value, ensure_ascii=False, default=str)
+    text = str(value).replace("\n", " ").strip()
+    if len(text) > MAX_CELL:
+        text = text[: MAX_CELL - 1] + "…"
+    return text
+
+
+def render_table(rows: list[dict[str, Any]], columns: tuple[str, ...]) -> str:
+    if not rows:
+        return "(no results)"
+
+    header = [column.upper() for column in columns]
+    cells = [[_cell(row.get(column)) for column in columns] for row in rows]
+
+    widths = [
+        max(len(header[i]), *(len(row[i]) for row in cells)) for i in range(len(columns))
+    ]
+
+    lines = ["  ".join(header[i].ljust(widths[i]) for i in range(len(columns)))]
+    lines.append("  ".join("-" * widths[i] for i in range(len(columns))))
+    for row in cells:
+        lines.append("  ".join(row[i].ljust(widths[i]) for i in range(len(columns))))
+    return "\n".join(lines)
+
+
+def render_pairs(data: dict[str, Any]) -> str:
+    lines: list[str] = []
+    for key, value in data.items():
+        if isinstance(value, (dict, list, tuple)):
+            rendered = render_json(value)
+        elif value is None or value == "":
+            rendered = "-"
+        else:
+            rendered = str(value)
+        lines.append(f"{key}: {rendered}")
+    return "\n".join(lines)
+
+
+def render(items: Any, output: str, columns: tuple[str, ...] = LISTING_COLUMNS) -> str:
+    """Render ``items`` in the requested format.
+
+    ``items`` may be a ``Page`` (or its ``as_dict``), a list of records, or a
+    plain dict.
+    """
+    if output == "jsonl":
+        rows = items["items"] if isinstance(items, dict) and "items" in items else items
+        if isinstance(rows, dict):
+            rows = [rows]
+        return render_jsonl(rows)
+    if output == "table":
+        if isinstance(items, dict) and "items" in items:
+            return render_table(items["items"], columns)
+        if isinstance(items, list):
+            return render_table(items, columns)
+        if isinstance(items, dict):
+            sections = [
+                f"# {key}\n" + render_table(value, tuple(value[0].keys()))
+                for key, value in items.items()
+                if isinstance(value, list) and value and isinstance(value[0], dict)
+            ]
+            if sections:
+                return "\n\n".join(sections)
+            if all(not isinstance(v, (dict, list)) for v in items.values()):
+                return render_pairs(items)
+            return render_table([items], columns)
+    return render_json(items)

blocket_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: blocket-toolkit
+Version: 0.1.0
+Summary: Search all of Blocket.se from the terminal: general items, cars, boats and motorcycles.
+Project-URL: Homepage, https://github.com/dojje/blocket-toolkit
+Project-URL: Repository, https://github.com/dojje/blocket-toolkit
+Project-URL: Issues, https://github.com/dojje/blocket-toolkit/issues
+Author: Daniel Hidefjäll
+License-Expression: MIT
+License-File: LICENSE
+Keywords: blocket,boats,cars,cli,marketplace,second-hand,sweden
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: blocket-api>=0.5.2
+Requires-Dist: httpx>=0.28.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# blocket-toolkit
+
+Search **all of Blocket.se** from the terminal: general items (*torget*), cars, boats
+and motorcycles, with clean JSON output that is easy to pipe into other tools or hand
+to an LLM.
+
+Built on top of the [`blocket-api`](https://pypi.org/project/blocket_api/) Python
+package.
+
+## Features
+
+- **Everything on Blocket**: torget, cars, boats, motorcycles and full ad details.
+- **Full filter surface**: category + subcategory, all 21 regions, price, year, milage,
+  horsepower, colour, gearbox, wheel drive, length, engine volume, brand/model.
+- **AI-friendly output**: compacted, flat JSON by default; `jsonl` and text `table` when
+  you want them.
+- **Self-documenting enums**: every category, subcategory, region, brand and model can
+  be listed or resolved by name *or* by Blocket's internal id.
+- **Pagination**: `--page`, `-n/--limit`, or `--all`.
+
+## Install
+
+```bash
+uv tool install blocket-toolkit          # or: pip install blocket-toolkit
+```
+
+From a checkout:
+
+```bash
+git clone https://github.com/dojje/blocket-toolkit
+cd blocket-toolkit
+uv venv && uv pip install -e '.[dev]'
+```
+
+## Quick start
+
+```bash
+blocket-toolkit search "kindle" --price-max 800 --sort price_asc
+
+blocket-toolkit search "grafikkort" -c elektronik_och_vitvaror --sub-category datorer -n 5
+
+blocket-toolkit cars --model volvo --year-min 2018 --mileage-max 12000 --sort mileage_asc
+
+blocket-toolkit boats --type segelbat_motorseglare --length-min 30
+
+blocket-toolkit mc --model yamaha --engine-min 600 --price-max 80000
+
+blocket-toolkit ad 20851738 --type recommerce
+```
+
+Every command accepts `-o json|jsonl|table` (default `json`).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `search <query>` | General items on torget |
+| `cars [query]` | Used cars |
+| `boats [query]` | Used boats |
+| `mc [query]` | Used motorcycles |
+| `ad <ad_id> --type ...` | Full details for one listing |
+| `categories` | All 11 top-level categories |
+| `subcategories [-c CATEGORY]` | All subcategories, optionally for one category |
+| `locations` | All 21 Swedish regions |
+| `car-options` | Car brands, colours, gearboxes, wheel drives, sort orders |
+| `boat-options` | Boat types and sort orders |
+| `mc-options` | MC brands, types and sort orders |
+
+Run `blocket-toolkit <command> --help` for the full filter list.
+
+### Common flags
+
+| Flag | Applies to | Meaning |
+|---|---|---|
+| `-c, --category` | `search` | Category name or id (e.g. `elektronik_och_vitvaror` or `0.93`) |
+| `--sub-category` | `search` | Subcategory name or id (mutually exclusive with `--category`) |
+| `-l, --location` | all searches | Region(s), repeatable or comma-separated (`-l stockholm,skane`) |
+| `--sort` | all searches | Sort order; valid values depend on the command |
+| `--price-min/--price-max` | `search`, `cars`, `boats`, `mc` | Price range in SEK |
+| `--newer-than HOURS` | `search` | Only ads published within the last N hours |
+| `--page`, `-n/--limit`, `--all` | all searches | Pagination |
+| `-o, --output` | everything | `json` (default), `jsonl`, `table` |
+| `--raw` | searches | Return Blocket's raw objects instead of compacted records |
+
+> `--price-min/--price-max` and `--newer-than` are applied **client-side** for torget,
+> because Blocket's general search endpoint has no server-side price filter. For cars,
+> boats and motorcycles the price range is sent to the API.
+
+## Output shape
+
+Search commands return:
+
+```json
+{
+  "page": 1,
+  "last_page": 20,
+  "total": 1187,
+  "count": 40,
+  "items": [
+    {
+      "id": 20851738,
+      "heading": "Kindle Paperwhite 11th gen",
+      "price": 750,
+      "location": "Stockholm",
+      "url": "https://www.blocket.se/annons/20851738",
+      "image_url": "https://...",
+      "timestamp": 1700000000000,
+      "published_at": "2023-11-14T22:13:20+00:00"
+    }
+  ]
+}
+```
+
+`ad` returns the full payload for a single listing.
+
+## Finding valid filter values
+
+```bash
+blocket-toolkit categories -o table
+blocket-toolkit subcategories -c elektronik_och_vitvaror -o table
+blocket-toolkit locations -o table
+blocket-toolkit car-options -o table
+```
+
+Values are resolved case-insensitively and accept spaces or dashes, so
+`ELEKTRONIK_OCH_VITVAROR`, `elektronik och vitvaror` and `0.93` are all valid.
+
+## Development
+
+```bash
+uv venv && uv pip install -e '.[dev]'
+pytest                 # unit tests (no network)
+pytest -m live         # smoke tests against the real Blocket API
+ruff check .
+```
+
+## Notes and limitations
+
+- Blocket has no official public API; this uses the same internal endpoints as the
+  website. Be gentle: don't hammer it with `--all --max-pages 200`.
+- Torget's search endpoint does not accept a result count, so `-n/--limit` and
+  `--price-*` are applied after fetching.
+- `ad` for `car`/`boat`/`mc` scrapes the mobility page and returns somewhat less
+  structured data than `recommerce`.
+
+## Credits
+
+- [`blocket-api`](https://github.com/dunderrrrrr/blocket_api) by dunderrrrrr, the
+  underlying API wrapper.
+- Blocket.se, obviously, for the data.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

blocket_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+blocket_toolkit/__init__.py,sha256=tJDhnno_lGNc7B2boY9VAi3Hcl7FJd8WZqtIDKfDCR4,182
+blocket_toolkit/cli.py,sha256=-RRgUvOFWW2V5L8reMqzqvMcvaBpmUHjvIO_e9pQjqs,17897
+blocket_toolkit/client.py,sha256=OlasMXRCgwSp6dqtqEdM4r8VhGV7gH4M2negzdgo4Xo,10688
+blocket_toolkit/enums.py,sha256=hgxPdoj1Ltys6wwkfSkpHHJasCi-l1m4U24Q368WaZg,2824
+blocket_toolkit/format.py,sha256=9fUuyirq-N5fn-nmL4CI9wRxYrvQTlxG99Q7RePZ7cY,3363
+blocket_toolkit-0.1.0.dist-info/METADATA,sha256=CDK8_w6NuMkENTYfBzNq8bdSE4-vDBi4JI3XCXLHAKI,6221
+blocket_toolkit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+blocket_toolkit-0.1.0.dist-info/entry_points.txt,sha256=Wxmc6ahNJscHZgdUUfL8b-LN-vtNskjdUlugF7tI4HM,61
+blocket_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=SU_3mlh6-ov9lPRM4NDhhhS-O6TeJyQRl8-yqYSiICU,1074
+blocket_toolkit-0.1.0.dist-info/RECORD,,

blocket_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

blocket_toolkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+blocket-toolkit = blocket_toolkit.cli:main

blocket_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Hidefjäll
+
+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.