blocket-toolkit 0.1.0__tar.gz

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

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Check metadata and README rendering
+        run: uvx twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/blocket-toolkit
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+
+      - name: Generate PEP 740 attestations
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

blocket_toolkit-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Environments
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+
+# Output
+*.jsonl

blocket_toolkit-0.1.0/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.

blocket_toolkit-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,154 @@
+# 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/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "blocket-toolkit"
+version = "0.1.0"
+description = "Search all of Blocket.se from the terminal: general items, cars, boats and motorcycles."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Daniel Hidefjäll" }]
+keywords = ["blocket", "cli", "marketplace", "sweden", "second-hand", "cars", "boats"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+dependencies = ["blocket-api>=0.5.2", "httpx>=0.28.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://github.com/dojje/blocket-toolkit"
+Repository = "https://github.com/dojje/blocket-toolkit"
+Issues = "https://github.com/dojje/blocket-toolkit/issues"
+
+[project.scripts]
+blocket-toolkit = "blocket_toolkit.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/blocket_toolkit"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["live: tests that hit the real Blocket API (deselected by default)"]
+addopts = "-m 'not live'"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]