bgg-search 0.1.0__tar.gz

bgg_search-0.1.0/.bandit

@@ -0,0 +1,3 @@
+exclude_dirs:
+  - tests
+  - .venv

bgg_search-0.1.0/.coveragerc

@@ -0,0 +1,7 @@
+[run]
+source = bgg_search
+branch = True
+
+[report]
+fail_under = 95
+show_missing = True

bgg_search-0.1.0/.cspell.yaml

@@ -0,0 +1,44 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/streetsidesoftware/cspell/main/packages/cspell-types/cspell.schema.json
+
+version: "0.2"
+language: en-US
+
+dictionaries:
+  - python
+  - html
+  - xml
+  - bash
+  - markdown
+  - software-terms
+
+words:
+  - bgg
+  - boardgame
+  - boardgamegeek
+  - xmlapi
+  - httpx
+  - pydantic
+  - pytest
+  - mypy
+  - ruff
+  - pyproject
+  - editable
+  - geek
+  - conftest
+  - stdlib
+  - integ
+  - Arnauld
+  - Muysewinkel
+  - coveragerc
+  - pytest-cov
+
+ignorePaths:
+  - .git/**
+  - .venv/**
+  - "**/__pycache__/**"
+  - "**/*.egg-info/**"
+  - dist/**
+  - build/**
+
+ignoreRegExpList:
+  - "https?://[^\\s]+"

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

@@ -0,0 +1,16 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  tox:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install tox~=4.55.0
+      - run: tox

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

@@ -0,0 +1,21 @@
+name: Publish
+
+on:
+  push:
+    tags: ["version/*"]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

bgg_search-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Virtualenvs
+.venv/
+
+# Build artifacts
+dist/
+*.egg-info/
+
+# Caches
+__pycache__/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage

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

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: tox
+        name: tox
+        entry: .venv/bin/tox
+        language: system
+        pass_filenames: false
+        always_run: true

bgg_search-0.1.0/AGENTS.md

@@ -0,0 +1,268 @@
+# BGG Search — Agent Guide
+
+## Project context
+
+`bgg-search` is a personal Python package for querying [BoardGameGeek](https://boardgamegeek.com) (BGG).
+It wraps the BGG XML API2 and exposes:
+
+- a clean, reusable Python API for searching games, retrieving game details, and filtering results;
+- a generic CLI for interacting with the BGG API from the command line.
+
+This is a personal project; prioritize clarity and correctness over enterprise-grade robustness.
+
+Rationale behind key choices is documented in [DECISIONS.md](DECISIONS.md).
+The project initiation workflow and branch/version map are documented in [PROCESS.md](PROCESS.md).
+
+### Repository layout (target structure)
+
+```
+bgg-search/
+├── src/
+│   └── bgg_search/          # installable package
+│       ├── __init__.py      # explicit public API surface
+│       ├── models.py        # pure domain dataclasses
+│       ├── exceptions.py    # all domain exceptions
+│       ├── _protocol.py     # BggClientProtocol (typing.Protocol)
+│       ├── _client.py       # concrete httpx client + XML parsing
+│       ├── search.py        # use-case layer
+│       └── cli.py           # CLI adapter (I/O only)
+├── tests/
+│   ├── conftest.py
+│   ├── unit/                # fast, purely local tests
+│   │   ├── conftest.py
+│   │   └── test_*.py
+│   └── integ/               # slow, hits the real BGG API
+│       ├── conftest.py
+│       └── test_*.py
+├── requirements/
+│   ├── runtime.in           # package runtime deps (unpinned spec)
+│   ├── runtime.txt          # locked runtime deps
+│   ├── dev.in               # tooling: tox, ruff, mypy, bandit (unpinned spec)
+│   ├── dev.txt              # locked tooling deps
+│   ├── unit.in              # unit test deps (unpinned spec)
+│   ├── unit.txt             # locked unit test deps
+│   ├── integ.in             # integ test deps (unpinned spec)
+│   ├── integ.txt            # locked integ test deps
+│   ├── audit.in             # pip-audit (unpinned spec)
+│   └── audit.txt            # locked audit deps
+├── pyproject.toml           # package metadata and build system only
+├── CHANGELOG.md             # user-facing change history (Keep a Changelog format)
+├── DECISIONS.md             # rationale behind key design and package choices
+├── PROCESS.md               # project initiation workflow and branch/version map
+├── README.md                # public-facing project documentation
+└── AGENTS.md                # guide for AI agents (this file)
+```
+
+Transient files (not always present):
+
+| File | Scope | Purpose |
+|------|-------|---------|
+| `ROADMAP.md` | `main` | succession of phases toward MVP |
+| `PHASE_PLAN.md` | `main` | decomposition of the current phase |
+| `PLAN.md` | feature branch | steps for the current feature/change |
+
+## Development environment
+
+Dependencies are managed with **uv**. Each context has its own requirements file (see `requirements/`).
+`.in` files are the unpinned specs; `.txt` files are the locked versions generated from them.
+
+```bash
+# create and activate a virtual environment
+uv venv --python 3.13 && source .venv/bin/activate
+
+# install the package in editable mode with locked dev deps
+uv pip install -e . -r requirements/dev.txt
+
+# register the pre-commit hook (once per clone)
+pre-commit install
+```
+
+There is no `setup.py`. `pyproject.toml` contains package metadata and build system only; all dependency declarations live in `requirements/`.
+
+### Commands
+
+All tasks run through **tox**, which executes each step in an isolated virtualenv.
+
+| Task | Command |
+|------|---------|
+| Full quality gate (lint + type + security + unit tests) | `tox` |
+| Lint / format | `tox -e lint` |
+| Type-check | `tox -e type` |
+| Security scan (bandit) | `tox -e security` |
+| Unit tests | `tox -e unit` |
+| Integration tests | `tox -e integ` |
+| Dependency audit (pip-audit) | `tox -e audit` |
+| Re-lock all dependencies | `tox -e lock` |
+
+Run `tox` before every commit.
+Before each release, also run: `tox -e lock`, then `tox -e audit`, then `tox -e integ`.
+
+To fix formatting issues reported by `tox -e lint`, run `ruff format .` locally then re-run tox.
+
+### Tool configuration
+
+Prefer individual configuration files per tool (e.g., `.bandit`, `mypy.ini`, `ruff.toml`) over consolidating everything into `pyproject.toml`. Use `pyproject.toml` only for package metadata and build system configuration.
+
+## Development workflow
+
+Every change (feature, bug fix, refactoring, …) follows this process:
+
+1. **Create a branch**: cut a short-lived branch from `main`, named after the intent (e.g., `feat/search-by-rank`).
+2. **Write a plan**: create `PLAN.md` on the branch; describe the steps before writing any code. One step = one future commit. Commit `PLAN.md` immediately so it is tracked and stays branch-local. (`PLAN.md` is the feature-level plan; the phase-level plan lives in `PHASE_PLAN.md` on `main` — see [PROCESS.md](PROCESS.md).)
+3. **Review the plan**: adapt it before starting execution.
+4. **Execute step by step** — for each step in `PLAN.md`:
+   - Edit code and adapt tests.
+   - Review the changes.
+   - Run `tox` (full quality gate).
+   - Loop until clean.
+   - Commit.
+5. **Remove `PLAN.md`**: delete it in a dedicated commit (`chore(PLAN.md): remove branch-local plan before merge`). This ensures it is never merged into `main`.
+6. **Merge and delete the branch**: merge into `main` with `--no-ff`, then delete the branch (`git branch -d <branch>`).
+7. **Run integration tests**: `tox -e integ`; loop until clean.
+8. **Release**: bump version (Y for a feature or significant fix; Z for a hotfix on a past version), update `CHANGELOG.md`, run `tox -e lock && tox -e audit`, tag `version/X.Y.Z`.
+
+### Step quality rules
+
+Each step (commit) must be:
+- **Localized**: touch as few files as possible — ideally one; as few sections within that file as possible.
+- **Consistent**: all changes in the step serve a single, coherent purpose.
+- **Clean**: the codebase must pass `tox` at the end of every step, with no known errors left behind.
+
+`PLAN.md` is branch-local and must **not** be merged into `main` (enforced by step 5 above).
+
+## Architecture
+
+### Modularization
+
+Modules are organized in layers. Inner layers never import from outer layers:
+
+```
+cli.py → search.py → _protocol.py → models.py
+                   ↘ exceptions.py
+_client.py → _protocol.py, models.py, exceptions.py
+```
+
+Rules:
+
+- `models.py` and `exceptions.py`: no imports from this package.
+- `_protocol.py`: imports `models.py` only; defines `BggClientProtocol` (`typing.Protocol`).
+- `_client.py`: internal (underscore prefix); never imported directly by callers; implements `BggClientProtocol`.
+- `search.py`: depends on `BggClientProtocol`, not on `_client.py`; receives a client instance via parameter.
+- `cli.py`: pure I/O adapter — parse args, call `search.py`, format output; no business logic.
+- `__init__.py`: explicitly re-exports the public API; adding internal modules never accidentally becomes public.
+
+### Code conventions
+
+- **Python 3.13**; use built-in `tomllib`, `match`/`case`, `TypeAlias`, etc. where appropriate.
+- Public functions and classes must have type annotations; internal helpers may omit them only when obvious.
+- No comments that restate what the code already says. Comment the *why*, not the *what*.
+- Raise domain-specific exceptions (subclass `BggSearchError`) instead of leaking `httpx` errors.
+
+### Package selection rules
+
+When choosing packages, apply these rules in order:
+
+1. **Prefer stdlib** over external packages when the functionality is equivalent.
+2. **Prefer well-maintained external packages**: large community, frequent and recent releases.
+3. **Prefer packages with fewer transitive dependencies** when other criteria are equal.
+
+Concretely for this project:
+- XML parsing → `xml.etree.ElementTree` (stdlib), not `lxml` or `beautifulsoup4`
+- HTTP → `httpx` (active community, minimal deps) over `requests` (heavier dep tree) or `aiohttp`
+- Data models → `dataclasses` (stdlib) when validation is not needed; `pydantic>=2` only when input validation is required
+- Date/time → `datetime` (stdlib), not `arrow` or `pendulum`
+
+### Testing
+
+Use `pytest`; never use `unittest` directly.
+Aim for behavior coverage, not line coverage — test what the public API promises, not implementation details.
+
+#### Unit tests (`tests/unit/`)
+
+- Purely local: no network, no filesystem side-effects.
+- Mock HTTP with `httpx.MockTransport`; do **not** add `pytest-httpx`.
+- One file per source module: `tests/unit/test_client.py`, `tests/unit/test_search.py`, etc.
+- Must be fast enough to run after every code change.
+
+#### Integration tests (`tests/integ/`)
+
+- Hit the real BGG API; require network access.
+- Run only explicitly (e.g., before a release) — never triggered automatically.
+- Keep the number of requests minimal: one test must not make more API calls than strictly necessary.
+- Add a `time.sleep` between requests to avoid flooding the BGG API.
+- One file per high-level scenario: `tests/integ/test_search_flow.py`, etc.
+
+### Things to avoid
+
+- Do **not** add logging configuration at module level; leave that to the caller.
+- Do **not** cache BGG responses unless caching is explicitly requested.
+- Do **not** commit `.venv/`, `__pycache__/`, or `*.egg-info/` (ensure `.gitignore` covers them).
+
+## Conventions
+
+### Language
+
+Use American English for text (messages, documentation, commits...)
+
+### Commit format
+
+Use commits of the form `<action>(<scope>):<description>`, where:
+
+- `<action>` is one of "add", "upd", "feat", "refactor", "chore"...
+- `<scope>` is a compact spec of the files full path (relative to project root)  
+  (exceptionally it may be omitted, when the commit concerns the whole project);  
+  optionally followed by ` > <location>` to pinpoint the change within the file  
+  (e.g. a class name, function name, or config section): `src/bgg_search/client.py > BggClient.search`
+- `<description>` is a short sentence describing the modification (do not repeat the action)
+
+Do not add `Co-Authored-By` trailers. AI involvement is documented once in this file.
+
+### Version management
+
+Versions follow [Semantic Versioning](https://semver.org) (`MAJOR.MINOR.PATCH`):
+
+- **MAJOR**: incompatible API change.
+- **MINOR**: new feature, or a significant fix on the latest version.
+- **PATCH**: hotfix backported to a past version (branch cut from an old release tag, not `main`).
+
+Between releases the version carries the `.dev0` suffix (PEP 440), signalling that the code is not yet a stable build. The canonical workflow:
+
+1. Before release: set version to `X.Y.Z` in `pyproject.toml`, update `CHANGELOG.md`, commit, tag `version/X.Y.Z`.
+2. After release: immediately bump to `X.(Y+1).0.dev0` and commit.
+
+The version is declared once, in `pyproject.toml` (`version = "..."`); the package exposes it via `importlib.metadata`:
+
+```python
+from importlib.metadata import version
+__version__ = version("bgg-search")
+```
+
+Do **not** hard-code the version string anywhere else in the source.
+
+### Changelog
+
+`CHANGELOG.md` follows the [Keep a Changelog](https://keepachangelog.com) format (version 1.0.0).
+
+Rules:
+
+- Always keep an `## [Unreleased]` section at the top.
+- Add an entry under `[Unreleased]` for every user-facing change (new feature, fix, removed behavior). Internal refactors and tooling changes do not need an entry.
+- Use the standard subsections: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
+- On release: rename `[Unreleased]` to `[x.y.z] - YYYY-MM-DD` and open a fresh `[Unreleased]` section above it.
+- Do **not** edit past release sections.
+
+## Reference
+
+### BGG XML API2
+
+Base URL: `https://boardgamegeek.com/xmlapi2/`
+
+Key endpoints used in this project:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `search?query=<q>&type=boardgame` | Search games by name |
+| `thing?id=<id>&stats=1` | Fetch full game details |
+| `collection?username=<u>&own=1` | Fetch a user's owned games |
+
+The API is unauthenticated and rate-limited; add a short `time.sleep` between bulk requests.

bgg_search-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-07
+
+### Added
+
+- Initial release of `bgg-search`: a Python client and CLI for the BoardGameGeek XML API.
+- Package installable from PyPI; requires Python ≥ 3.13.
+- `bgg_search.__version__` exposes the installed package version.
+- MIT license.

bgg_search-0.1.0/DECISIONS.md

@@ -0,0 +1,154 @@
+# Design decisions
+
+Rationale behind key choices made in this project.
+See [AGENTS.md](AGENTS.md) for the actionable rules derived from these decisions.
+
+---
+
+## uv as dependency manager
+
+`uv` replaces `pip` + `venv` for environment and dependency management.
+
+- **Speed**: written in Rust; resolves and installs orders of magnitude faster than pip.
+- **Single tool**: handles virtualenv creation (`uv venv`), installation (`uv pip install`), and locking (`uv pip compile`) — no need for pip-tools alongside pip.
+- **pip-compatible**: `uv pip compile` produces standard `requirements.txt` files; `uv pip install -r` accepts them. No lock-in to a proprietary format.
+- **Actively maintained**: developed by Astral (same team as ruff), large and fast-growing community.
+
+The `.in` / `.txt` split (spec vs. lock) follows the pip-tools convention, which uv fully supports.
+
+---
+
+## Individual tool configuration files over pyproject.toml
+
+Each tool (`ruff`, `mypy`, `bandit`, `tox`, …) gets its own configuration file rather than a consolidated `[tool.*]` section in `pyproject.toml`.
+
+Reasons:
+
+- **Discoverability**: a developer (or agent) looking for ruff's config opens `ruff.toml` directly; they do not need to know which tools happen to store config in `pyproject.toml` and scroll through an unrelated file.
+- **Separation of concerns**: `pyproject.toml` is the package manifest (metadata, dependencies, build system). Mixing tool config into it conflates two distinct responsibilities.
+- **Diff clarity**: changes to a tool's config appear in that tool's file, not buried in `pyproject.toml` alongside unrelated edits.
+- **Portability**: individual config files work even when the tool is invoked outside the Python packaging context (e.g., in a pre-commit hook, a CI step, or a standalone script).
+
+`pyproject.toml` retains only what belongs there: `[project]` metadata (including runtime `dependencies`) and `[build-system]`.
+
+---
+
+## Python 3.13 as target version
+
+Criteria for choosing a Python version (in order):
+
+1. **Active support window**: target a version with several years of security fixes remaining; avoid versions nearing EOL.
+2. **Ecosystem readiness**: all dependencies must support the target version.
+3. **Feature set**: prefer newer versions for language improvements and performance gains.
+4. **Project type**: a published library must support older versions for broad compatibility; a personal tool can freely track the latest stable.
+
+As of June 2026, Python 3.13 is the latest stable release (EOL Oct 2029), all project dependencies support it, and 3.14 is still pre-release. There is no reason to stay on an older version for a personal tool.
+
+The version pin (`3.13`, not `≥ 3.13`) is intentional: it makes the runtime explicit and reproducible. Upgrade deliberately when 3.14 stabilizes and the ecosystem catches up.
+
+---
+
+## Modular architecture and separation of concerns
+
+The package is organized in layers with a strict inward dependency direction. Each decision below addresses a specific maintainability or testability concern.
+
+### Domain models and exceptions are dependency-free
+
+`models.py` and `exceptions.py` import nothing from this package or from external libraries.
+This makes them the stable core: any other module can import them without risk of circular imports,
+and they can be read and understood without knowledge of httpx, XML, or argparse.
+
+### Abstract client protocol (`_protocol.py`)
+
+`search.py` (the use-case layer) depends on `BggClientProtocol` — a `typing.Protocol` — rather
+than on the concrete `_client.py`. This decouples business logic from HTTP and XML details:
+
+- Unit tests for `search.py` pass a fake/stub client with no httpx involved.
+- The concrete client can be replaced (e.g., async variant, cached variant) without touching `search.py`.
+- The protocol is the contract; the client is an implementation detail.
+
+### Concrete client is internal (`_client.py`)
+
+The underscore prefix signals that `_client.py` is not part of the public API.
+Callers (including `cli.py`) never import it directly; they receive a client instance via
+dependency injection. This means:
+
+- XML parsing is fully encapsulated: swapping the parser is a one-file change.
+- The HTTP layer can evolve (e.g., connection pooling, retries) without rippling through the codebase.
+
+### CLI is a pure I/O adapter (`cli.py`)
+
+`cli.py` contains no business logic. It only:
+1. Parses command-line arguments.
+2. Calls `search.py` functions.
+3. Formats and prints output.
+
+This separation means the Python API and the CLI are independently testable and independently
+evolvable. A future GUI or REST wrapper would reuse `search.py` without touching `cli.py`.
+
+### Explicit public API (`__init__.py`)
+
+`__init__.py` explicitly re-exports everything that is public. Adding a new internal module
+(e.g., a caching layer) never accidentally leaks into the package's public surface.
+Consumers of the library import from `bgg_search`, not from `bgg_search._client`.
+
+---
+
+## dataclasses over pydantic (default)
+
+Use `dataclasses` (stdlib) for internal data structures where no input validation is needed.
+Reach for `pydantic>=2` only when validating external input (e.g., deserializing API responses
+where field types or constraints must be enforced at runtime).
+
+This applies the **prefer stdlib** rule from the [Package selection policy](#package-selection-policy).
+
+---
+
+## Package selection policy
+
+**Rules (in priority order):**
+
+1. Prefer stdlib over external packages when the functionality is equivalent.
+2. Among external packages, prefer those with a large community and frequent recent releases.
+3. Among equally suitable packages, prefer those with fewer transitive dependencies.
+
+---
+
+## pytest over unittest
+
+`unittest` is stdlib, but its functionality is not equivalent to `pytest`:
+
+- **Fixtures**: `pytest` fixture injection is composable and scope-aware; `unittest` setUp/tearDown is flat and class-scoped.
+- **Parametrize**: `@pytest.mark.parametrize` is concise; the `unittest` equivalent (`subTest` or external libs) is verbose.
+- **Assertions**: `pytest` rewrites plain `assert` statements and produces detailed diffs; `unittest` requires `assertEqual`, `assertIn`, etc.
+- **Ecosystem**: plugins (`pytest-cov`, `pytest-xdist`, …) integrate naturally.
+
+`pytest` has a very large community, is released frequently, and has minimal transitive dependencies.
+The "prefer stdlib" rule does not apply here because the functionality is not equivalent.
+
+---
+
+## httpx.MockTransport over pytest-httpx
+
+`pytest-httpx` is a thin convenience layer on top of `httpx`'s own `MockTransport`.
+The built-in transport covers the same use case (intercept requests, return canned responses)
+with no extra dependency — applying the **prefer stdlib/built-in** and **fewer transitive dependencies**
+rules from the [Package selection policy](#package-selection-policy).
+
+The trade-off is a few more lines of fixture boilerplate in `tests/conftest.py`.
+
+---
+
+## httpx over requests
+
+`httpx` has a smaller transitive dependency tree than `requests` (**fewer transitive dependencies**),
+supports both sync and async out of the box, and is actively maintained with a large community
+(**well-maintained, frequent releases**) — see [Package selection policy](#package-selection-policy).
+
+---
+
+## xml.etree.ElementTree over lxml / beautifulsoup4
+
+The BGG XML API returns well-formed XML. The stdlib parser handles it without issues.
+Adding `lxml` or `beautifulsoup4` would introduce external dependencies for no gain —
+applying the **prefer stdlib** rule from the [Package selection policy](#package-selection-policy).

bgg_search-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnauld Van Muysewinkel
+
+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.